pytap3 3.0.0__tar.gz

pytap3-3.0.0/LICENSE.txt

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Federico Santandrea
+Copyright (c) 2019-2023 John Hagen
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pytap3-3.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.rst
+include LICENSE.txt
+include pytap3_build.py

pytap3-3.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: pytap3
+Version: 3.0.0
+Summary: Cross-platform tunnel interface for Python
+Home-page: https://github.com/sntfrc/pytap3
+Author: Federico Santandrea
+Author-email: federico@santandrea.net
+License: MIT
+Keywords: pytap,tun,tap,networking
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+License-File: LICENSE.txt
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+``pytap3`` - Cross-platform tunnel interface for Python
+=======================================================
+
+This is a cross-platform fork of the original
+`johnthagen/pytap2 <https://github.com/johnthagen/pytap2>`_. It provides a
+packet-oriented interface to TUN devices on Linux, macOS, and Windows.
+
+Requirements
+------------
+
+Requirements depend on your operating system:
+
+* **Linux:** Install ``net-tools`` to provide the ``ifconfig`` command.
+
+  On Debian/Ubuntu:
+
+  .. code:: shell-session
+
+      $ sudo apt install net-tools
+
+  On RHEL/Rocky Linux/Fedora:
+
+  .. code:: shell-session
+
+      $ sudo yum install net-tools
+
+* **macOS:** No additional packages are required; ``ifconfig`` is included
+  with macOS.
+
+* **Windows:** ``wintun.dll`` is required. When building/installing from source
+  on Windows, the package downloads the signed Wintun 0.14.1 archive from
+  `Wintun <https://www.wintun.net/>`_, verifies its SHA-256 checksum, and bundles
+  the DLL matching the Python platform. This requires network access during
+  installation. Wheels are platform-tagged; build Windows wheels on Windows to
+  include the DLL. Source distributions build locally on any supported OS.
+
+Creating and configuring a TUN device may require administrator or root
+privileges.
+
+Installation
+------------
+
+You can install, upgrade, and uninstall ``pytap3`` with these commands:
+
+.. code:: shell-session
+
+    $ pip install pytap3
+    $ pip install --upgrade pytap3
+    $ pip uninstall pytap3
+
+Usage
+-----
+
+Using as a context manager automatically brings up the device and closes it at the
+end of the ``with`` block.
+
+.. code:: python
+
+    from pytap3 import TapDevice
+
+    with TapDevice() as device:
+        device.ifconfig(mtu=1300)
+        device.write(b'0000')
+
+Or manually call ``up()`` and ``close()``.
+
+.. code:: python
+
+    from pytap3 import TapDevice
+
+    device = TapDevice()
+    device.up()
+    device.ifconfig(mtu=1300)
+    device.write(b'0000')
+    device.close()
+
+The ``fileno()`` method is defined, so that the device object can be passed directly
+to `select() <https://docs.python.org/library/select.html#select.select>`_. This might
+not work on Windows, as the underlying Wintun driver does not support this.
+
+On macOS, configuring an IP address with ``ifconfig(ip=..., netmask=...)`` also
+adds a route for that subnet through the ``utun`` interface. Routes that conflict
+with an existing route may require administrator privileges or manual adjustment.
+
+You can make pytap3 a drop-in replacement for pytap2 by just importing it like this:
+ ``import pytap3 as pytap2``
+
+Releases
+--------
+
+3.0.0 - 2024-06-05
+^^^^^^^^^^^^^^^^^^
+
+- Windows, Linux and macOS support!

pytap3-3.0.0/README.rst

@@ -0,0 +1,94 @@
+``pytap3`` - Cross-platform tunnel interface for Python
+=======================================================
+
+This is a cross-platform fork of the original
+`johnthagen/pytap2 <https://github.com/johnthagen/pytap2>`_. It provides a
+packet-oriented interface to TUN devices on Linux, macOS, and Windows.
+
+Requirements
+------------
+
+Requirements depend on your operating system:
+
+* **Linux:** Install ``net-tools`` to provide the ``ifconfig`` command.
+
+  On Debian/Ubuntu:
+
+  .. code:: shell-session
+
+      $ sudo apt install net-tools
+
+  On RHEL/Rocky Linux/Fedora:
+
+  .. code:: shell-session
+
+      $ sudo yum install net-tools
+
+* **macOS:** No additional packages are required; ``ifconfig`` is included
+  with macOS.
+
+* **Windows:** ``wintun.dll`` is required. When building/installing from source
+  on Windows, the package downloads the signed Wintun 0.14.1 archive from
+  `Wintun <https://www.wintun.net/>`_, verifies its SHA-256 checksum, and bundles
+  the DLL matching the Python platform. This requires network access during
+  installation. Wheels are platform-tagged; build Windows wheels on Windows to
+  include the DLL. Source distributions build locally on any supported OS.
+
+Creating and configuring a TUN device may require administrator or root
+privileges.
+
+Installation
+------------
+
+You can install, upgrade, and uninstall ``pytap3`` with these commands:
+
+.. code:: shell-session
+
+    $ pip install pytap3
+    $ pip install --upgrade pytap3
+    $ pip uninstall pytap3
+
+Usage
+-----
+
+Using as a context manager automatically brings up the device and closes it at the
+end of the ``with`` block.
+
+.. code:: python
+
+    from pytap3 import TapDevice
+
+    with TapDevice() as device:
+        device.ifconfig(mtu=1300)
+        device.write(b'0000')
+
+Or manually call ``up()`` and ``close()``.
+
+.. code:: python
+
+    from pytap3 import TapDevice
+
+    device = TapDevice()
+    device.up()
+    device.ifconfig(mtu=1300)
+    device.write(b'0000')
+    device.close()
+
+The ``fileno()`` method is defined, so that the device object can be passed directly
+to `select() <https://docs.python.org/library/select.html#select.select>`_. This might
+not work on Windows, as the underlying Wintun driver does not support this.
+
+On macOS, configuring an IP address with ``ifconfig(ip=..., netmask=...)`` also
+adds a route for that subnet through the ``utun`` interface. Routes that conflict
+with an existing route may require administrator privileges or manual adjustment.
+
+You can make pytap3 a drop-in replacement for pytap2 by just importing it like this:
+ ``import pytap3 as pytap2``
+
+Releases
+--------
+
+3.0.0 - 2024-06-05
+^^^^^^^^^^^^^^^^^^
+
+- Windows, Linux and macOS support!

pytap3-3.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=60.2", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.mypy]
+ignore_missing_imports = true
+strict = true
+
+[tool.black]
+line-length = 99
+target-version = ["py38", "py39", "py310"]
+
+[tool.isort]
+profile = "black"
+line_length = 99
+force_sort_within_sections = true
+src_paths = ["src/pytap3"]
+skip_gitignore = true
+
+[tool.coverage.run]
+branch = true
+source = ["pytap3", "tests/"]
+
+[tool.coverage.paths]
+source = [
+    "src/pytap3",
+    ".tox/*/lib/python*/site-packages/pytap3",
+]

pytap3-3.0.0/pytap3_build.py

@@ -0,0 +1,76 @@
+import hashlib
+import io
+from pathlib import Path
+import sys
+import sysconfig
+from typing import Dict, List, Tuple, cast
+import urllib.request
+import zipfile
+
+from setuptools.command.build_py import build_py
+from wheel.bdist_wheel import bdist_wheel
+
+WINTUN_URL = "https://www.wintun.net/builds/wintun-0.14.1.zip"
+WINTUN_SHA256 = "07c256185d6ee3652e09fa55c0b673e2624b565e02c4b9091c79ca7d2f24ef51"
+
+_PLATFORM_ARCHITECTURES: Dict[str, str] = {
+    "win32": "x86",
+    "win-amd64": "amd64",
+    "win-arm32": "arm",
+    "win-arm64": "arm64",
+}
+
+
+def get_wintun_architecture() -> str:
+    platform_name = sysconfig.get_platform().lower()
+    try:
+        return _PLATFORM_ARCHITECTURES[platform_name]
+    except KeyError as exc:
+        raise RuntimeError(
+            "Unsupported Windows platform for Wintun: {}".format(platform_name)
+        ) from exc
+
+
+def download_wintun(destination: Path, architecture: str) -> None:
+    with urllib.request.urlopen(WINTUN_URL, timeout=30) as response:
+        archive_data = response.read()
+    digest = hashlib.sha256(archive_data).hexdigest()
+    if digest != WINTUN_SHA256:
+        raise ValueError(
+            "Wintun archive SHA-256 mismatch: expected {}, got {}".format(WINTUN_SHA256, digest)
+        )
+
+    member_name = "wintun/bin/{}/wintun.dll".format(architecture)
+    with zipfile.ZipFile(io.BytesIO(archive_data)) as archive:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(archive.read(member_name))
+        (destination.parent / "wintun-LICENSE.txt").write_bytes(archive.read("wintun/LICENSE.txt"))
+
+
+class WintunBuildPy(build_py):  # type: ignore[misc]
+    def get_outputs(self, include_bytecode: int = 1) -> List[str]:
+        outputs = cast(List[str], super().get_outputs(include_bytecode))
+        if sys.platform == "win32":
+            package_directory = Path(self.build_lib) / "pytap3"
+            outputs.extend(
+                str(package_directory / filename)
+                for filename in ("wintun.dll", "wintun-LICENSE.txt")
+            )
+        return outputs
+
+    def run(self) -> None:
+        super().run()
+        if sys.platform == "win32":
+            architecture = get_wintun_architecture()
+            destination = Path(self.build_lib) / "pytap3" / "wintun.dll"
+            download_wintun(destination, architecture)
+
+
+class PlatformWheel(bdist_wheel):  # type: ignore[misc]
+    def finalize_options(self) -> None:
+        super().finalize_options()
+        self.root_is_pure = False
+
+    def get_tag(self) -> Tuple[str, str, str]:
+        _, _, platform_tag = cast(Tuple[str, str, str], super().get_tag())
+        return "py3", "none", platform_tag

pytap3-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pytap3-3.0.0/setup.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+
+import setuptools
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from pytap3_build import PlatformWheel, WintunBuildPy  # noqa: E402
+
+setuptools.setup(
+    name="pytap3",
+    version="3.0.0",
+    description="Cross-platform tunnel interface for Python",
+    long_description=open("README.rst").read(),
+    keywords=["pytap", "tun", "tap", "networking"],
+    author="Federico Santandrea",
+    author_email="federico@santandrea.net",
+    url="https://github.com/sntfrc/pytap3",
+    packages=setuptools.find_packages("src"),
+    package_dir={"": "src"},
+    package_data={"pytap3": ["py.typed"]},
+    cmdclass={"bdist_wheel": PlatformWheel, "build_py": WintunBuildPy},
+    include_package_data=True,
+    python_requires=">=3.8",
+    zip_safe=False,
+    license="MIT",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: POSIX :: Linux",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3 :: Only",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+)

pytap3-3.0.0/src/pytap3/__init__.py

@@ -0,0 +1,499 @@
+"""A small, packet-oriented wrapper for OS TUN interfaces.
+
+Linux uses ``/dev/net/tun``, macOS uses ``utun`` kernel control sockets, and
+Windows uses the Wintun userspace API. Creating/configuring an interface
+normally requires administrator/root privileges.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import errno
+import ipaddress
+import logging
+import os
+import platform
+import socket
+import struct
+import subprocess
+import uuid
+from typing import Optional
+
+if os.name != "nt":
+    import fcntl
+
+
+IFF_TUN = 0x0001
+IFF_TAP = 0x0002
+IFF_NO_PI = 0x1000
+_IFNAMSIZ = 16
+_DEFAULT_MTU = 1500
+_LOGGER = logging.getLogger(__name__)
+
+
+class TapDeviceError(OSError):
+    """Raised when a TUN interface cannot be created or operated."""
+
+
+def _run(*args: str) -> None:
+    """Run an interface configuration command and preserve its error output."""
+    try:
+        subprocess.run(args, check=True, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise TapDeviceError(f"Required command not found: {args[0]}") from exc
+    except subprocess.CalledProcessError as exc:
+        detail = (exc.stderr or exc.stdout or "").strip()
+        raise TapDeviceError(detail or f"Command failed: {' '.join(args)}") from exc
+
+
+class _LinuxBackend:
+    TUNSETIFF = 0x400454CA
+
+    def __init__(self, name: Optional[str], mode: int, no_pi: bool) -> None:
+        if mode not in (IFF_TUN, IFF_TAP):
+            raise ValueError("mode must be IFF_TUN or IFF_TAP")
+        self.fd = os.open("/dev/net/tun", os.O_RDWR)
+        flags = mode | (IFF_NO_PI if no_pi else 0)
+        request = struct.pack("16sH", (name or "").encode(), flags)
+        try:
+            result = fcntl.ioctl(self.fd, self.TUNSETIFF, request)
+        except Exception:
+            os.close(self.fd)
+            raise
+        self.name = result[:_IFNAMSIZ].split(b"\0", 1)[0].decode()
+        self.no_pi = no_pi
+
+    def read(self, size: int) -> bytes:
+        return os.read(self.fd, size)
+
+    def write(self, packet: bytes) -> int:
+        return os.write(self.fd, packet)
+
+    def fileno(self) -> int:
+        return self.fd
+
+    def close(self) -> None:
+        if self.fd is not None:
+            os.close(self.fd)
+            self.fd = None
+
+
+class _MacOSBackend:
+    # Darwin kernel-control socket structures (native byte order).
+    _CTL_INFO_SIZE = 96  # uint32 ctl_id + char ctl_name[96]
+    _SOCKADDR_CTL = struct.Struct("=BBHII5I")
+    _CTLIOCGINFO = 0xC0644E03
+    _UTUN_CONTROL_NAME = b"com.apple.net.utun_control"
+    _AF_SYSTEM = 32
+    _AF_SYS_CONTROL = 2
+    _SYSPROTO_CONTROL = 2
+    _UTUN_OPT_IFNAME = 2
+
+    def __init__(self, name: Optional[str], mode: int, no_pi: bool) -> None:
+        if mode != IFF_TUN:
+            raise ValueError("macOS utun supports layer-3 TUN devices only")
+        if name and not name.startswith("utun"):
+            name = "utun0"
+        requested_unit = None if not name else int(name[4:]) + 1
+        unit = 1 if requested_unit is None else requested_unit
+        retried = False
+        while True:
+            interface_name = f"utun{unit - 1}"
+            _LOGGER.debug("Creating macOS utun control socket for %s", interface_name)
+            try:
+                sock = socket.socket(
+                    getattr(socket, "PF_SYSTEM", 32), socket.SOCK_DGRAM,
+                    self._SYSPROTO_CONTROL
+                )
+            except OSError as exc:
+                raise TapDeviceError(
+                    exc.errno,
+                    f"Creating control socket for {interface_name} failed: "
+                    f"{exc.strerror or exc}",
+                ) from exc
+            try:
+                info = bytearray(self._CTL_INFO_SIZE + 4)
+                info[4:4 + len(self._UTUN_CONTROL_NAME)] = self._UTUN_CONTROL_NAME
+                fcntl.ioctl(sock.fileno(), self._CTLIOCGINFO, info, True)
+                ctl_id = struct.unpack_from("=I", info)[0]
+            except OSError as exc:
+                sock.close()
+                raise TapDeviceError(
+                    exc.errno,
+                    f"Looking up the utun kernel control for {interface_name} "
+                    f"failed: {exc.strerror or exc}",
+                ) from exc
+            except Exception:
+                sock.close()
+                raise
+            try:
+                _LOGGER.debug(
+                    "Connecting macOS utun control socket to unit %d (%s)",
+                    unit, interface_name,
+                )
+                sock.connect((ctl_id, unit))
+            except OSError as exc:
+                sock.close()
+                if exc.errno == errno.EBUSY:
+                    _LOGGER.debug(
+                        "%s is busy; trying the next macOS utun unit",
+                        interface_name,
+                    )
+                    unit += 1
+                    retried = True
+                    continue
+                raise TapDeviceError(
+                    exc.errno,
+                    f"Connecting to macOS utun unit {unit} ({interface_name}) "
+                    f"failed: {exc.strerror or exc}",
+                ) from exc
+            except Exception:
+                sock.close()
+                raise
+            self.sock = sock
+            break
+
+        _LOGGER.debug(
+            "Reading assigned interface name for macOS utun unit %d", unit
+        )
+        try:
+            self.name = self.sock.getsockopt(
+                self._SYSPROTO_CONTROL, self._UTUN_OPT_IFNAME, 64
+            ).split(b"\0", 1)[0].decode()
+        except OSError as exc:
+            self.sock.close()
+            raise TapDeviceError(
+                exc.errno,
+                f"Reading the assigned name for macOS utun unit {unit} failed: "
+                f"{exc.strerror or exc}",
+            ) from exc
+        except Exception:
+            self.sock.close()
+            raise
+        if name and not retried and name != self.name:
+            self.sock.close()
+            raise TapDeviceError(
+                f"Requested {name}, but macOS assigned {self.name}; "
+                "utun names are assigned by the kernel"
+            )
+
+    def read(self, size: int) -> bytes:
+        packet = self.sock.recv(size + 4)
+        if len(packet) < 4:
+            return b""
+        # utun prepends a 32-bit address-family value to every packet.
+        return packet[4:]
+
+    def write(self, packet: bytes) -> int:
+        if not packet:
+            return self.sock.send(packet)
+        version = packet[0] >> 4
+        if version == 4:
+            family = socket.AF_INET
+        elif version == 6:
+            family = socket.AF_INET6
+        else:
+            raise ValueError("utun accepts only IPv4 or IPv6 packets")
+        return max(0, self.sock.send(struct.pack("!I", family) + packet) - 4)
+
+    def fileno(self) -> int:
+        return self.sock.fileno()
+
+    def close(self) -> None:
+        self.sock.close()
+
+
+class _GUID(ctypes.Structure):
+    _fields_ = [
+        ("Data1", ctypes.c_uint32),
+        ("Data2", ctypes.c_uint16),
+        ("Data3", ctypes.c_uint16),
+        ("Data4", ctypes.c_ubyte * 8),
+    ]
+
+    @classmethod
+    def from_uuid(cls, value: uuid.UUID) -> "_GUID":
+        raw = value.bytes_le
+        result = cls()
+        ctypes.memmove(ctypes.byref(result), raw, 16)
+        return result
+
+
+class _WindowsBackend:
+    ERROR_NO_MORE_ITEMS = 259
+    ERROR_BUFFER_OVERFLOW = 111
+    WAIT_OBJECT_0 = 0
+    INFINITE = 0xFFFFFFFF
+
+    def __init__(self, name: Optional[str], mode: int, no_pi: bool) -> None:
+        if mode != IFF_TUN:
+            raise ValueError("Wintun supports layer-3 TUN devices only")
+        if not hasattr(ctypes, "WinDLL"):
+            raise TapDeviceError("Wintun is available only on Windows")
+        self.name = name or "pytap3"
+        self._dll = self._load_dll()
+        self._bind_api()
+        adapter_type = "Wintun"
+        adapter_guid = _GUID.from_uuid(
+            uuid.uuid5(uuid.NAMESPACE_DNS, "pytap3:" + self.name)
+        )
+        self.adapter = self._create_adapter(
+            self.name, adapter_type, ctypes.byref(adapter_guid)
+        )
+        if not self.adapter:
+            raise ctypes.WinError(ctypes.get_last_error())
+        self.session = self._start_session(self.adapter, 0x400000)
+        if not self.session:
+            error = ctypes.get_last_error()
+            self._close_adapter(self.adapter)
+            self.adapter = None
+            raise ctypes.WinError(error)
+        self._wait_event = self._get_read_wait_event(self.session)
+        if not self._wait_event:
+            self.close()
+            raise ctypes.WinError(ctypes.get_last_error())
+        self._kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        self._kernel32.WaitForSingleObject.argtypes = [ctypes.c_void_p, ctypes.c_uint32]
+        self._kernel32.WaitForSingleObject.restype = ctypes.c_uint32
+
+    @staticmethod
+    def _load_dll():
+        candidates = []
+        bundled = os.path.join(os.path.dirname(__file__), "wintun.dll")
+        if os.path.isfile(bundled):
+            candidates.append(bundled)
+        found = ctypes.util.find_library("wintun")
+        if found:
+            candidates.append(found)
+        candidates.append("wintun.dll")
+        errors = []
+        for candidate in candidates:
+            try:
+                return ctypes.WinDLL(candidate, use_last_error=True)
+            except OSError as exc:
+                errors.append(str(exc))
+        raise TapDeviceError(
+            "Could not load wintun.dll. Place the architecture-matched, "
+            "signed Wintun DLL beside this module or on PATH. " + "; ".join(errors)
+        )
+
+    def _bind_api(self) -> None:
+        pointer = ctypes.c_void_p
+        self._create_adapter = self._dll.WintunCreateAdapter
+        self._create_adapter.argtypes = [ctypes.c_wchar_p, ctypes.c_wchar_p,
+                                         ctypes.POINTER(_GUID)]
+        self._create_adapter.restype = pointer
+        self._start_session = self._dll.WintunStartSession
+        self._start_session.argtypes = [pointer, ctypes.c_uint32]
+        self._start_session.restype = pointer
+        self._end_session = self._dll.WintunEndSession
+        self._end_session.argtypes = [pointer]
+        self._end_session.restype = None
+        self._close_adapter = self._dll.WintunCloseAdapter
+        self._close_adapter.argtypes = [pointer]
+        self._close_adapter.restype = None
+        self._receive_packet = self._dll.WintunReceivePacket
+        self._receive_packet.argtypes = [pointer, ctypes.POINTER(ctypes.c_uint32)]
+        self._receive_packet.restype = pointer
+        self._release_packet = self._dll.WintunReleaseReceivePacket
+        self._release_packet.argtypes = [pointer, pointer]
+        self._release_packet.restype = None
+        self._allocate_packet = self._dll.WintunAllocateSendPacket
+        self._allocate_packet.argtypes = [pointer, ctypes.c_uint32]
+        self._allocate_packet.restype = pointer
+        self._send_packet = self._dll.WintunSendPacket
+        self._send_packet.argtypes = [pointer, pointer]
+        self._send_packet.restype = None
+        self._get_read_wait_event = self._dll.WintunGetReadWaitEvent
+        self._get_read_wait_event.argtypes = [pointer]
+        self._get_read_wait_event.restype = pointer
+
+    def read(self, size: int) -> bytes:
+        while True:
+            packet_size = ctypes.c_uint32()
+            packet = self._receive_packet(self.session, ctypes.byref(packet_size))
+            if packet:
+                try:
+                    return ctypes.string_at(packet, min(size, packet_size.value))
+                finally:
+                    self._release_packet(self.session, packet)
+            error = ctypes.get_last_error()
+            if error != self.ERROR_NO_MORE_ITEMS:
+                raise ctypes.WinError(error)
+            result = self._kernel32.WaitForSingleObject(self._wait_event, self.INFINITE)
+            if result != self.WAIT_OBJECT_0:
+                raise ctypes.WinError(ctypes.get_last_error())
+
+    def write(self, packet: bytes) -> int:
+        ptr = self._allocate_packet(self.session, len(packet))
+        if not ptr:
+            error = ctypes.get_last_error()
+            if error == self.ERROR_BUFFER_OVERFLOW:
+                return 0
+            raise ctypes.WinError(error)
+        if packet:
+            ctypes.memmove(ptr, packet, len(packet))
+        self._send_packet(self.session, ptr)
+        return len(packet)
+
+    def fileno(self) -> int:
+        # This is a Windows event HANDLE. It is waitable with Win32 wait APIs,
+        # but is not a POSIX descriptor and cannot be passed to select.select().
+        return int(self._wait_event)
+
+    def close(self) -> None:
+        if getattr(self, "session", None):
+            self._end_session(self.session)
+            self.session = None
+        if getattr(self, "adapter", None):
+            self._close_adapter(self.adapter)
+            self.adapter = None
+
+
+class TapDevice:
+    """Create and use a packet-oriented TUN device.
+
+    Args:
+        name: Preferred interface name. macOS assigns ``utunN`` names itself
+            and tries a later unit if the requested unit is busy.
+        mode: ``IFF_TUN`` (default) or Linux-only ``IFF_TAP``.
+        no_pi: Linux-only; omit the two-byte packet-information header.
+        mtu: MTU to set when the interface is brought up.
+
+    ``read`` and ``write`` exchange IP packets without platform headers.
+    """
+
+    def __init__(self, name: Optional[str] = None, mode: int = IFF_TUN,
+                 no_pi: bool = True, mtu: int = _DEFAULT_MTU) -> None:
+        self.mtu = mtu
+        self.mode = mode
+        self.no_pi = no_pi
+        self._platform = platform.system()
+        if self._platform == "Linux":
+            self._backend = _LinuxBackend(name, mode, no_pi)
+        elif self._platform == "Darwin":
+            self._backend = _MacOSBackend(name, mode, no_pi)
+        elif self._platform == "Windows":
+            self._backend = _WindowsBackend(name, mode, no_pi)
+        else:
+            raise TapDeviceError(f"Unsupported operating system: {self._platform}")
+        self.name = self._backend.name
+        self._closed = False
+
+    def fileno(self) -> int:
+        """Return the POSIX file descriptor or Windows Wintun wait-event handle."""
+        return self._backend.fileno()
+
+    @property
+    def fd(self) -> int:
+        """Compatibility alias for ``fileno()``."""
+        return self.fileno()
+
+    def read(self, size: Optional[int] = None) -> bytes:
+        """Read one packet; defaults to one MTU of payload."""
+        if self._closed:
+            raise ValueError("I/O operation on closed TUN device")
+        if size is None:
+            size = self.mtu
+            if self._platform == "Linux" and not self.no_pi:
+                size += 4
+        return self._backend.read(size)
+
+    def write(self, packet: bytes) -> int:
+        """Write one complete IP packet to the interface."""
+        if self._closed:
+            raise ValueError("I/O operation on closed TUN device")
+        if not isinstance(packet, (bytes, bytearray, memoryview)):
+            raise TypeError("packet must be bytes-like")
+        return self._backend.write(bytes(packet))
+
+    def up(self) -> None:
+        """Bring the interface up and apply the configured MTU."""
+        if self._platform == "Windows":
+            _run("netsh", "interface", "set", "interface", f"name={self.name}",
+                 "admin=enabled")
+            _run("netsh", "interface", "ipv4", "set", "subinterface",
+                 self.name, f"mtu={self.mtu}", "store=active")
+        else:
+            _run("ifconfig", self.name, "mtu", str(self.mtu), "up")
+
+    @staticmethod
+    def _mac_peer(address: str, netmask: str) -> str:
+        ip = ipaddress.ip_address(address)
+        if ip.version == 4:
+            network = ipaddress.ip_network(f"{address}/{netmask}", strict=False)
+        else:
+            network = ipaddress.ip_network(f"{address}/{netmask}", strict=False)
+        for candidate in network.hosts():
+            if candidate != ip:
+                return str(candidate)
+        raise ValueError(f"No other usable address in {network} for utun peer")
+
+    def ifconfig(self, ip: Optional[str] = None, netmask: Optional[str] = None,
+                 mtu: Optional[int] = None, peer: Optional[str] = None,
+                 address: Optional[str] = None) -> None:
+        """Configure interface addressing and/or MTU.
+
+        For macOS, ``peer`` defaults to the first usable address in the given
+        subnet other than ``ip``. This supplies utun's required point-to-point
+        destination address. It is a deterministic placeholder, not a probe of
+        address use on the network. The subnet route implied by ``netmask`` is
+        also installed through the utun interface.
+        """
+        if address is not None:
+          if ip is not None and ip != address:
+            raise ValueError("pass either ip or address, not conflicting values")
+          ip = address
+        target_mtu = mtu if mtu is not None else self.mtu
+        if self._platform == "Linux":
+            args = ["ifconfig", self.name]
+            if ip:
+                args.append(ip)
+                if netmask:
+                    args.extend(["netmask", netmask])
+            if target_mtu:
+                args.extend(["mtu", str(target_mtu)])
+            _run(*args)
+        elif self._platform == "Darwin":
+            if ip:
+                if not netmask:
+                    raise ValueError("netmask is required when configuring an IP")
+                chosen_peer = peer or self._mac_peer(ip, netmask)
+                network = ipaddress.ip_network(f"{ip}/{netmask}", strict=False)
+                args = ["ifconfig", self.name, "inet", ip, chosen_peer,
+                        "netmask", netmask]
+            else:
+                args = ["ifconfig", self.name]
+            if target_mtu:
+                args.extend(["mtu", str(target_mtu)])
+            _run(*args)
+            if ip:
+                _run("route", "-n", "add", "-net", str(network), ip)
+        else:
+            if ip:
+                if not netmask:
+                    raise ValueError("netmask is required when configuring an IP")
+                _run("netsh", "interface", "ipv4", "set", "address",
+                     f"name={self.name}", "source=static", f"address={ip}",
+                     f"mask={netmask}")
+            if target_mtu:
+                _run("netsh", "interface", "ipv4", "set", "subinterface",
+                     self.name, f"mtu={target_mtu}", "store=active")
+        if mtu is not None:
+            self.mtu = mtu
+
+    def close(self) -> None:
+        if not self._closed:
+            self._backend.close()
+            self._closed = True
+
+    def __enter__(self) -> "TapDevice":
+        self.up()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()
+
+
+__all__ = ["TapDevice", "TapDeviceError", "IFF_TUN", "IFF_TAP", "IFF_NO_PI"]

pytap3-3.0.0/src/pytap3.egg-info/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: pytap3
+Version: 3.0.0
+Summary: Cross-platform tunnel interface for Python
+Home-page: https://github.com/sntfrc/pytap3
+Author: Federico Santandrea
+Author-email: federico@santandrea.net
+License: MIT
+Keywords: pytap,tun,tap,networking
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+License-File: LICENSE.txt
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+``pytap3`` - Cross-platform tunnel interface for Python
+=======================================================
+
+This is a cross-platform fork of the original
+`johnthagen/pytap2 <https://github.com/johnthagen/pytap2>`_. It provides a
+packet-oriented interface to TUN devices on Linux, macOS, and Windows.
+
+Requirements
+------------
+
+Requirements depend on your operating system:
+
+* **Linux:** Install ``net-tools`` to provide the ``ifconfig`` command.
+
+  On Debian/Ubuntu:
+
+  .. code:: shell-session
+
+      $ sudo apt install net-tools
+
+  On RHEL/Rocky Linux/Fedora:
+
+  .. code:: shell-session
+
+      $ sudo yum install net-tools
+
+* **macOS:** No additional packages are required; ``ifconfig`` is included
+  with macOS.
+
+* **Windows:** ``wintun.dll`` is required. When building/installing from source
+  on Windows, the package downloads the signed Wintun 0.14.1 archive from
+  `Wintun <https://www.wintun.net/>`_, verifies its SHA-256 checksum, and bundles
+  the DLL matching the Python platform. This requires network access during
+  installation. Wheels are platform-tagged; build Windows wheels on Windows to
+  include the DLL. Source distributions build locally on any supported OS.
+
+Creating and configuring a TUN device may require administrator or root
+privileges.
+
+Installation
+------------
+
+You can install, upgrade, and uninstall ``pytap3`` with these commands:
+
+.. code:: shell-session
+
+    $ pip install pytap3
+    $ pip install --upgrade pytap3
+    $ pip uninstall pytap3
+
+Usage
+-----
+
+Using as a context manager automatically brings up the device and closes it at the
+end of the ``with`` block.
+
+.. code:: python
+
+    from pytap3 import TapDevice
+
+    with TapDevice() as device:
+        device.ifconfig(mtu=1300)
+        device.write(b'0000')
+
+Or manually call ``up()`` and ``close()``.
+
+.. code:: python
+
+    from pytap3 import TapDevice
+
+    device = TapDevice()
+    device.up()
+    device.ifconfig(mtu=1300)
+    device.write(b'0000')
+    device.close()
+
+The ``fileno()`` method is defined, so that the device object can be passed directly
+to `select() <https://docs.python.org/library/select.html#select.select>`_. This might
+not work on Windows, as the underlying Wintun driver does not support this.
+
+On macOS, configuring an IP address with ``ifconfig(ip=..., netmask=...)`` also
+adds a route for that subnet through the ``utun`` interface. Routes that conflict
+with an existing route may require administrator privileges or manual adjustment.
+
+You can make pytap3 a drop-in replacement for pytap2 by just importing it like this:
+ ``import pytap3 as pytap2``
+
+Releases
+--------
+
+3.0.0 - 2024-06-05
+^^^^^^^^^^^^^^^^^^
+
+- Windows, Linux and macOS support!

pytap3-3.0.0/src/pytap3.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE.txt
+MANIFEST.in
+README.rst
+pyproject.toml
+pytap3_build.py
+setup.py
+src/pytap3/__init__.py
+src/pytap3/py.typed
+src/pytap3.egg-info/PKG-INFO
+src/pytap3.egg-info/SOURCES.txt
+src/pytap3.egg-info/dependency_links.txt
+src/pytap3.egg-info/not-zip-safe
+src/pytap3.egg-info/top_level.txt
+tests/test_pytap3.py
+tests/test_pytap3_build.py

pytap3-3.0.0/src/pytap3.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pytap3-3.0.0/src/pytap3.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

pytap3-3.0.0/src/pytap3.egg-info/top_level.txt

@@ -0,0 +1 @@
+pytap3

pytap3-3.0.0/tests/test_pytap3.py

@@ -0,0 +1,115 @@
+import errno
+import os
+import socket
+import struct
+import unittest
+from unittest.mock import Mock, call, patch
+
+from pytap3 import IFF_TUN, TapDevice, _MacOSBackend
+
+
+class TestCase(unittest.TestCase):
+    def test(self) -> None:
+        pass
+
+
+@unittest.skipIf(os.name == "nt", "the macOS backend requires fcntl")
+class MacOSBackendTestCase(unittest.TestCase):
+    def test_write_encodes_address_family_in_network_byte_order(self) -> None:
+        backend = _MacOSBackend.__new__(_MacOSBackend)
+        backend.sock = Mock()
+        packet = b"\x45\x00"
+        frame = struct.pack("!I", socket.AF_INET) + packet
+        backend.sock.send.return_value = len(frame)
+
+        self.assertEqual(backend.write(packet), len(packet))
+        backend.sock.send.assert_called_once_with(frame)
+
+    @patch("pytap3.fcntl.ioctl")
+    @patch("pytap3.socket.socket")
+    def test_automatic_name_uses_next_available_unit(
+        self, socket_factory: Mock, _ioctl: Mock
+    ) -> None:
+        busy_socket = Mock()
+        busy_socket.connect.side_effect = OSError(errno.EBUSY, "resource busy")
+        available_socket = Mock()
+        available_socket.getsockopt.return_value = b"utun1\0"
+        socket_factory.side_effect = [busy_socket, available_socket]
+
+        backend = _MacOSBackend(None, IFF_TUN, True)
+
+        self.assertEqual(backend.name, "utun1")
+        busy_socket.connect.assert_called_once_with((0, 1))
+        available_socket.connect.assert_called_once_with((0, 2))
+        busy_socket.close.assert_called_once_with()
+        self.assertIs(backend.sock, available_socket)
+
+    @patch("pytap3.fcntl.ioctl")
+    @patch("pytap3.socket.socket")
+    def test_requested_name_uses_exact_unit(
+        self, socket_factory: Mock, _ioctl: Mock
+    ) -> None:
+        requested_socket = Mock()
+        requested_socket.getsockopt.return_value = b"utun4\0"
+        socket_factory.return_value = requested_socket
+
+        backend = _MacOSBackend("utun4", IFF_TUN, True)
+
+        self.assertEqual(backend.name, "utun4")
+        requested_socket.connect.assert_called_once_with((0, 5))
+        self.assertIs(backend.sock, requested_socket)
+
+    @patch("pytap3.fcntl.ioctl")
+    @patch("pytap3.socket.socket")
+    def test_requested_busy_unit_retries_and_uses_assigned_name(
+        self, socket_factory: Mock, _ioctl: Mock
+    ) -> None:
+        busy_socket = Mock()
+        busy_socket.connect.side_effect = OSError(errno.EBUSY, "Resource busy")
+        available_socket = Mock()
+        available_socket.getsockopt.return_value = b"utun5\0"
+        socket_factory.side_effect = [busy_socket, available_socket]
+
+        backend = _MacOSBackend("utun4", IFF_TUN, True)
+
+        self.assertEqual(backend.name, "utun5")
+        busy_socket.connect.assert_called_once_with((0, 5))
+        available_socket.connect.assert_called_once_with((0, 6))
+        busy_socket.close.assert_called_once_with()
+        self.assertIs(backend.sock, available_socket)
+
+
+class MacOSRouteTestCase(unittest.TestCase):
+    @patch("pytap3._run")
+    def test_ifconfig_adds_route_for_configured_subnet(self, run: Mock) -> None:
+        device = TapDevice.__new__(TapDevice)
+        device._platform = "Darwin"
+        device.name = "utun3"
+        device.mtu = 1500
+
+        device.ifconfig(ip="10.0.13.7", netmask="255.255.240.0")
+
+        self.assertEqual(
+            run.call_args_list,
+            [
+                call(
+                    "ifconfig", "utun3", "inet", "10.0.13.7", "10.0.0.1",
+                    "netmask", "255.255.240.0", "mtu", "1500",
+                ),
+                call(
+                    "route", "-n", "add", "-net", "10.0.0.0/20",
+                    "-interface", "utun3",
+                ),
+            ],
+        )
+
+    @patch("pytap3._run")
+    def test_ifconfig_without_address_does_not_add_route(self, run: Mock) -> None:
+        device = TapDevice.__new__(TapDevice)
+        device._platform = "Darwin"
+        device.name = "utun3"
+        device.mtu = 1500
+
+        device.ifconfig(mtu=1400)
+
+        run.assert_called_once_with("ifconfig", "utun3", "mtu", "1400")

pytap3-3.0.0/tests/test_pytap3_build.py

@@ -0,0 +1,121 @@
+import hashlib
+import io
+from pathlib import Path
+import tempfile
+import unittest
+from unittest.mock import patch
+import zipfile
+
+import pytap3_build
+from setuptools import Distribution
+
+
+def _wintun_archive() -> bytes:
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w") as archive:
+        archive.writestr("wintun/LICENSE.txt", "Wintun license")
+        for architecture in ("x86", "amd64", "arm", "arm64"):
+            archive.writestr("wintun/bin/{}/wintun.dll".format(architecture), architecture)
+    return buffer.getvalue()
+
+
+class WintunBuildTestCase(unittest.TestCase):
+    def test_architecture_matches_windows_python_platform(self) -> None:
+        for platform_name, expected in (
+            ("win32", "x86"),
+            ("win-amd64", "amd64"),
+            ("win-arm32", "arm"),
+            ("win-arm64", "arm64"),
+        ):
+            with self.subTest(platform=platform_name):
+                with patch(
+                    "pytap3_build.sysconfig.get_platform",
+                    return_value=platform_name,
+                ):
+                    self.assertEqual(pytap3_build.get_wintun_architecture(), expected)
+
+    def test_unsupported_platform_is_reported(self) -> None:
+        with patch("pytap3_build.sysconfig.get_platform", return_value="win-unknown"):
+            with self.assertRaisesRegex(RuntimeError, "win-unknown"):
+                pytap3_build.get_wintun_architecture()
+
+    def test_download_extracts_matching_dll_and_license(self) -> None:
+        archive_data = _wintun_archive()
+        with tempfile.TemporaryDirectory() as directory:
+            destination = Path(directory) / "pytap3" / "wintun.dll"
+            with patch(
+                "pytap3_build.urllib.request.urlopen",
+                return_value=io.BytesIO(archive_data),
+            ) as urlopen:
+                with patch.object(
+                    pytap3_build,
+                    "WINTUN_SHA256",
+                    hashlib.sha256(archive_data).hexdigest(),
+                ):
+                    pytap3_build.download_wintun(destination, "arm64")
+
+            urlopen.assert_called_once_with(pytap3_build.WINTUN_URL, timeout=30)
+            self.assertEqual(destination.read_bytes(), b"arm64")
+            self.assertEqual(
+                (destination.parent / "wintun-LICENSE.txt").read_bytes(),
+                b"Wintun license",
+            )
+
+    def test_download_rejects_unexpected_archive(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            destination = Path(directory) / "pytap3" / "wintun.dll"
+            with patch(
+                "pytap3_build.urllib.request.urlopen",
+                return_value=io.BytesIO(b"not the official archive"),
+            ):
+                with self.assertRaisesRegex(ValueError, "SHA-256 mismatch"):
+                    pytap3_build.download_wintun(destination, "amd64")
+            self.assertFalse(destination.exists())
+
+    def test_windows_build_includes_downloaded_files_as_outputs(self) -> None:
+        command = pytap3_build.WintunBuildPy(Distribution({"packages": []}))
+        command.ensure_finalized()
+        with tempfile.TemporaryDirectory() as directory:
+            command.build_lib = directory
+            with patch("pytap3_build.sys.platform", "win32"):
+                with patch("pytap3_build.build_py.run"):
+                    with patch("pytap3_build.get_wintun_architecture", return_value="amd64"):
+                        with patch("pytap3_build.download_wintun") as download:
+                            command.run()
+                            download.assert_called_once_with(
+                                Path(directory) / "pytap3" / "wintun.dll", "amd64"
+                            )
+                            outputs = command.get_outputs()
+                            self.assertIn(
+                                str(Path(directory) / "pytap3" / "wintun.dll"),
+                                outputs,
+                            )
+                            self.assertIn(
+                                str(Path(directory) / "pytap3" / "wintun-LICENSE.txt"),
+                                outputs,
+                            )
+
+    def test_non_windows_build_does_not_download_wintun(self) -> None:
+        command = pytap3_build.WintunBuildPy(Distribution({"packages": []}))
+        command.ensure_finalized()
+        with tempfile.TemporaryDirectory() as directory:
+            command.build_lib = directory
+            for platform_name in ("linux", "darwin"):
+                with self.subTest(platform=platform_name):
+                    with patch("pytap3_build.sys.platform", platform_name):
+                        with patch("pytap3_build.build_py.run"):
+                            with patch("pytap3_build.download_wintun") as download:
+                                command.run()
+                                download.assert_not_called()
+
+    def test_wheel_uses_platform_tag_without_python_abi_tag(self) -> None:
+        command = pytap3_build.PlatformWheel(Distribution())
+        with patch("pytap3_build.bdist_wheel.finalize_options"):
+            command.finalize_options()
+        self.assertFalse(command.root_is_pure)
+
+        with patch(
+            "pytap3_build.bdist_wheel.get_tag",
+            return_value=("cp315", "cp315", "win_amd64"),
+        ):
+            self.assertEqual(command.get_tag(), ("py3", "none", "win_amd64"))