Async SSL TCP Packet-Tunneling Gateway

A lightweight, high-performance, and zero-dependency Python asyncio package that establishes an SSL TCP connection to tunnel network payload packets inside customized stream-frames.

Supports custom packet bunching/padding layouts, multi-client ID routing, and adaptive TLS security modes.

Core Features

• Asynchronous Multiplexing: Built entirely on Python asyncio streams for extreme throughput.
• Header Packaging: IPv4 and IPv6 packets are passed as-is without extra header encapsulation (automatically parsed via their standard IP headers). Management and padding packets are prefixed with a 3-byte header (1-byte version/type and 2-byte payload size Big-Endian integer).
• Dynamic Bunching: Accumulates packets until:
  • Next packet exceeds the preferred TCP segment chunk size block.
  • Specified syncing timeout is triggered.
  • An incoming packet has a priority DSCP field (VoIP/SSH) demanding immediate flushing.
• Three Padding Modes: (none, full, random). String argument:
  • none: Disables padding.
  • full: Pads up to preferred bunch size with Junk packets of version 15.
  • random: Dynamic randomized floating pad size.
• Multi-Client ID Routing: Allocates and maps 4-octet Client IDs from a configurable IPv4 subnet pool (--pool, default 10.0.0.0/24). The first address of the configured subnet is locked and reserved for the server. Identifiers are converted/translated into Unique Local Address (ULA) IPv6 address strings starting with fd00:: prefix (within the fc00::/7 space).
• Three SSL Security Models:
  • insecure: Disables peer certification checks.
  • trusted: Checks the direct SHA256 cryptographic fingerprint of the self-signed certificate.
  • secure: Runs standard CAs verification checks.

Installation

Install using pip:

pip install .

Running the Terminal Nodes

1. Launch the Server

astunnel server --bind 0.0.0.0 --port 18443 --pem server.pem --pool 10.0.0.0/24 --padding full --timeout 0.25 --logfile server.log

2. Launch the Client

To run a client, specify the server address as a positional host:port argument:

astunnel client 127.0.0.1:18443 --client-id 10.0.0.5 --ssl-mode insecure --padding random --timeout 0.1 --logfile client.log

Backends Ecosystem

Echo Backend (Default)

Bounces packets back to the client. Ideal for testing connectivity and filtering options.

Linux TUN Backend (--backend tun)

Acquires an available virtual TUN device (e.g., tun0), brings the interface link up, configures peer-to-peer IPv4 and IPv6 addresses derived from the Client ID, and forwards bidirectional raw packets between the TUN interface and the secure SSL tunnel stream without extra overhead.

Note: Access to virtual network interfaces requires root privileges (administrative access is required to allocate and configure TUN devices).

Server:

astunnel server --bind 0.0.0.0 --port 18443 --pem server.pem --pool 10.1.2.0/24 --backend tun

Client:

astunnel client 127.0.0.1:18443 --ssl-mode insecure --backend tun

Running Tests

Run unittest suite:

python -m unittest discover -s tests