« Previous -
Version 2/11
(diff) -
Next » -
Current version
Bartosz SKOWRON -, 08/26/2008 06:22 pm
There are several examples for beginners written directly in Python shell.
=== Examples ===
Check examples/* for already written full code examples.
There 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? ;-)
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 for everytime when we would like to build packets.
{{{Socket}}} is needed at the end of the process. Let's back to it 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 app).
So, it's recommended to drop the priviliges and up them only when needed. {{{umpa.utils}}} provides some useful things, 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) 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 be raised:
{{{
#!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 then 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()
Out5:
{'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 Plugins section. But {{{get_all()}}} is usually what you 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
In [7]: ip.destination_address = (67,205,14,183)
In [8]: list(ip.get_fields_keys())
Out8:
['_version',
'_ihl',
'type_of_service',
'_total_length',
'_identification',
'flags',
'_fragment_offset',
'time_to_live',
'_protocol',
'_header_checksum',
'source_address',
'destination_address',
'options',
'_padding']
}}}
Ok, I've just created the IP instance. As you see, we can pass values directly to construct ({{{In [6]}}}) or pass them later ({{{In [7]}}}). Also, IP addresses can by pass 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. Those fields may auto-generate values. So usually, we don't need a 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 payloads 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. 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, 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
| 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
| 0 (auto - 0)< TCP > contains 12 fields
\
<umpa.protocols.TCP.TCP object at 0xb78e774c>
-< Payload >
| \
| + this is umpa!< Payload > contains 1 fields
\
<umpa.protocols.Payload.Payload object at 0xb78e794c>
<umpa._packets.Packet object at 0xb78e798c>
In [18]:
}}}
===== sockets =====
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 arguments for the first one.
Result of the callable argument is return by the {{{super_priviliges()}}} function.
Internally in the {{{super_priviliges()}}} function:
1. change EUID to the 0 (root)
2. call the first argument with passed arguments
3. change EUID to nobody (call {{{drop_priviliges()}}})
4. return the result of the calling in point 2
Ok, actually we have a socket, so 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).
===== UDP protocol =====
Ok, let's create another packet with a UDP header just in single line!
{{{
#!python
In [20]: udp = umpa.protocols.UDP
In [21]:
}}}
===== ttl aka enumfield =====
Now, we can simple create new packet and use already created {{{sock}}} object to send it, but before we will do that, lets change TTL of the IP protocol.
Some common fields like TTL or ports in TCP/UDP headers are {{{EnumField}}} objects. What does mean? Well, this is simple numeric field but with special behaviour.
We can pass 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
Out21:
{'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
| 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)
| + 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.