« Previous -
Version 10/11
(diff) -
Next » -
Current version
Bartosz SKOWRON -, 08/05/2009 10:27 am
forgot to add #!rst at the beginning
{{{
#!rst
====================
Your First Packets
====================
Introduction ============
This tutorial is meant for everybody who wants to start using UMPA.
You will learn how to build and send your packets.
Examples
--------
Check examples/* directory for already written full code examples.
They are also available on http://trac.umitproject.org/browser/branch/UMPA/examples/
..2, 3...GO! ============
import UMPA
-----------
Ok, at the beginning we need to import UMPA.
.. code-block:: python
In [1]: import umit.umpa
In [2]:Pretty easy, isn't it? ;-)
After that, we have 2 classes provided: ``Packet`` and ``Socket``.
The former one is a protocol container. If you want to build new packet,
you have to create a Packet's object. We will use it everytime when we would
like to build packets.
``Socket`` is needed at the end of the process. We will back
to this point later.
security issue
--------------
To create RAW_SOCKET we need SUID (root priviliges), but for normal usage
usually it's not necessary (depends what you are doing with your application).
So, it's recommended to drop the priviliges and up them only if needed.
``umit.umpa.utils`` package provides some useful modules, and
the ``umit.umpa.utils.security`` module provides functions which are usefull
in this case.
All we need is to import the module and call the function. Later when we need
to create a new socket (or to do something other what rely on SUID) we call
another function from the module (it will be describe later).
.. code-block:: python
In [2]: import umit.umpa.utils.security
In [3]: umit.umpa.utils.security.drop_priviliges()
In [4]:Please note that our process has to be run as a root. Otherwise, an excaption
will raise:
.. code-block:: python
In [1]: import umit.umpa.utils.security
In [2]: umit.umpa.utils.security.drop_priviliges()Run the program with root-priviliges.---------------------------------------------------------------------------
<type 'exceptions.OSError'> Traceback (most recent call last)/home/xsx/UMPA/<ipython console> in <module>()/home/xsx/UMPA/umpa/utils/security.py in drop_priviliges()
48 nobody_id = pwd.getpwnam('nobody')[2]
49 try:
---> 50 os.seteuid(nobody_id)
51 except OSError:
52 print >> sys.stderr, "Run the program with root-priviliges.\n"<type 'exceptions.OSError'>: [Errno 1] Operation not permittedIn [3]:protocols
---------
Let's build our first packet. There are several ways to do that. We can include
each protocols as an arguments in ``Packet()`` constructor, or just build
them independent. The second case is more interesting.
First, we need to import the ``umit.umpa.protocols`` package. If we don't know
which protocols are available, we can simple check it.
.. code-block:: python
In [4]: import umit.umpa.protocolsIn [5]: umit.umpa.protocols.get_all()
Out[5]:
{'IP': <class 'umit.umpa.protocols.IP.IP'>,
'Payload': <class 'umit.umpa.protocols.Payload.Payload'>,
'TCP': <class 'umit.umpa.protocols.TCP.TCP'>,
'UDP': <class 'umit.umpa.protocols.UDP.UDP'>}In [6]:There are two more functions (``get_globals()`` and ``get_locals()``). We will
talk about them in next tutorials. But ``get_all()`` is what you usually need.
OK, in our example we would like to build TCP/IP packet and UDP/IP.
Both packets with the same IP header.
IP protocol
-----------
.. code-block:: python
In [6]: ip = umit.umpa.protocols.IP(source_address="127.0.0.1")In [7]: ip.destination_address = (67,205,14,183)In [8]: list(ip.get_fields_keys())
Out[8]:
['_version',
'_ihl',
'type_of_service',
'_total_length',
'_identification',
'flags',
'_fragment_offset',
'time_to_live',
'_protocol',
'_header_checksum',
'source_address',
'destination_address',
'options',
'_padding']Ok, We've just created the IP instance. As you see, we can pass values directly
to constructor (``In [6]``) or pass them later (``In [7]``). Also, IP addresses
can be passed in two ways as a string or tuple (or list). To get list of
headers just call ``get_fields_key()`` method. But this method is a generator,
so in this case we need to cast it. Names convention is pretty simple.
Those names are taken from the RFCs documents.
.. note::
Some fields are started with the underscrored prefix. This has a special
meaning. These fields may auto-generate values. So usually, we don't need
to care about them. But if you want to modify them - feel free to break
your packets ;)TCP and Payload protocols
-------------------------
What next? TCP header and some payload for it..
.. code-block:: python
In [9]: tcp = umit.umpa.protocols.TCP()In [10]: tcp.source_port = 2958In [11]: tcp.destination_port = 0In [12]: tcp.set_flags('control_bits', syn=True)In [13]: payload = umit.umpa.protocols.Payload()In [14]: payload.data = "this is umpa!"In [15]:Completely simple so far, isn't it?
protocols container
-------------------
Ok, let's build a packet...
.. code-block:: python
In [15]: first_packet = umit.umpa.Packet(ip, tcp)In [16]: first_packet.include(payload)So, we passed 2 protocols into constructor, and included another one with the
`include()` method.
Please remember that including order is important. By default, we can't break
the OSI model, so protocols need to be packed in the proper order. Otherwise,
the ``UMPAStrictException`` will raise. If you want to break this rule, please
read about ``strict`` attribute of the Packet's object in later tutorials.
print statement
---------------
If we take a coffe break (longer than 5 hours) now, perhaps we will forget what
we built. Just print it!
.. code-block:: python
In [17]: print first_packet
Packet contains 3 protocols
+-< IP >
| \
| +-[ Version ] 4 (auto - 4)
| +-[ IHL ] None (auto - 5)
| +-[ TOS ]
| | \
| | -{ precedence0 } 0
| | -{ precedence1 } 0
| | -{ precedence2 } 0
| | -{ delay } 0
| | -{ throughput } 0
| | -{ relibility } 0
| | -{ reserved0 } 0
| | -{ reserved1 } 0
| | /
| \-[ TOS ] contains 8 bit flags
| +-[ Total Length ] None (auto - 0)
| +-[ Identification ] 0 (auto - 0)
| +-[ Flags ]
| | \
| | -{ reserved } 0
| | -{ df } 0
| | -{ mf } 0
| | /
| \-[ Flags ] contains 3 bit flags
| +-[ Fragment Offset ] 0 (auto - 0)
| +-[ TTL ] 64 (auto - 64)
| +-[ Protocol ] None (auto - 0)
| +-[ _Header Checksum ] 0 (auto - 0)
| +-[ Source Address ] 127.0.0.1
| +-[ Destination Address ] (67, 205, 14, 183)
| +-[ Options ]
| | \
| | /
| \-[ Options ] contains 0 bit flags
| + 0 (auto - 0)
\< IP > contains 14 fields
<umit.umpa.protocols.IP.IP object at 0xb78c2a4c>
+-< TCP >
| \
| +-[ Source Port ] 2958
| +-[ Destination Port ] 0
| +-[ Sequence Number ] None (auto - 0)
| +-[ Acknowledgment Number ] None (auto - 1)
| +-[ DataOffset ] None (auto - 5)
| +-[ Reserved ] 0 (auto - 0)
| +-[ Control Bits ]
| | \
| | -{ urg } 0
| | -{ ack } 0
| | -{ psh } 0
| | -{ rst } 0
| | -{ syn } 1
| | -{ fin } 0
| | /
| \-[ Control Bits ] contains 6 bit flags
| +-[ Window ] None (auto - 512)
| +-[ Checksum ] None (auto - 0)
| +-[ Urgent Pointer ] None (auto - 0)
| +-[ Options ]
| | \
| | /
| \-[ Options ] contains 0 bit flags
| + 0 (auto - 0)
\< TCP > contains 12 fields
<umit.umpa.protocols.TCP.TCP object at 0xb78e774c>
+-< Payload >
| \
| + this is umpa!
\< Payload > contains 1 fields
<umit.umpa.protocols.Payload.Payload object at 0xb78e794c>
<umit.umpa._packets.Packet object at 0xb78e798c>In [18]:sockets
-------
Now, we are ready to send the packet!
To create a new socket, we will use ``umit.umpa.Socket`` class.
Please remember, that we dropped our priviliges so we need to get them
back now.
We can do it in 2 ways.
1. atomic way (recommended)
.. code-block:: python
In [18]: sock = umit.umpa.utils.security.super_priviliges(umit.umpa.Socket)In [19]:2. normal way
.. code-block:: python
In [18]: umit.umpa.utils.security.drop_priviliges()In [19]: umit.umpa.utils.security.super_priviliges()In [20]: sock = umit.umpa.Socket()In [21]: umit.umpa.utils.security.drop_priviliges()In [22]:Both are correct. But the former is recommended. How does it work?
We pass arguments into ``super_priviliges()`` function, the first has to
be callable, others are just arguments for the first one.
Result of the callable argument is returned by the ``super_priviliges()``
function.
Internally in the ``super_priviliges()`` function:
1. change EUID to the 0 (root)
2. call the first argument from passed arguments
3. change EUID to nobody (call ``drop_priviliges()``)
4. return the result of the calling from point 2
Ok, actually we have a socket object, so let's send the packet!
.. code-block:: python
In [19]: sock.send(first_packet)
Out [19]: [53]In [20]:``Socket.send()`` method returns a list with sent bytes of each packets (we can
pass more than one packet at the same time).
UDP protocol
------------
Ok, let's create another packet with a UDP header just in single line!
.. code-block:: python
In [20]: udp = umit.umpa.protocols.UDP(source_port=0, destination_port=7)In [21]:ttl aka enumfield
-----------------
Now, we can simple create a new packet and use already created ``sock`` object
to send it out, but before we will do that, lets change TTL field of
the IP protocol.
Some common fields like TTL or ports in TCP/UDP headers are ``EnumField``
objects. What does it mean? Well, this is a simple numeric field but with
special behaviour.
We can pass common names instead of numbers (what is easier to remember).
Let's do it on the TTL example.
.. code-block:: python
In [21]: ip.get_field("time_to_live").enumerable
Out[21]:
{'aix': 60,
'dec': 30,
'freebsd': 64,
'irix': 60,
'linux': 64,
'macos': 60,
'os2': 64,
'solaris': 255,
'sunos': 60,
'ultrix': 60,
'windows': 128}In [22]: ip.time_to_live = "windows"In [23]:Why can't we use ``ip.time_to_live.enumerable`` in the first line?
Well, attributes like object.''name_of_field'' are reserved only to get/set
values of them. They handle only with values. To get a reference to the field's
object we need to use ``get_field()`` method.
print statement is sooo cool
----------------------------
Don't forget about checking if everything is correct :-)
.. code-block:: python
In [23]: print second_packet
Packet contains 2 protocols
+-< IP >
| \
| +-[ Version ] 4 (auto - 4)
| +-[ IHL ] None (auto - 5)
| +-[ TOS ]
| | \
| | -{ precedence0 } 0
| | -{ precedence1 } 0
| | -{ precedence2 } 0
| | -{ delay } 0
| | -{ throughput } 0
| | -{ relibility } 0
| | -{ reserved0 } 0
| | -{ reserved1 } 0
| | /
| \-[ TOS ] contains 8 bit flags
| +-[ Total Length ] None (auto - 28)
| +-[ Identification ] 0 (auto - 0)
| +-[ Flags ]
| | \
| | -{ reserved } 0
| | -{ df } 0
| | -{ mf } 0
| | /
| \-[ Flags ] contains 3 bit flags
| +-[ Fragment Offset ] 0 (auto - 0)
| +-[ TTL ] 128 (auto - 128)
| +-[ Protocol ] None (auto - 17)
| +-[ _Header Checksum ] 0 (auto - 0)
| +-[ Source Address ] 127.0.0.1
| +-[ Destination Address ] (67, 205, 14, 183)
| +-[ Options ]
| | \
| | /
| \-[ Options ] contains 0 bit flags
| + 0 (auto - 0)
\< IP > contains 14 fields
<umit.umpa.protocols.IP.IP object at 0xb78c8b6c>
+-< UDP >
| \
| +-[ Source Port ] 0
| +-[ Destination Port ] 7
| +-[ Length ] None (auto - 8)
| + None (auto - 0)
\< UDP > contains 4 fields
<umit.umpa.protocols.UDP.UDP object at 0xb78c8b0c>
<umit.umpa._packets.Packet object at 0xb78c8ecc>In [24]:As you see, TTL is "in Windows mode".
packing and sending again
-------------------------
.. code-block:: python
In [24]: second_packet = umit.umpa.Packet(ip, udp)In [25]: sock.send(first_packet, second_packet)
Out [25]: [53, 28]In [26]:We sent 2 packets. 53 bytes first for the first packet and 28 for the second.
Now, just make some exercises to get more practice!
}}}