Umit Project

== 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.

{{{

#!python

In [1]: import 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. {{{umpa.utils}}} package provides some useful modules, and the {{{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).

{{{

#!python

In [2]: import umpa.utils.security

In [3]: umpa.utils.security.drop_priviliges()

In [4]: 

}}}

Please note that our process has to be run as a root. Otherwise, an excaption will raise:

{{{

#!python

In [1]: import umpa.utils.security

In [2]: 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 permitted

In [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 {{{umpa.protocols}}} package. If we don't know which protocols are available, we can simple check it.

{{{

#!python

In [4]: import umpa.protocols

In [5]: umpa.protocols.get_all()

Out[5]: 

{'IP': <class 'umpa.protocols.IP.IP'>,

 'Payload': <class 'umpa.protocols.Payload.Payload'>,

 'TCP': <class 'umpa.protocols.TCP.TCP'>,

 'UDP': <class 'umpa.protocols.UDP.UDP'>}

In [6]:

}}}

There are two more functions ({{{get_globals()}}} and {{{get_locals()}}}). We will talk about them in [wiki:UMPA/Documentation/Tutorial/PluginsSystem other tutorial]. 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 =====

{{{

#!python

In [6]: ip = 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 we want to modify them - feel free to break your packets ;)

===== TCP and Payload protocols =====

What next? TCP header and some payload for it..

{{{

#!python

In [9]: tcp = umpa.protocols.TCP()

In [10]: tcp.source_port = 2958

In [11]: tcp.destination_port = 0

In [12]: tcp.set_flags('control_bits', syn=True)

In [13]: payload = umpa.protocols.Payload()

In [14]: payload.data = "this is umpa!"

In [15]: 

}}}

Completely simple so far, isn't?

===== protocols container =====

Ok, let's build a packet...

{{{

#!python

In [15]: first_packet = 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 [wiki:UMPA/Documentation/Tutorials/BreakYourPacket here].

===== print statement =====

If we take a coffe break (longer than 5 hours) now, perhaps we will forget what we built. Just print it!

{{{

#!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

| +-[ Padding                   ]		0 (auto - 0)

\-< IP                          >		contains 14 fields

<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

| +-[ Padding                   ]		0 (auto - 0)

\-< TCP                         >		contains 12 fields

<umpa.protocols.TCP.TCP object at 0xb78e774c>

+-< Payload                     >

| \

| +-[ Data                      ]		this is umpa!

\-< Payload                     >		contains 1 fields

<umpa.protocols.Payload.Payload object at 0xb78e794c>

<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 {{{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''''')

  {{{

#!python

In [18]: sock = umpa.utils.security.super_priviliges(umpa.Socket)

In [19]: 

}}}

 2. normal way

  {{{

#!python

In [18]: umpa.utils.security.drop_priviliges()

In [19]: umpa.utils.security.super_priviliges()

In [20]: sock = umpa.Socket()

In [21]: 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!

{{{

#!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!

{{{

#!python

In [20]: udp = 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 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.

{{{

#!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 we can't 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 :-)

{{{

#!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

| +-[ Padding                   ]		0 (auto - 0)

\-< IP                          >		contains 14 fields

<umpa.protocols.IP.IP object at 0xb78c8b6c>

+-< UDP                         >

| \

| +-[ Source Port               ]		0

| +-[ Destination Port          ]		7

| +-[ Length                    ]		None (auto - 8)

| +-[ Checksum                  ]		None (auto - 0)

\-< UDP                         >		contains 4 fields

<umpa.protocols.UDP.UDP object at 0xb78c8b0c>

<umpa._packets.Packet object at 0xb78c8ecc>

In [24]: 

}}}

As you see, TTL is "in Windows mode".

===== packing and sending again =====

{{{

#!python

In [24]: second_packet = 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!