[Python-checkins] gh-95389: expose popular ETHERTYPE_* constants in the socket module (#95390)

Mon Nov 7 09:27:43 EST 2022

https://github.com/python/cpython/commit/80c08d1cd67afdd1336c65ba23a044b6ac490f33
commit: 80c08d1cd67afdd1336c65ba23a044b6ac490f33
branch: main
author: Noam Cohen <noam at noam.me>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2022-11-07T15:27:37+01:00
summary:

gh-95389: expose popular ETHERTYPE_* constants in the socket module (#95390)

Co-authored-by: Erlend E. Aasland <erlend.aasland at protonmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach at Gerlach.CAM>

files:
A Misc/NEWS.d/next/Core and Builtins/2022-07-30-14-10-27.gh-issue-95389.nSGEkG.rst
M Doc/library/socket.rst
M Modules/socketmodule.c
M configure
M configure.ac
M pyconfig.h.in

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 3f6cb4803716..c946407ea1d8 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -189,8 +189,11 @@ created.  Socket addresses are represented as follows:
   ``(ifname, proto[, pkttype[, hatype[, addr]]])`` where:
 
   - *ifname* - String specifying the device name.
-  - *proto* - An in network-byte-order integer specifying the Ethernet
-    protocol number.
+  - *proto* - The Ethernet protocol number.
+    May be :data:`ETH_P_ALL` to capture all protocols,
+    one of the :ref:`ETHERTYPE_* constants <socket-ethernet-types>`
+    or any other Ethernet protocol number.
+    Value must be in network-byte-order.
   - *pkttype* - Optional integer specifying the packet type:
 
     - ``PACKET_HOST`` (the default) - Packet addressed to the local host.
@@ -508,6 +511,19 @@ Constants
    .. availability:: Linux >= 2.2.
 
 
+.. data:: ETH_P_ALL
+
+   :data:`!ETH_P_ALL` can be used in the :class:`~socket.socket`
+   constructor as *proto* for the :const:`AF_PACKET` family in order to
+   capture every packet, regardless of protocol.
+
+   For more information, see the :manpage:`packet(7)` manpage.
+
+   .. availability:: Linux.
+
+   .. versionadded:: 3.12
+
+
 .. data:: AF_RDS
           PF_RDS
           SOL_RDS
@@ -638,6 +654,22 @@ Constants
 
    .. versionadded:: 3.12
 
+.. _socket-ethernet-types:
+
+.. data:: ETHERTYPE_ARP
+          ETHERTYPE_IP
+          ETHERTYPE_IPV6
+          ETHERTYPE_VLAN
+
+   `IEEE 802.3 protocol number
+   <https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.txt>`_.
+   constants.
+
+   .. availability:: Linux, FreeBSD, macOS.
+
+   .. versionadded:: 3.12
+
+
 Functions
 ^^^^^^^^^
 
diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-07-30-14-10-27.gh-issue-95389.nSGEkG.rst b/Misc/NEWS.d/next/Core and Builtins/2022-07-30-14-10-27.gh-issue-95389.nSGEkG.rst
new file mode 100644
index 000000000000..d31f00de6087
--- /dev/null
+++ b/Misc/NEWS.d/next/Core and Builtins/2022-07-30-14-10-27.gh-issue-95389.nSGEkG.rst	
@@ -0,0 +1,3 @@
+Expose :data:`~socket.ETH_P_ALL` and some of the
+:ref:`ETHERTYPE_* constants <socket-ethernet-types>` in :mod:`socket`.
+Patch by Noam Cohen.
diff --git a/Modules/socketmodule.c b/Modules/socketmodule.c
index 869bacde924d..e99dfc643f94 100644
--- a/Modules/socketmodule.c
+++ b/Modules/socketmodule.c
@@ -247,6 +247,10 @@ shutdown(how) -- shut down traffic in one or both directions\n\
 #include <net/if.h>
 #endif
 
+#ifdef HAVE_NET_ETHERNET_H
+#include <net/ethernet.h>
+#endif
+
 /* Generic socket object definitions and includes */
 #define PySocket_BUILDING_SOCKET
 #include "socketmodule.h"
@@ -7711,6 +7715,25 @@ PyInit__socket(void)
     PyModule_AddIntMacro(m, ALG_OP_VERIFY);
 #endif
 
+/* IEEE 802.3 protocol numbers required for a standard TCP/IP network stack */
+#ifdef ETHERTYPE_ARP
+    PyModule_AddIntMacro(m, ETHERTYPE_ARP);
+#endif
+#ifdef ETHERTYPE_IP
+    PyModule_AddIntMacro(m, ETHERTYPE_IP);
+#endif
+#ifdef ETHERTYPE_IPV6
+    PyModule_AddIntMacro(m, ETHERTYPE_IPV6);
+#endif
+#ifdef ETHERTYPE_VLAN
+    PyModule_AddIntMacro(m, ETHERTYPE_VLAN);
+#endif
+
+/* Linux pseudo-protocol for sniffing every packet */
+#ifdef ETH_P_ALL
+    PyModule_AddIntMacro(m, ETH_P_ALL);
+#endif
+
     /* Socket types */
     PyModule_AddIntMacro(m, SOCK_STREAM);
     PyModule_AddIntMacro(m, SOCK_DGRAM);
diff --git a/configure b/configure
index ab3d6ee3c2ea..97fd931a95db 100755
--- a/configure
+++ b/configure
@@ -9446,7 +9446,7 @@ for ac_header in  \
   alloca.h asm/types.h bluetooth.h conio.h crypt.h direct.h dlfcn.h endian.h errno.h fcntl.h grp.h \
   ieeefp.h io.h langinfo.h libintl.h libutil.h linux/auxvec.h sys/auxv.h linux/fs.h linux/memfd.h \
   linux/random.h linux/soundcard.h \
-  linux/tipc.h linux/wait.h netdb.h netinet/in.h netpacket/packet.h poll.h process.h pthread.h pty.h \
+  linux/tipc.h linux/wait.h netdb.h net/ethernet.h netinet/in.h netpacket/packet.h poll.h process.h pthread.h pty.h \
   sched.h setjmp.h shadow.h signal.h spawn.h stropts.h sys/audioio.h sys/bsdtty.h sys/devpoll.h \
   sys/endian.h sys/epoll.h sys/event.h sys/eventfd.h sys/file.h sys/ioctl.h sys/kern_control.h \
   sys/loadavg.h sys/lock.h sys/memfd.h sys/mkdev.h sys/mman.h sys/modem.h sys/param.h sys/poll.h \
diff --git a/configure.ac b/configure.ac
index aebe2408c0b3..c8e227a81d2a 100644
--- a/configure.ac
+++ b/configure.ac
@@ -2708,7 +2708,7 @@ AC_CHECK_HEADERS([ \
   alloca.h asm/types.h bluetooth.h conio.h crypt.h direct.h dlfcn.h endian.h errno.h fcntl.h grp.h \
   ieeefp.h io.h langinfo.h libintl.h libutil.h linux/auxvec.h sys/auxv.h linux/fs.h linux/memfd.h \
   linux/random.h linux/soundcard.h \
-  linux/tipc.h linux/wait.h netdb.h netinet/in.h netpacket/packet.h poll.h process.h pthread.h pty.h \
+  linux/tipc.h linux/wait.h netdb.h net/ethernet.h netinet/in.h netpacket/packet.h poll.h process.h pthread.h pty.h \
   sched.h setjmp.h shadow.h signal.h spawn.h stropts.h sys/audioio.h sys/bsdtty.h sys/devpoll.h \
   sys/endian.h sys/epoll.h sys/event.h sys/eventfd.h sys/file.h sys/ioctl.h sys/kern_control.h \
   sys/loadavg.h sys/lock.h sys/memfd.h sys/mkdev.h sys/mman.h sys/modem.h sys/param.h sys/poll.h \
diff --git a/pyconfig.h.in b/pyconfig.h.in
index 0d3c851a1af9..236cee6588d4 100644
--- a/pyconfig.h.in
+++ b/pyconfig.h.in
@@ -844,6 +844,9 @@
 /* Define to 1 if you have the <netpacket/packet.h> header file. */
 #undef HAVE_NETPACKET_PACKET_H
 
+/* Define to 1 if you have the <net/ethernet.h> header file. */
+#undef HAVE_NET_ETHERNET_H
+
 /* Define to 1 if you have the <net/if.h> header file. */
 #undef HAVE_NET_IF_H
 

