Merged revisions 5591-5606,5613,5625,5645-5646 via svnmerge from

http://svn.umitproject.org/svnroot/umit/umpa/branches/link-layer-integration ........ r5591 | kosma | 2010-06-05 00:38:07 +0200 (So, 05 čen 2010) | 3 lines Initial version of SocketL2 - Linux and FreeBSD supported. With tests. L2 tests fail under BSD. L3 support not touched. ........ r5592 | kosma | 2010-06-05 01:03:33 +0200 (So, 05 čen 2010) | 1 line obliterating re module at getxsick's request :* ........ r5593 | kosma | 2010-06-05 01:15:34 +0200 (So, 05 čen 2010) | 1 line platform check: convert find to startswith ........ r5594 | kosma | 2010-06-05 01:16:59 +0200 (So, 05 čen 2010) | 1 line platform check: detect MS Windows via os.name ........ r5595 | kosma | 2010-06-05 12:39:43 +0200 (So, 05 čen 2010) | 1 line added a _Socket superclass ........ r5596 | kosma | 2010-06-05 13:16:45 +0200 (So, 05 čen 2010) | 2 lines moved 'get packet destination' to class Packet, with tests ........ r5597 | kosma | 2010-06-05 18:23:57 +0200 (So, 05 čen 2010) | 2 lines Port L3 code to new style. Add BSD endianness quirk support w/test. ........ r5598 | kosma | 2010-06-05 19:32:07 +0200 (So, 05 čen 2010) | 2 lines Load fcntl module conditionally - it's not present under Win32. ........ r5599 | kosma | 2010-06-05 21:28:44 +0200 (So, 05 čen 2010) | 1 line fix a typo preventing L3 sockets from working under OpenBSD ........ r5600 | kosma | 2010-06-05 22:15:52 +0200 (So, 05 čen 2010) | 1 line Fixed L2 send (bpf) under OpenBSD. ........ r5601 | kosma | 2010-06-05 22:39:46 +0200 (So, 05 čen 2010) | 1 line minor documentation issue ........ r5602 | kosma | 2010-06-05 23:42:41 +0200 (So, 05 čen 2010) | 1 line example for SocketL2 usage ........ r5603 | kosma | 2010-06-05 23:46:17 +0200 (So, 05 čen 2010) | 2 lines Set svn:executable property on examples, install scripts and setup.py. ........ r5604 | kosma | 2010-06-05 23:58:42 +0200 (So, 05 čen 2010) | 1 line set svn:ignore on generated documentation dirs ........ r5605 | kosma | 2010-06-06 00:09:36 +0200 (Ne, 06 čen 2010) | 6 lines README file update. - New library description from the trac site. - Added myself to Authors section (hope I won't get killed for that ;). - Formatting cleanups, rephrasing, etc. ........ r5606 | kosma | 2010-06-06 00:21:49 +0200 (Ne, 06 čen 2010) | 1 line apply changes to cloned README in docs/ ........ r5613 | getxsick | 2010-06-16 19:41:53 +0200 (St, 16 čen 2010) | 2 lines rename UMPA repository to umpa ........ r5625 | getxsick | 2010-06-18 14:48:59 +0200 (Pá, 18 čen 2010) | 2 lines rename umpa/branch to umpa/branches (even if i prefer branch/) ........ r5645 | kosma | 2010-06-19 18:00:18 +0200 (So, 19 čen 2010) | 1 line revert a too-hasty documentation change ........ r5646 | kosma | 2010-06-19 19:14:44 +0200 (So, 19 čen 2010) | 1 line information on L3 sockets under xp sp2 ........ git-svn-id: http://svn.umitproject.org/svnroot/umit/umpa/trunk@5651 1105ee14-b0fa-0310-85a5-ff3eed429ff7
umitproject · Jun 20, 2010 · caa7411 · caa7411
1 parent b150ffb
commit caa7411
Show file tree

Hide file tree

Showing 20 changed files with 448 additions and 110 deletions.
diff --git a/README b/README
@@ -2,9 +2,9 @@
  UMPA - Umit's Manipulations of Packets Art
 ============================================
 
-Copyright (C) 2008 Adriano Monteiro Marques <py.adriano at gmail dot com>
+Copyright (C) 2008-2010 Adriano Monteiro Marques <py.adriano at gmail dot com>
 
-Author: Bartosz SKOWRON <getxsick at gmail dot com>
+Authors: Bartosz SKOWRON <getxsick at gmail dot com>
 
 All rights reserved, see COPYING for details.
 
@@ -26,28 +26,27 @@ Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 Introduction
 ============
 
-UMPA is a packets manipulation library.
+UMPA is a packet generation and manipulation library. It aims to provide
+an easy-to-use system to manipulate packets on every layer of the OSI model.
+UMPA supports many sophisticated features, including:
 
-UMPA is developed in the Python programming language.
+  * auto-generating packets - defaults are provided for most fields
+  * high-level editing of header fields - no knowledge of bit-level
+    representation needed
+  * auto-filling - checksum/length fields are generated automatically
+  * interaction system - reacting and responding to network events
+  * sniffing and sending packets - easy communication with the real world 
 
-Packet manipulation library aims to provide easy to use system
-to manipulate packets of every OSI model layers.
-
-Many features are supported like: auto-generating packets, high-level
-editing header fields, auto-filling, interaction system, sniffing
-and creating objet's of packets.
 The goal of the project is to get a powerful, easy to use and intelligent
-tool for pro and newbies.
-
-Check docs/* for additional informations.
+packet manipulation tool suitable both for beginners and experienced users.
+UMPA has a wide range of uses, including network diagnostics, auditing,
+stress testing and network stack debugging. 
 
 
 Documentation
 =============
 
-On the Web:
-
-http://www.umpa.umitproject.org
+On the Web: http://www.umpa.umitproject.org
 
 This page also points to support resources and informations about UMPA
 development status and plans.
@@ -63,7 +62,7 @@ Dependencies
 
   * [1] Python programming language
   * [2] libpcap (for sniffing)
-  * [3] libpcap's python wrapper (see INSTALL for more)
+  * [3] libpcap's python wrapper (see INSTALL for details)
 
 
 Acknowledgements
@@ -72,11 +71,11 @@ Acknowledgements
 I would like to thank for a several people, who help and support me with the
 library, sending patches, testing it and giving ideas:
 
-   * Adriano Monteiro Marques
-   * Francesco Piccinno
-   * Luís António Bastião Silva
-   * Guilherme Henrique Polo Gonçalves
-   * João Paulo de Souza Medeiros
+  * Adriano Monteiro Marques
+  * Francesco Piccinno
+  * Luís António Bastião Silva
+  * Guilherme Henrique Polo Gonçalves
+  * João Paulo de Souza Medeiros
 
 
 Authors
@@ -88,6 +87,6 @@ Authors
 References
 ==========
 
-  * [0] UMPA website - http://www.umpa.umitproject.org
-  * [1] Python official website - http://www.python.org
-  * [2] Umit Project - http://www.umitproject.org
+  * [0] UMPA website - http://umpa.umitproject.org/
+  * [1] Umit Project - http://www.umitproject.org/
+  * [2] Python official website - http://www.python.org/
diff --git a/docs/README b/docs/README
@@ -2,9 +2,9 @@
  UMPA - Umit's Manipulations of Packets Art
 ============================================
 
-Copyright (C) 2008 Adriano Monteiro Marques <py.adriano at gmail dot com>
+Copyright (C) 2008-2010 Adriano Monteiro Marques <py.adriano at gmail dot com>
 
-Author: Bartosz SKOWRON <getxsick at gmail dot com>
+Authors: Bartosz SKOWRON <getxsick at gmail dot com>
 
 All rights reserved, see COPYING for details.
 
@@ -26,28 +26,27 @@ Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 Introduction
 ============
 
-UMPA is a packets manipulation library.
+UMPA is a packet generation and manipulation library. It aims to provide
+an easy-to-use system to manipulate packets on every layer of the OSI model.
+UMPA supports many sophisticated features, including:
 
-UMPA is developed in the Python programming language.
+  * auto-generating packets - defaults are provided for most fields
+  * high-level editing of header fields - no knowledge of bit-level
+    representation needed
+  * auto-filling - checksum/length fields are generated automatically
+  * interaction system - reacting and responding to network events
+  * sniffing and sending packets - easy communication with the real world 
 
-Packet manipulation library aims to provide easy to use system
-to manipulate packets of every OSI model layers.
-
-Many features are supported like: auto-generating packets, high-level
-editing header fields, auto-filling, interaction system, sniffing
-and creating objet's of packets.
 The goal of the project is to get a powerful, easy to use and intelligent
-tool for pro and newbies.
-
-Check docs/* for additional informations.
+packet manipulation tool suitable both for beginners and experienced users.
+UMPA has a wide range of uses, including network diagnostics, auditing,
+stress testing and network stack debugging. 
 
 
 Documentation
 =============
 
-On the Web:
-
-http://www.umpa.umitproject.org
+On the Web: http://www.umpa.umitproject.org
 
 This page also points to support resources and informations about UMPA
 development status and plans.
@@ -63,7 +62,7 @@ Dependencies
 
   * [1] Python programming language
   * [2] libpcap (for sniffing)
-  * [3] libpcap's python wrapper (see INSTALL for more)
+  * [3] libpcap's python wrapper (see INSTALL for details)
 
 
 Acknowledgements
@@ -72,11 +71,11 @@ Acknowledgements
 I would like to thank for a several people, who help and support me with the
 library, sending patches, testing it and giving ideas:
 
-   * Adriano Monteiro Marques
-   * Francesco Piccinno
-   * Luís António Bastião Silva
-   * Guilherme Henrique Polo Gonçalves
-   * João Paulo de Souza Medeiros
+  * Adriano Monteiro Marques
+  * Francesco Piccinno
+  * Luís António Bastião Silva
+  * Guilherme Henrique Polo Gonçalves
+  * João Paulo de Souza Medeiros
 
 
 Authors
@@ -88,6 +87,6 @@ Authors
 References
 ==========
 
-  * [0] UMPA website - http://www.umpa.umitproject.org
-  * [1] Python official website - http://www.python.org
-  * [2] Umit Project - http://www.umitproject.org
+  * [0] UMPA website - http://umpa.umitproject.org/
+  * [1] Umit Project - http://www.umitproject.org/
+  * [2] Python official website - http://www.python.org/
diff --git a/docs/tutorials-src/01-YourFirstPackets.rst b/docs/tutorials-src/01-YourFirstPackets.rst
@@ -345,6 +345,21 @@ Ok, actually we have a socket object, so let's send the packet!
 ``Socket.send()`` method returns a list with sent bytes of each packets (we can
 pass more than one packet at the same time).
 
+Raw IP sockets under Windows
+----------------------------
+
+If you plan to use raw sockets under Windows XP SP2 or later, be aware of
+the restrictions imposed by the Windows' networking stack. They generally boil
+down to two things:
+
+ 1. TCP data cannot be sent over raw sockets.
+ 2. The IP source address for any outgoing UDP datagram must exist on a network
+    interface.
+
+The detailed description of those restrictions can be found at the following URL:
+http://msdn.microsoft.com/en-us/library/ms740548%28VS.85%29.aspx.
+If you find them to be too limiting, consider using Layer 2 sockets (``SocketL2``
+class) instead.
 
 UDP protocol
 ------------

diff --git a/examples/layer2.py b/examples/layer2.py
@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# Copyright (C) 2010 Adriano Monteiro Marques.
+#
+# Author: Kosma Moczek <kosma at kosma dot pl>
+#
+# This library is free software; you can redistribute it and/or modify 
+# it under the terms of the GNU Lesser General Public License as published 
+# by the Free Software Foundation; either version 2.1 of the License, or 
+# (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but 
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
+# License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License 
+# along with this library; if not, write to the Free Software Foundation, 
+# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 
+
+"""
+This example shows how to send raw Ethernet frames using SocketL2 class.
+"""
+
+import umit.umpa
+import umit.umpa.utils.security
+
+from umit.umpa.protocols import Ethernet, IP, UDP, Payload
+from umit.umpa import SocketL2, Packet
+
+# Create a raw Ethernet socket. The 'iface' argument is mandatory.
+sock = umit.umpa.SocketL2(iface='eth0')
+
+# Drop root privileges after socket creation. This improves security.
+umit.umpa.utils.security.drop_priviliges()
+
+# Create protocol objects. We need to specify MAC addresses since we operate
+# on the link layer.
+ethernet = Ethernet(src='00:11:22:33:44:55', dst='01:23:45:67:89:AB')
+ip = IP(src='192.168.1.234', dst='192.168.1.1')
+udp = UDP(srcport=1234, dstport=4321)
+payload = Payload("UMPA")
+
+# Create a new Packet object.
+packet = Packet(ethernet, ip, udp, payload)
+
+# Send the packet. Use a network sniffer (e.g. Wireshark) to see it.
+sock.send(packet)
diff --git a/examples/models.py b/examples/models.py
diff --git a/examples/nostrict.py b/examples/nostrict.py
diff --git a/examples/payload.py b/examples/payload.py
diff --git a/examples/sniff.py b/examples/sniff.py
diff --git a/examples/tcp.py b/examples/tcp.py
diff --git a/examples/udp.py b/examples/udp.py
diff --git a/install_scripts/clean.sh b/install_scripts/clean.sh
diff --git a/install_scripts/create_docs.sh b/install_scripts/create_docs.sh
diff --git a/install_scripts/create_packages.sh b/install_scripts/create_packages.sh
diff --git a/setup.py b/setup.py
diff --git a/tests/a_unit/test_packets.py b/tests/a_unit/test_packets.py
@@ -21,9 +21,10 @@
 
 import sys
 from umit.umpa import Packet
-from umit.umpa.protocols import IP, TCP, UDP, Payload
+from umit.umpa.protocols import Ethernet, IP, TCP, UDP, Payload
 from umit.umpa.protocols import _consts
-from umit.umpa.utils.exceptions import UMPAException, UMPAStrictException
+from umit.umpa.utils.exceptions import UMPAException, UMPAStrictException, \
+                                       UMPAAttributeException
 from umit.umpa._packets import StrictWarning
 
 import py.test
@@ -97,6 +98,19 @@ def test_protos_order(self):
         for i in xrange(len(order)):
             assert isinstance(p.protos[i], order[i])
 
+    def test_get_destination(self):
+        p = Packet(Ethernet(dst='00:11:22:33:44:55'),
+                   IP(dst='1.2.3.4'),
+                   UDP(dstport=1234),
+                   Payload('UMPA'))
+
+        py.test.raises(UMPAException, p._get_destination, 1);
+        assert p._get_destination(2) == '00:11:22:33:44:55'
+        assert p._get_destination(3) == '1.2.3.4'
+        py.test.raises(UMPAAttributeException, p._get_destination, 4);
+        py.test.raises(UMPAAttributeException, p._get_destination, 5);
+        py.test.raises(UMPAException, p._get_destination, 6);
+
 class TestUMPAPacketsOutput(object):
     def test_get_raw__ip(self):
         p = Packet()

diff --git a/tests/a_unit/test_sockets.py b/tests/a_unit/test_sockets.py
@@ -1,9 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2009 Adriano Monteiro Marques.
+# Copyright (C) 2009-2010 Adriano Monteiro Marques.
 #
-# Author: Bartosz SKOWRON <getxsick at gmail dot com>
+# Authors: Bartosz SKOWRON <getxsick at gmail dot com>
+#          Kosma Moczek <kosma at kosma dot pl>
 #
 # This library is free software; you can redistribute it and/or modify 
 # it under the terms of the GNU Lesser General Public License as published 
@@ -22,10 +23,11 @@
 import os
 import py.test
 
-from umit.umpa import Socket, Packet
-from umit.umpa.protocols import IP, TCP
+from umit.umpa import Socket, SocketL2, Packet
+import umit.umpa.sniffing
+from umit.umpa.protocols import Ethernet, IP, TCP, UDP, Payload
 from umit.umpa.utils.exceptions import UMPAException, UMPANotPermittedException
-
+from tests.utils import SendPacket, SendPacketL2
 
 class TestUMPASockets(object):
     def test_init(self):
@@ -34,12 +36,75 @@ def test_init(self):
 
     def test_sent_size(self):
         if os.name == 'posix' and os.geteuid() != 0:
-            py.test.skip('root-priviliges are needed')
+            py.test.skip('root-privileges are needed')
 
         p1 = Packet(IP(), TCP())
         p2 = Packet(IP(), TCP())
 
         s = Socket()
         size = s.send(p1, p2)
-
         assert size == [40, 40]
+
+    def test_send_size_L2(self):
+        if os.name == 'posix' and os.geteuid() != 0:
+            py.test.skip('root-privileges are needed')
+
+        p1 = Packet(Ethernet(src='00:11:22:33:44:55', dst='00:11:22:33:44:55'),
+                    IP(src="127.0.0.1", dst="127.0.0.1"),
+                    TCP(srcport=1234, dstport=4321),
+                    Payload('xyz'))
+        p2 = Packet(Ethernet(src='00:11:22:33:44:55', dst='00:11:22:33:44:55'),
+                    IP(src="127.0.0.1", dst="127.0.0.1"),
+                    TCP(srcport=1234, dstport=4321),
+                    Payload('xyz'))
+
+        s = SocketL2(iface='lo')
+        size = s.send(p1, p2)
+
+        assert size == [57, 57]
+
+    def test_send_sniff_tcp(self):
+        if os.name == 'posix' and os.geteuid() != 0:
+            py.test.skip('root-privileges are needed')
+
+        p = Packet(Ethernet(src='00:11:22:33:44:55', dst='00:11:22:33:44:55'),
+                   IP(src="127.0.0.1", dst="127.0.0.1"),
+                   UDP(srcport=1234, dstport=4321),
+                   Payload('xyz'))
+
+        th = SendPacketL2(p, iface='lo')
+        th.start()
+        result = umit.umpa.sniffing.sniff(1, device='lo', filter="src port 1234")
+        th.join()
+
+        assert len(result) == 1
+        assert result[0].ethernet.src == '00:11:22:33:44:55'
+        assert result[0].ip.src == '127.0.0.1'
+        assert result[0].udp.srcport == 1234
+        assert result[0].udp.dstport == 4321
+
+    def test_send_sniff_tcp_L2(self):
+        if os.name == 'posix' and os.geteuid() != 0:
+            py.test.skip('root-privileges are needed')
+
+        p = Packet(Ethernet(src='00:11:22:33:44:55', dst='00:11:22:33:44:55'),
+                   IP(src="127.0.0.1", dst="127.0.0.1"),
+                   TCP(srcport=1234, dstport=4321),
+                   Payload('xyz'))
+
+        th = SendPacketL2(p, iface='lo')
+        th.start()
+        result = umit.umpa.sniffing.sniff(1, device='lo', filter="src port 1234")
+        th.join()
+
+        assert len(result) == 1
+        assert result[0].ethernet.src == '00:11:22:33:44:55'
+        assert result[0].ip.src == '127.0.0.1'
+        assert result[0].tcp.srcport == 1234
+        assert result[0].tcp.dstport == 4321
+
+    def test_ntohs_quirk(self):
+        raw1 = "ABCDEFGH"
+        raw2 = umit.umpa._sockets._ntohs_quirk(raw1)
+
+        assert raw2 == "ABDCEFHG"