Domain Explainer: Onion Routing and Anonymous Transport#

What Is This Domain?#

When you send data over the internet, your IP address is visible to your ISP, to every router your traffic passes through, and to the server you’re connecting to. Anonymous transport systems hide this relationship — they route your traffic through a chain of intermediate nodes so that no single observer can see both who you are and what you’re doing.

The most famous example is Tor (The Onion Router). But there’s a whole ecosystem of systems with different properties and different threat models.

The Core Problem: Who Can See What?#

Consider a simple HTTP request: GET https://example.com/secret-page

Without anonymization:

• Your ISP sees: your IP, example.com, approximate content size
• example.com sees: your IP, the exact path/content

With Tor:

• Your ISP sees: your IP connecting to a Tor relay — nothing else
• example.com sees: a Tor exit node IP — your real IP is hidden
• Each Tor relay sees only its immediate neighbors in the chain

This is the core value proposition: traffic is encrypted in layers (like an onion) so each relay peels one layer and only knows the next hop.

Onion Routing vs. Garlic Routing#

Onion routing (Tor): Each message travels through a fixed chain of 3 relays. Each relay decrypts one layer and forwards to the next. Think: one message, one path, three layers of wrapping.

Garlic routing (I2P): Multiple messages are bundled together (“garlic cloves”) and sent as a unit. Uses unidirectional tunnels — separate tunnels for sending and receiving. Think: multiple messages, bundled, through one-way tunnels.

The main difference in practice:

• Tor is better for accessing the regular internet (clearnet) anonymously
• I2P is better for communication entirely within the I2P network (internal eepsites)

What Is a “Mixnet”?#

Tor and I2P are vulnerable to a sophisticated attack: if an adversary can watch both ends of a connection simultaneously — your outgoing traffic and the server’s incoming traffic — they can match the timing patterns. This is called a traffic correlation attack or global passive adversary (GPA) attack.

A mixnet defends against this by actively scrambling the timing of traffic. Each mix node deliberately delays messages by a random amount, and every node continuously generates fake “cover traffic” even when idle. This makes it impossible to correlate a packet entering the network with a packet leaving it.

Nym and Katzenpost are the main modern mixnets. The tradeoff: latency goes from ~200ms (Tor) to seconds or more (Nym). This makes mixnets unsuitable for interactive use (web browsing, chat) but appropriate for asynchronous messaging.

Onion Services (Hidden Services)#

An onion service is a server whose real IP is hidden. Instead of connecting to example.com (which reveals the server’s IP), you connect to 3g2upl4pq6kufc4m.onion — a 56-character address derived from a cryptographic key.

The magic: both the client and the server route through Tor circuits to meet at a “rendezvous point” inside the Tor network. Neither party learns the other’s real IP.

Examples: DuckDuckGo’s onion address, The New York Times onion address, SecureDrop (whistleblower platforms), various darkweb markets.

In Python: stem can create ephemeral onion services with ~5 lines of code.

The Sphinx Packet Format#

Most modern anonymous transport systems use the Sphinx packet format. Key properties:

• Fixed size: Every packet looks identical regardless of payload size (padding ensures this). No size-based fingerprinting.
• Unlinkability: An observer at a mix node cannot link the packet arriving to the packet leaving. They look completely different.
• Replay protection: The system detects and drops duplicate packets.
• Path confidentiality: Each node only knows its immediate predecessor and successor; the full path is hidden.

Sphinx is used by I2P, Nym, Katzenpost, and (partially) Lightning Network. Tor uses a similar but older format.

Key Libraries at a Glance#

stem: Python library for controlling the Tor daemon. Use it to create circuits, rotate IPs, create onion services, and monitor Tor events. The standard tool.

requests + SOCKS5: Route Python HTTP requests through Tor. proxies={'http': 'socks5h://127.0.0.1:9050'}. Simple and reliable.

torpy: Pure Python implementation of the Tor protocol — no daemon needed. Less audited than the official Tor daemon. Use as a last resort.

i2plib: Python client for I2P’s SAM bridge. Inactive; the SAM v3 protocol is simple enough to implement directly.

Nym websocket API: Nym has no Python SDK. The practical path is a local Nym client daemon + websocket JSON API. Good for GPA-resistant messaging with latency tolerance.

What This Domain Is NOT#

• VPNs: A VPN hides your traffic from your ISP but the VPN provider can see everything. It’s a single-hop trust relationship, not multi-hop anonymization.
• HTTPS: Encrypts content but doesn’t hide who you’re talking to.
• Proxies: Single-hop, provider can log.
• Tor Browser: Application that uses Tor; not a library.

When Do You Actually Need This?#

Most applications don’t need anonymous transport. Use Tor when:

• You want to hide your IP from the server you’re connecting to
• You’re scraping and don’t want to be blocked by IP
• You’re building a whistleblower platform or anonymous submission system
• You’re operating in a country that censors certain websites

Use Nym/mixnet when:

• You need to be anonymous against an adversary who can see all internet traffic
• You’re building a privacy tool for high-risk journalists or activists
• Latency tolerance is high (asynchronous messaging)

Most web applications, APIs, and services have no need for anonymous transport.

S1 Approach: Rapid Discovery#

Objective: Map the onion routing and anonymous transport library landscape. Identify the key systems (Tor, I2P, Nym, Katzenpost), their Python accessibility, and the fundamental trade-offs between anonymity strength and latency/usability.

Method: Web searches for stem Python Tor, I2P SAM Python, Nym SDK Python, Katzenpost mixnet, Sphinx packet format Python.

Key distinctions to establish:

1. Onion routing (Tor) vs. garlic routing (I2P) vs. mix networks (Nym, Katzenpost)
2. Anonymous client use (SOCKS proxy) vs. anonymous server (onion service)
3. Exit to clearnet (Tor) vs. darknet-only (I2P eepsites)
4. Low-latency onion routing (Tor) vs. high-latency mix networks (Nym, Katzenpost)
5. Latency vs. anonymity trade-off

S1 Overview: Onion Routing / Anonymous Transport Libraries#

Research ID: 1.066 Pass: S1 — Rapid Discovery Date: 2026-02-17

The Core Taxonomy#

Anonymous transport systems differ on the fundamental question: what adversary are you protecting against?

The central trade-off: Higher anonymity requires fake traffic (cover traffic) and timing delays, which kills interactive use cases. Tor is the sweet spot for most practical applications; Nym/Katzenpost are for adversarial environments where global traffic analysis is a real threat.

Category 1: Tor#

The dominant anonymity network. A volunteer-run network of ~7,000 relays. Traffic passes through 3 hops (guard → middle → exit) with layered encryption.

Python access:

stem — Official Tor Control Library#

The Python library for speaking the Tor control protocol.

• Monitors Tor status, creates custom circuits, manages hidden services
• Does NOT route traffic through Tor by itself — it controls the Tor daemon
• Stars: ~1.1k GitHub
• Maintenance: Active (Tor Project maintains it)

import stem
from stem.control import Controller

with Controller.from_port(port=9051) as controller:
    controller.authenticate()
    # Build a specific circuit
    circuit_id = controller.new_circuit(['relay1_fingerprint', 'relay2_fingerprint', 'exit_fingerprint'])
    # List current circuits
    for circuit in controller.get_circuits():
        print(circuit)

SOCKS5 Proxy (requests / aiohttp)#

The simplest path: Tor listens on 127.0.0.1:9050 as a SOCKS5 proxy.

import requests

proxies = {
    'http': 'socks5h://127.0.0.1:9050',
    'https': 'socks5h://127.0.0.1:9050'
}
resp = requests.get('https://check.torproject.org', proxies=proxies)

PySocks (aka socks) provides the low-level SOCKS5 support. requests[socks] bundles it.

torpy — Pure Python Tor Client#

A pure Python implementation of the Tor protocol. Does not require the Tor binary — implements onion circuit building from scratch.

• Stars: ~400 GitHub
• Use case: Embedding Tor in Python apps without system Tor daemon dependency
• Caveat: Community-maintained, not from Tor Project; security review limited

torsocks (not Python-specific)#

Linux LD_PRELOAD library that intercepts connect() syscalls and routes through Tor. Works for any application but is not a Python library.

Category 2: I2P (Invisible Internet Project)#

A parallel anonymous network focused on internal darknet services (eepsites). Uses garlic routing — bundling multiple encrypted messages into one container. Unidirectional tunnels.

Key difference from Tor: I2P is its own internet (.i2p addresses), not primarily a proxy to the clearnet.

SAM Bridge (Simple Anonymous Messaging)#

I2P’s programmatic API. A TCP socket protocol that lets external applications create I2P sessions, connect to destinations, listen for incoming connections.

• SAM v3.1: Actively maintained (spec updated 2025, accurate for I2P 0.9.66)
• Works for stream (TCP-like), datagram (UDP-like), and raw transports

i2plib (Python)#

Python async library wrapping the SAM bridge.

• Status: Inactive — no new PyPI releases in past year, marked stale
• Last version: 0.0.14
• If you need I2P from Python today: talk to SAM protocol directly via asyncio TCP socket, or use i2plib with eyes open on maintenance

Category 3: Nym Mixnet#

A next-generation anonymous transport using the Loopix mixnet design. Key differentiator: adds cover traffic and timing obfuscation to defeat global passive adversaries (nation-state traffic analysis).

How Nym works#

• 5-hop Sphinx packet routing through mixing nodes
• Each node adds random delays
• Cover traffic (“loop” and “drop” messages) fills in silence
• An observer watching all links cannot correlate sender and receiver

SDKs#

• Rust SDK: Official, production-ready
• TypeScript SDK: Official
• Python SDK: Does not exist (as of 2026)
• Access from Python: REST API via local NymVPN client, or build Rust FFI

Current status (2026)#

• NymVPN product launched
• Post-quantum roadmap: Outfox packet format to replace Sphinx (paper Dec 2024)
• Nym token (NYM) / staking for mix node operators

Category 4: Katzenpost#

A research-grade post-quantum mixnet. Written in Go with experimental Python and Android/Java bindings.

• Fixed-size Sphinx packets (eliminates size-based fingerprinting)
• Random exponential forwarding delays (Poisson mixing)
• Stratified topology (layers of mix nodes)
• Post-quantum: cryptographic agility (supports multiple KEMs/NIKEs)
• First post-quantum mixnet claim

Python: Experimental bindings only. Go is the primary language. Not suitable for production Python use.

Funding: NLnet (EU research infrastructure fund). Research-grade, not a product.

Category 5: Sphinx Packet Format#

The cryptographic packet format used by Nym, Katzenpost, and I2P. Compact, provably secure: indistinguishable replies, hides path length and position, detects tagging attacks.

Python implementation#

UCL-InfoSec/sphinx: Python implementation of the Sphinx mix format. Academic/research use.

Post-quantum successor#

Outfox (Dec 2024 paper): Replaces Sphinx’s Diffie-Hellman with KEMs (Key Encapsulation Mechanisms). Lighter, post-quantum secure. Proposed for Nym and Katzenpost.

Preliminary Library Summary#

Sources#

• Tor Project / stem
• Nym mixnet
• Katzenpost GitHub
• I2P SAM v3 spec
• i2plib PyPI
• UCL-InfoSec/sphinx
• Outfox paper (arXiv 2412.19937)

S1 Recommendation: Rapid Discovery#

Preliminary Winners#

Confidence#

High on stem + SOCKS5 pattern (Tor Project-backed, widely used). Low on torpy (not Tor Project, limited audit). Medium on I2P (protocol stable, library inactive). Medium on Nym (active project, no Python path).

S1 Synthesis: Onion Routing / Anonymous Transport Libraries#

Core Finding#

This domain is unusual: the dominant system (Tor) has excellent Python support. But the anonymity guarantees of Tor are limited — it protects against a moderate, non-global adversary. For stronger guarantees against traffic analysis, you need Nym or Katzenpost, neither of which has Python support.

The Three Tiers#

Tier 1 — Practical (Tor): Well-supported in Python, reasonable latency (~150-500ms), widely used. Protects IP address and routing from the destination and intermediate nodes. Does NOT protect against an adversary who can see both endpoints’ traffic (global passive adversary).

Tier 2 — Darknet (I2P): Self-contained anonymous network. Good for running internal services. Python library (i2plib) is inactive; SAM protocol is stable but requires DIY integration.

Tier 3 — Mix Networks (Nym, Katzenpost): Protects against global passive adversaries via cover traffic and timing obfuscation. Latency measured in seconds. No Python SDKs. Research/infrastructure grade.

What S2 Must Resolve#

• stem’s circuit-building capabilities in detail
• torpy security posture: can it be trusted for sensitive use?
• Nym’s websocket API (accessing from Python without SDK)
• I2P SAM protocol detail — is it manageable to use directly?
• Tor hidden services (v3): what stem provides
• Typical Tor latency budget in practice

S2 Approach: Comprehensive Analysis#

Objective: Deep-dive each system’s architecture, Python integration paths, latency characteristics, and anonymity guarantees. Establish the adversary model for each tier.

Topics examined:

1. Tor circuit construction, stem API, SOCKS5 pattern, onion services v3
2. torpy: pure Python Tor — what does it actually implement?
3. I2P garlic routing, SAM bridge protocol detail
4. Nym: Loopix design, Sphinx routing, cover traffic mechanics, websocket API
5. Katzenpost: Go architecture, experimental Python bindings
6. Sphinx packet format: what it guarantees, UCL-InfoSec Python impl
7. Latency budgets for each system
8. Adversary models: who does each system protect against?

S2 Comprehensive Analysis: Onion Routing / Anonymous Transport#

Research ID: 1.066 Pass: S2 — Comprehensive Analysis Date: 2026-02-17

1. Adversary Models — The Foundation#

Anonymous transport systems are only meaningful relative to a specific adversary model. The key spectrum:

Local adversary: Can see traffic at one point in the network (e.g., your ISP). A VPN or Tor defeats this.

Moderate adversary: Can monitor some nodes or links, compromise some relays. Tor defeats this with 3-hop circuits (no single node sees both source and destination).

Global passive adversary (GPA): Can observe all network traffic simultaneously. Classic national-level adversary. Tor does NOT defeat this — timing correlation attacks deanonymize Tor circuits with high accuracy. Nym and Katzenpost are designed for this threat model.

Active adversary: Can modify traffic, inject packets, take down nodes. Sphinx’s tagging attack resistance is relevant here.

2. Tor — Deep Dive#

Circuit Construction#

A Tor circuit has three hops:

1. Guard node (entry guard): a long-lived trusted relay that knows your real IP
2. Middle relay: knows only the guard and exit
3. Exit node: connects to the destination; sees destination but not origin

Each hop gets one layer of encryption. The origin encrypts for exit, then middle, then guard. Each relay peels one layer.

stem circuit building:

from stem.control import Controller
import stem

with Controller.from_port(port=9051) as ctrl:
    ctrl.authenticate()

    # Create circuit through specific relays (by fingerprint)
    circuit_id = ctrl.new_circuit(
        path=['FINGERPRINT1', 'FINGERPRINT2', 'FINGERPRINT3'],
        await_build=True
    )

    # Attach a stream to a specific circuit
    def attach_stream(stream):
        if stream.status == 'NEW':
            ctrl.attach_stream(stream.id, circuit_id)

    ctrl.add_event_listener(attach_stream, stem.control.EventType.STREAM)

stem can:

• List all current circuits and streams
• Build circuits through specified relays
• Create ephemeral onion services
• Monitor Tor events (circuit build, stream attach, bandwidth)
• Get relay descriptors and consensus data
• Signal Tor to generate new identity (new IP)

stem cannot (by itself): route traffic. You still need the Tor SOCKS5 proxy for that.

Tor v3 Onion Services (Hidden Services)#

Onion services provide anonymous servers — the server’s location is hidden, not just the client’s. A v3 onion address is 56 characters (ed25519 key), e.g., facebookwkhpilnemxj7ascrwwwdbkzjwjohqvzplezdbwrfamkdqiqd.onion.

Ephemeral onion services with stem:

from stem.control import Controller

with Controller.from_port() as ctrl:
    ctrl.authenticate()

    # Create ephemeral v3 onion service (key generated by Tor)
    response = ctrl.create_ephemeral_hidden_service(
        ports={80: 8080},  # onion port 80 → local port 8080
        await_publication=True
    )
    print(f"Service address: {response.service_id}.onion")
    # Service lives until this script exits (ephemeral)

Persistent onion services: Write the key to disk; service survives restarts.

Tor Latency Budget#

Typical Tor round-trip latency (clearnet destination, from benchmark data):

• Minimum (good path): ~100ms
• Typical: 150-500ms
• Congested/long path: 500ms-3s

Key contributors:

• Guard RTT: 20-100ms (geographic)
• Middle relay processing: 10-50ms
• Exit relay processing and destination: 20-200ms
• Queue and congestion: variable

Implication: HTTP APIs, web scraping, anonymous browsing — fine. Video calls, real-time games — not suitable.

torpy — Pure Python Tor#

torpy implements the Tor protocol directly in Python, without needing the Tor daemon:

• Creates TLS connections to Tor relays
• Performs Tor’s ntor handshake (Curve25519)
• Builds onion circuits
• Wraps connections in circuit layers

Security caveat: Not from the Tor Project. Implements a subset of the Tor spec. Has not received the security scrutiny of the official Tor daemon (C). Use only when the Tor daemon genuinely cannot be installed (e.g., serverless environments).

Maintenance: Community-maintained, ~400 GitHub stars.

3. I2P — Deep Dive#

Garlic Routing vs. Onion Routing#

Why unidirectional tunnels: Security property — separating inbound and outbound traffic means a compromised node can only see traffic in one direction. The cost is doubled tunnel count.

SAM Bridge Protocol#

The SAM (Simple Anonymous Messaging) bridge is I2P’s programmatic interface — a text protocol over TCP to 127.0.0.1:7656.

SAM v3 session creation:

→ HELLO VERSION MIN=3.1 MAX=3.1\n
← HELLO REPLY RESULT=OK VERSION=3.1\n

→ SESSION CREATE STYLE=STREAM ID=mysession DESTINATION=TRANSIENT\n
← SESSION STATUS RESULT=OK DESTINATION=<base64-encoded-I2P-destination>\n

→ STREAM CONNECT ID=mysession DESTINATION=<target-destination>.b32.i2p\n
← STREAM STATUS RESULT=OK\n

After STREAM STATUS RESULT=OK, the socket becomes a bytestream to the I2P destination.

i2plib wraps this in asyncio. It’s inactive but the code is simple enough to use or fork for SAM v3 client sessions.

DIY SAM in Python (minimalist):

import asyncio

async def connect_to_i2p(destination_b32):
    reader, writer = await asyncio.open_connection('127.0.0.1', 7656)
    writer.write(b'HELLO VERSION MIN=3.1 MAX=3.1\n')
    await reader.readline()  # HELLO REPLY
    writer.write(b'SESSION CREATE STYLE=STREAM ID=mysession DESTINATION=TRANSIENT\n')
    await reader.readline()  # SESSION STATUS
    writer.write(f'STREAM CONNECT ID=mysession DESTINATION={destination_b32}\n'.encode())
    result = await reader.readline()  # STREAM STATUS
    # Now use reader/writer as the I2P stream
    return reader, writer

4. Nym — Deep Dive#

Loopix / Mixnet Design#

Nym is based on the Loopix design (2017 academic paper). Key properties:

Fixed topology: Mix nodes arranged in layers. Each packet traverses a fixed number of hops (5 in production).

Poisson mixing: Each mix node delays packets by a random amount drawn from a Poisson distribution. This prevents timing correlation — an adversary observing input and output of a node cannot easily match packets.

Cover traffic: Each client continuously sends “loop” messages (to itself) and “drop” messages (to random destinations). This makes traffic indistinguishable from real traffic, even when the user is idle.

Sphinx packet format: All packets are fixed-size and look identical. No size-based fingerprinting.

Result: Unlike Tor, Nym provides anonymity against a global passive adversary who watches all network links simultaneously.

Python Access Path#

Nym has no Python SDK. The practical Python path is:

1. Run the Nym client daemon locally (Rust binary)
2. Connect via its WebSocket API on ws://localhost:1977
3. Send/receive JSON messages

import asyncio
import websockets
import json

async def send_via_nym(recipient_address, message):
    async with websockets.connect('ws://localhost:1977') as ws:
        # Get own address
        await ws.send(json.dumps({"type": "selfAddress"}))
        addr_resp = json.loads(await ws.recv())

        # Send message through mixnet
        payload = json.dumps({
            "type": "send",
            "message": message,
            "recipient": recipient_address,
            "withReplySurb": True  # anonymous reply capability
        })
        await ws.send(payload)

Latency: Seconds, not milliseconds. The cover traffic and delays make Nym unsuitable for interactive protocols.

Nym SDKs (official)#

• Rust SDK: nym-sdk crate. Full programmatic access to Nym mixnet.
• TypeScript SDK: Modules for mixnet, Nyx blockchain, Coconut credentials.

5. Katzenpost — Deep Dive#

Architecture#

Katzenpost is a decryption mixnet with stratified topology (not Loopix-style but similar intent):

• Mix nodes: Arranged in layers; each layer decrypts one Sphinx layer
• Providers: Entry/exit points for clients
• PKI: Provides authenticated directory of mix nodes (can be decentralized)

Fixed-size messages: All Sphinx packets are the same size. Variable-length payloads are padded. This eliminates packet-size correlation attacks.

Exponential delays: Each mix node delays packet by a random exponential time. An observer cannot tell when a packet entered by when it exits.

Post-quantum: Cryptographic agility means Katzenpost can use post-quantum KEMs (MLKEM, CTIDH) instead of classical Diffie-Hellman.

Python Access#

Katzenpost’s Python bindings are experimental (katzenpost/client2 or older bindings). Not production-ready. Primary language is Go.

For Python applications: call a Katzenpost Go client via subprocess or gRPC.

6. Sphinx Packet Format#

The cryptographic onion packet format used by I2P (partially), Nym, and Katzenpost.

Guarantees:

• Unlinkability: An observer cannot link the packet entering a hop to the packet exiting
• Path confidentiality: Each hop sees only its own routing info; path length hidden
• Replay protection: Detects and rejects replayed packets
• Tagging attack detection: Modified packets are discarded

Python implementation: UCL-InfoSec/sphinx — academic, implements the 2009 George Danezis paper. Not a production library.

Outfox (Dec 2024): Post-quantum successor. Replaces ECDH key exchange in Sphinx with KEMs. Lighter computation. Proposed for Nym and future systems.

7. Key Technical Findings#

1. For Python + Tor: Use stem + SOCKS5. It’s clean, well-documented, and actively maintained by the Tor Project. Don’t use torpy unless you absolutely cannot run the Tor daemon.

2. Tor’s anonymity limit: Tor does not protect against a global passive adversary. Timing correlation attacks have ~90%+ accuracy against Tor given a global view. For most real-world threat models, Tor is sufficient; for state-level adversaries, it’s not.

3. I2P Python is a DIY project: i2plib is inactive. The SAM protocol is simple enough to implement directly (~50 lines of asyncio). But I2P itself has a smaller network (fewer nodes, less bandwidth) than Tor.

4. Nym adds cover traffic — that’s the key difference: Cover traffic is what makes Nym resistant to global traffic analysis. Tor has no cover traffic; a global observer can do traffic analysis. Nym’s cost is latency (seconds).

5. Katzenpost is research-grade: Excellent cryptographic design (post-quantum, formally verified Sphinx), but not a production SDK. Funding is from NLnet (research). For production applications, it’s not ready.

6. No Python SDK for Nym: The websocket interface to the Nym client daemon is the practical Python path. Simple JSON protocol.

Sources#

• stem documentation
• Tor Project — design paper
• I2P SAM v3 spec
• i2plib GitHub
• Nym mixnet
• Nym SDK docs
• Katzenpost GitHub
• UCL-InfoSec/sphinx GitHub
• Outfox paper (arXiv 2412.19937)
• torpy PyPI
• Loopix design paper (2017)

S2 Recommendation: Comprehensive Analysis#

Core Decision: What Adversary Are You Protecting Against?#

Local/national ISP or network monitor → Tor (stem + SOCKS5) Most real-world use cases. Excellent Python support.

Global traffic analysis adversary (nation-state with full network view) → Nym Via local Nym client daemon websocket API. Latency in seconds.

Post-quantum adversary / research → Katzenpost Go only. Experimental Python. Not production-ready.

Library Slots (Confirmed)#

S2 Synthesis: Onion Routing / Anonymous Transport#

What S2 Confirmed from S1#

• stem + SOCKS5 is the right Python Tor path (confirmed: Tor Project-maintained, clean API)
• i2plib confirmed inactive; SAM protocol accessible directly (~50 lines asyncio)
• Nym has no Python SDK; websocket interface to local client daemon is the Python path
• Katzenpost: research-grade Go, experimental Python bindings, not production-ready

What S2 Added#

Adversary model is the key dimension: Tor for local/moderate adversaries; Nym/Katzenpost for global passive adversaries. Most applications need only Tor.

Tor circuit building via stem: Full programmatic control — attach streams to specific circuits, create ephemeral onion services, monitor events. Much more powerful than just proxying.

I2P SAM protocol is simple: ~50 lines of asyncio to talk to SAM v3. The Python library being inactive is not a blocker.

Nym cover traffic is the differentiator: Nym’s continuous cover traffic is what makes it resistant to global traffic analysis. The cost is latency measured in seconds. This rules out interactive use.

torpy warning: Not from Tor Project; not as audited as the C daemon. Use only when the Tor daemon cannot be deployed.

Recommended Slots#

S3 Approach: Need-Driven Discovery#

Objective: Identify real-world use cases for anonymous transport, then work backward to which Python library or pattern satisfies each need. Distinguish the primary personas and their actual constraints.

Topics examined:

1. Security researcher / penetration tester: anonymized scanning and enumeration
2. Journalist / whistleblower tooling: secure document drop, anonymous submission
3. Privacy-preserving crawler / scraper: bypassing geo-restrictions, avoiding fingerprinting
4. Onion service operator: running an anonymous Python server
5. High-stakes anonymous communication: state-level adversary, metadata protection
6. Constrained environment: no root, no Tor daemon install, serverless/container
7. Comparing the options by constraint matrix (no daemon, no root, latency tolerance)

S3 Library Comparison: By Need Matrix#

Comparison Matrix#

Decision Tree#

Need anonymous HTTP/HTTPS in Python?
├── Can you run the Tor daemon?
│   ├── YES → requests + SOCKS5 via Tor daemon (+ stem for control)
│   └── NO  → torpy (with security caveat)
│
Need to host an anonymous server?
└── YES → stem ephemeral/persistent onion service
    └── (No alternative exists in Python)
│
Need to defeat a global passive adversary (nation-state)?
├── Interactive? → Nothing truly satisfactory (Nym latency is seconds)
└── Async/batch? → Nym websocket API (requires Nym daemon)
│
Need I2P access?
└── DIY SAM v3 client (~50 lines asyncio) or fork i2plib
│
Research / post-quantum?
└── Katzenpost (Go) + subprocess or gRPC bridge

stem vs torpy: Detailed Comparison#

Recommendation: Use stem for all production use. torpy only if daemon installation is truly impossible.

Nym vs Katzenpost: When Does Post-Tor Matter?#

Bottom line: Neither has a Python SDK. Nym is closer to production. Katzenpost is for researchers building PQ privacy systems.

Anonymity Guarantee Comparison#

Key insight: For 99% of use cases (bypassing ISP/corporate monitoring, protecting location from server), Tor is sufficient. Nym/Katzenpost are specifically for the scenario where an adversary can observe all network traffic simultaneously.

Packaging and Deployment Complexity#

Deployment insight: Tor binary is widely available (apt/brew/Docker). For containerized deployments, the Tor Project provides official Docker images. torpy is truly zero-dependency (beyond Python stdlib + optional requests).

S3 Recommendation: Need-Driven#

By Use Case#

Anonymous HTTP scraping/browsing → requests + SOCKS5 + Tor daemon Standard pattern. Works with all Python HTTP libraries. Add stem for IP rotation.

Anonymous server (onion service) → stem No alternative. stem is the only Python library for ephemeral/persistent onion service creation.

No-daemon environment → torpy Last resort. Less secure than official Tor, but works without system installation.

Nation-state level anonymity (GPA threat) → Nym websocket API Only option with cover traffic. Accept the latency cost (seconds). Async use only.

I2P internal network → DIY SAM client i2plib is inactive; 50-line asyncio implementation is sufficient. Smaller network than Tor.

Post-quantum research → Katzenpost (Go) Not Python-ready. Use via subprocess/gRPC if needed.

Single-Line Summary#

For most Python applications, the answer is: pip install stem requests[socks] and run the Tor daemon.

S3 Use Cases: Onion Routing / Anonymous Transport#

Use Case 1: Async Anonymous HTTP (aiohttp + aiohttp-socks)#

Who: Developer building an async application (crawler, API client) that needs anonymous HTTP with asyncio.

Constraints:

• Async codebase; requests is synchronous and doesn’t fit
• Multiple concurrent requests through Tor
• Can run Tor daemon

Solution:

import aiohttp
from aiohttp_socks import ProxyConnector

async def fetch_anonymous(url: str) -> str:
    connector = ProxyConnector.from_url('socks5h://127.0.0.1:9050')
    async with aiohttp.ClientSession(connector=connector) as session:
        async with session.get(url) as resp:
            return await resp.text()

Why aiohttp-socks: Drop-in async connector for aiohttp. Supports SOCKS4, SOCKS5, HTTP CONNECT, and proxy chains. Actively maintained (237 stars, releases through 2025). Install: pip install aiohttp aiohttp-socks.

Note: Use socks5h:// (not socks5://) to force DNS resolution through Tor. Critical for .onion addresses; also prevents DNS leaks on clearnet requests.

Use Case 2: Privacy-Preserving Web Scraper (sync)#

Who: Developer building a crawler that must not be IP-blocked or fingerprinted.

Constraints:

• Multiple HTTP requests; requests must come from varied exit IPs
• Python ecosystem; must integrate with requests
• Latency ≤ 2-3 seconds per request (acceptable for scraping)
• Can run Tor daemon (root or user-local install)

Solution:

import requests
import stem.process
import stem.control

# Start Tor with circuit renewal capability
tor_process = stem.process.launch_tor_with_config(config={
    'SocksPort': '9050',
    'ControlPort': '9051',
    'DataDirectory': '/tmp/tor_data',
})

proxies = {'http': 'socks5h://127.0.0.1:9050', 'https': 'socks5h://127.0.0.1:9050'}

# Rotate exit IP between requests
with stem.control.Controller.from_port() as ctrl:
    ctrl.authenticate()
    ctrl.signal(stem.Signal.NEWNYM)  # Request new circuit

response = requests.get('https://target.com', proxies=proxies)

Why stem + SOCKS5: Programmatic IP rotation via NEWNYM signal. Clean requests integration. Production-quality.

Use Case 3: Anonymous Onion Service (Hidden Server)#

Who: Developer building a server whose real IP must never be disclosed. Examples: SecureDrop-style submission system, whistleblower portal, research node.

Constraints:

• Python HTTP server (Flask, FastAPI)
• Server location must be hidden from connecting clients
• Must survive the server restarting (persistent onion address)

Solution (ephemeral — for testing):

from stem.control import Controller
from flask import Flask

app = Flask(__name__)

@app.route('/')
def index():
    return 'Hello from the onion!'

with Controller.from_port() as ctrl:
    ctrl.authenticate()
    service = ctrl.create_ephemeral_hidden_service(
        ports={80: 5000},
        await_publication=True
    )
    print(f'Available at: {service.service_id}.onion')
    app.run(port=5000)  # service dies when this exits

Persistent variant: Use key_type='NEW' + key_content='ED25519-V3' and save the returned private key to disk. Pass it back on next startup.

Why stem: Only Python library with native ephemeral/persistent onion service creation. No alternatives.

Use Case 4: Journalist / SecureDrop-Style Tool#

Who: Journalist accepting documents from sources who need plausible deniability.

Constraints:

• Source must be able to submit anonymously from Tor Browser
• Server cannot know source IP
• Reply capability needed (anonymous reply to source)
• High reliability (production system)

Solution: Run an onion service (stem) + accept only .onion connections.

Architecture:

Source (Tor Browser) ─── Tor network ──→ .onion address ──→ Flask app
                                              ↑
                              stem ephemeral onion service

For reply surbs: Nym’s SURB (Single Use Reply Block) mechanism enables anonymous replies without revealing the source’s address. But latency is seconds — suitable for async reply, not interactive.

Note: SecureDrop (the production system) uses Tor onion services + HTTPS. It does NOT use Nym or Katzenpost. This is the right choice for the realistic threat model (not a global passive adversary).

Use Case 5: Security Research — Anonymous Enumeration#

Who: Penetration tester or OSINT researcher who needs to query targets without revealing their own IP.

Constraints:

• Various tools: nmap, whois, shodan API, HTTP requests
• Must not be attributable to the researcher
• Latency: seconds acceptable; minutes not

Solution:

import socks
import socket
import requests

# For requests:
proxies = {'http': 'socks5h://127.0.0.1:9050', 'https': 'socks5h://127.0.0.1:9050'}
resp = requests.get('https://api.shodan.io/shodan/host/1.2.3.4', proxies=proxies)

# For raw socket operations (e.g., with tools that support proxy chains):
# Use proxychains-ng or torsocks at OS level
# torsocks nmap -sV target.com

Limitation: Tor exit nodes are publicly listed. Targets can block Tor exit IPs (and many do). For exit-blocking evasion, obfuscation bridges (obfs4, meek) are needed — configurable via Tor control via stem.

Use Case 6: High-Stakes Anonymous Messaging (Nation-State Adversary)#

Who: Activist or journalist operating in a country with deep packet inspection and full traffic correlation capability.

Constraints:

• Adversary can see all traffic (global passive adversary)
• Standard Tor is insufficient — timing correlation will deanonymize
• Latency: asynchronous messages OK (minutes acceptable)
• Python client acceptable

Solution: Nym mixnet via websocket API.

import asyncio
import websockets
import json

async def send_anonymous_message(recipient_nym_address, message_text):
    async with websockets.connect('ws://localhost:1977') as ws:
        payload = json.dumps({
            "type": "send",
            "message": message_text,
            "recipient": recipient_nym_address,
            "withReplySurb": True
        })
        await ws.send(payload)
        # Delivery confirmation
        response = json.loads(await ws.recv())
        return response

Prerequisites: Nym client daemon running locally (nym-client binary).

Why Nym: Cover traffic prevents global traffic analysis. Latency cost (seconds) is acceptable for asynchronous messaging.

Why not Tor: A nation-state adversary monitoring all links can correlate timing of Tor circuits with ~90% accuracy.

Use Case 7: Constrained Environment (No Daemon, No Root)#

Who: Developer in a serverless, container, or shared hosting environment where the Tor daemon cannot be installed.

Constraints:

• Cannot install system packages
• Cannot run persistent background processes
• Python only

Solution: torpy (pure Python Tor implementation).

from torpy.http.requests import TorRequests

with TorRequests() as tor_requests:
    with tor_requests.get_session() as session:
        resp = session.get('https://check.torproject.org')
        print(resp.text)

Security caveat: torpy is not from the Tor Project, has less audit than the C daemon, and implements a subset of the Tor spec. Use only as a last resort.

Better alternative: If possible, use a Tor SOCKS5 proxy provided by the infrastructure (many cloud providers and CDNs offer Tor exits or proxy services).

Use Case 8: I2P Internal Network Communication#

Who: Developer building communication between services that should only be reachable within the I2P network (not via clearnet).

Constraints:

• All participants run I2P node
• Services communicate exclusively within I2P (eepsites, i2p addresses)
• Python client

Solution: DIY SAM v3 client.

import asyncio

class I2PSAM:
    def __init__(self, host='127.0.0.1', port=7656):
        self.host = host
        self.port = port

    async def connect(self, destination_b32: str):
        reader, writer = await asyncio.open_connection(self.host, self.port)
        writer.write(b'HELLO VERSION MIN=3.1 MAX=3.1\n')
        await reader.readline()
        writer.write(b'SESSION CREATE STYLE=STREAM ID=sess1 DESTINATION=TRANSIENT\n')
        line = await reader.readline()
        # Parse own destination from SESSION STATUS
        writer.write(f'STREAM CONNECT ID=sess1 DESTINATION={destination_b32}\n'.encode())
        status = await reader.readline()
        if b'RESULT=OK' in status:
            return reader, writer
        raise ConnectionError(f'SAM connect failed: {status}')

Library state: i2plib is inactive. The SAM protocol is simple enough (~50 lines) to implement directly. For serious use, fork i2plib.

Tradeoff vs Tor: I2P has a smaller network (fewer nodes, lower bandwidth). I2P is optimized for internal darknet use; Tor for anonymous clearnet access.

S4 Strategic Analysis: Onion Routing / Anonymous Transport#

Research ID: 1.066 Pass: S4 — Strategic Analysis Date: 2026-02-17

1. Funding and Maintenance Trajectory#

Tor Project#

Funding: US federal grants (NSF, State Department), foundations (Ford, Mozilla), individual donors. ~$10M/year organization. Politically sensitive — has faced funding cuts under certain administrations.

Trajectory: Tor is ~20 years old and has survived multiple funding crises. The C daemon is stable and slow-moving. stem (Python library) is actively maintained and part of the Tor Project organization.

Risk: stem’s maintainer base is small (~2-3 active contributors). If stem development stalls, the underlying SOCKS5/control port interface remains stable and can be used directly.

Protocol stability: Tor’s SOCKS5 interface and control port protocol have been stable for 10+ years. Code written against it today will work in 5 years.

torpy#

Funding: Individual/community maintained. No organizational backing.

Trajectory: ~400 GitHub stars. Sporadic commits. Not a dependency you’d want to bet a production system on.

Risk: Could go unmaintained. The Tor protocol itself doesn’t change often, but security patches to the C daemon won’t appear in torpy.

I2P / i2plib#

Funding: The I2P router (Java) is maintained by the I2P Project. i2plib (Python) is unmaintained.

Trajectory: I2P router is stable and maintained. The Python SAM client code you write yourself won’t have maintenance issues (it’s 50 lines, no library dependency on i2plib).

Risk: i2plib is dead. DIY SAM code is fine for the foreseeable future — the SAM v3 protocol is stable.

Nym#

Funding: Raised ~$300M in token sales (2021-2022). Foundation + venture backing (a16z, Polychain).

Trajectory: Active development (Rust). The Python path is via websocket to local daemon — not an official SDK. If Nym changes the websocket protocol, your Python code breaks.

Risk: Protocol churn risk is moderate. Nym is still evolving. The absence of an official Python SDK means you’re depending on an undocumented internal interface.

Strategic note: Nym’s token economics create sustainability incentives (node operators earn tokens). This is a different funding model than traditional open source and has both benefits (economic incentives for network participants) and risks (regulatory exposure, token value volatility affecting development).

Katzenpost#

Funding: NLnet Foundation grants (EU). Academic/research funding.

Trajectory: Active research project. Not production software. Python bindings are experimental.

Risk: High for production use. The project could pivot, lose funding, or be abandoned. For research purposes, it’s fine.

2. Protocol Stability#

3. Regulatory and Legal Risk#

Tor: Legal in virtually all jurisdictions to run and use. Exit nodes have faced some legal pressure (hosting providers getting copyright notices). Running a Python client → Tor is clearly legal for legitimate use.

I2P: No significant legal issues. Smaller footprint means less attention.

Nym: Token sales have regulatory exposure in some jurisdictions (SEC scrutiny of crypto projects). The network itself is legal to use.

Katzenpost: Academic project with no legal risk.

Key caveat: Using anonymous transport for illegal activity is illegal in all jurisdictions. The tools themselves are legal. Note that some countries (China, Russia, Iran) block or restrict Tor access — using Tor bridges may be necessary in those environments.

4. Lock-in Analysis#

Switching cost between Tor options (stem ↔ SOCKS5 direct): Near zero. stem wraps the same interfaces.

Switching from Tor to Nym: High effort. Completely different protocol, different latency characteristics, different daemon requirement. Not a drop-in replacement.

Switching from Tor to I2P: Medium effort. SAM protocol has different semantics (stream-based vs circuit-based). I2P network doesn’t access clearnet by default.

Abstraction layer option: A thin abstraction that routes traffic to Tor or Nym based on configuration is feasible for simple HTTP use cases. Not standardized.

Recommendation: Don’t over-engineer. Pick Tor for the default case and only add Nym if you have a clear GPA threat model requirement.

5. Emerging Threats and Trends#

Traffic Correlation Attacks Improving#

Academic research on timing correlation attacks against Tor is advancing. The attack success rate has gone from ~70% to ~90%+ in recent years. Tor’s threat model has always acknowledged this; it’s not a new problem.

Implication: Applications with a GPA threat model (journalists in adversarial states, high-value targets) should seriously evaluate Nym. For most applications (bypassing ISP monitoring, accessing geo-blocked content), Tor remains the correct choice.

Post-Quantum Transition#

Current Tor circuits use classical Diffie-Hellman (ntor handshake). Tor has been working on hybrid PQ/classical circuits (NTOR-V3), but full deployment is pending.

Katzenpost already uses PQ KEMs. This will matter in 5-10 years when quantum computers capable of breaking elliptic curve crypto become feasible.

Implication: For long-lived systems that need PQ anonymity, Katzenpost is the research path. For near-term production systems, Tor is fine.

Censorship Circumvention#

Tor’s main censorship bypasses:

• obfs4 bridges: Obfuscated transport that disguises Tor traffic as random bytes
• meek: Fronted via CDN (Azure, Fastly) — looks like legitimate CDN traffic
• Snowflake: WebRTC-based, routes through volunteer proxies

stem can configure and use these transports via the Tor control port:

ctrl.set_options({'Bridge': 'obfs4 <bridge-address>'})

Implication: For deployment in censored environments, Tor + bridges is the practical solution. Nym faces similar censorship risks since its traffic is distinctive.

Edge Deployments (WASM, Serverless)#

torpy has been discussed (but not finalized) for compilation to WASM. This could enable browser-side Tor circuits without a daemon — useful for browser extensions or edge workers.

Current state: Not production-ready. Watch this space.

6. Strategic Summary#

The safe default (2026 and beyond): stem + Tor daemon. This has been the correct answer for 10+ years and will remain so for the foreseeable future. The SOCKS5 interface is eternal.

The right forward bet for high-stakes anonymity: Nym. Cover traffic is the right technical direction. The lack of a Python SDK is a current friction, not an architectural flaw. When Nym releases an official Python SDK, the migration will be straightforward.

The research bet for post-quantum: Katzenpost. Not production today, but the cryptographic design is sound. If your threat model includes quantum adversaries in a 5-10 year horizon, track Katzenpost.

What to avoid:

• torpy in production (insufficient audit)
• i2plib (abandoned)
• Building on undocumented Nym websocket protocol for production systems

S4 Approach: Strategic Analysis#

Objective: Assess the long-term viability, ecosystem health, and strategic risks of each anonymous transport option for Python projects.

Topics examined:

1. Maintenance trajectory: who funds these projects and why?
2. Protocol stability: will your Python code break in 2-3 years?
3. Regulatory risk: are any of these facing legal pressure?
4. Lock-in analysis: how easy is it to swap one for another?
5. Emerging threats: what’s changing in the threat landscape?
6. Final recommendation: the safe default vs. future-looking choice

Strategic Viability: Nym and Katzenpost#

Nym#

Organizational Health#

Nym Technologies (later Nym Network Foundation) is a VC-backed company with roots in the Loopix academic paper (2017). Raised ~$300M in token sales (2021-2022, pre-bear market peak). Investors include a16z crypto, Polychain Capital.

The Rust SDK (nym-sdk crate) and TypeScript SDK are actively maintained (2024). The Python path (websocket to daemon) is not officially supported.

Protocol Stability Risk#

The websocket API used for Python integration is not documented as a stable API. Protocol messages and fields can change between Nym client daemon versions.

Mitigation: Pin to a specific daemon version. Test against daemon updates before upgrading.

Token Economic Risk#

Nym’s network is sustained by token incentives (NYM token) — node operators earn tokens for forwarding traffic. This creates a different sustainability model than pure open source:

• Upside: Economic incentives align node operators with network health
• Downside: Token value volatility can affect node operator count; regulatory changes (SEC, MiCA) could affect the token’s legality in some jurisdictions

When Nym Makes Strategic Sense#

The case for Nym becomes clear when your threat model explicitly includes a global passive adversary. The cover traffic mechanism is the only practical defense against traffic correlation. If your threat model is “ISP or corporate network”, Tor is sufficient and simpler.

Strategic Verdict#

Python SDK: WATCH. Nym is technically sound but has no official Python SDK. The websocket interface is a workaround. Wait for official Python support before betting production systems on it.

For GPA threat model: BEST CURRENT OPTION. Katzenpost is research-only; Nym is in production beta with a real network. If you need GPA-resistant async messaging today, Nym is the practical choice.

Katzenpost#

Organizational Health#

Katzenpost is funded by NLnet Foundation (EU open source grants) and individual researchers. It is explicitly a research project with no commercial aspirations.

The project produced several academic papers on the Sphinx packet format and post-quantum extensions (Outfox, 2024). Core implementation language: Go.

Python Status#

Python bindings exist in katzenpost/client2 but are described as experimental. They wrap the Go client via CGo or subprocess. Not production quality.

Post-Quantum Advantage#

Katzenpost is the only mixnet with production post-quantum key exchange (MLKEM, CTIDH). This is 5-10 years ahead of what most applications need, but if your system must be secure against quantum adversaries today, Katzenpost is the only option.

Strategic Verdict#

Research only. Not a production Python library. Track for PQ readiness. Expected timeline to Python production SDK: unknown (no public roadmap).

Comparison: Long-Term Bets#

S4 Recommendation: Strategic Analysis#

Final Library Slots#

Long-Term Outlook#

stem + Tor: Durable 5-10 year bet. SOCKS5 protocol is stable. Tor has organizational backing.

Nym: Watch for official Python SDK. When it arrives, it becomes the production choice for GPA-threat use cases.

Katzenpost: Track for PQ readiness. Not production for years.

What Not to Build On#

• i2plib (dead)
• torpy (insufficient audit) for production security applications
• Undocumented Nym websocket protocol for production without version pinning

Strategic Viability: Tor (stem + SOCKS5)#

Organizational Health#

The Tor Project is a US 501(c)(3) nonprofit, incorporated 2006. Annual budget ~$10M. Primary funders: US State Department (DRL), NSF, Ford Foundation, Mozilla, individual donations.

The Tor Project employs ~30 full-time staff including core C daemon developers and stem maintainers.

stem is maintained within the Tor Project GitHub organization. It has been the standard Python Tor control library since ~2012. Last release: active (2024).

Protocol Longevity#

The Tor SOCKS5 proxy interface has been stable since Tor 0.1.x (~2004). It follows the standard RFC 1928 SOCKS5 protocol. This is as stable as network protocols get.

The Tor control protocol (used by stem) has had incremental additions but strong backwards compatibility. Code written against the current stem API will work against future Tor versions.

Network Size#

~7,000-8,000 relays. ~2 million daily users. Bandwidth: ~300-500 GB/s.

This is a mature network. Size ensures anonymity (more relays = smaller fraction that adversary can compromise). Growth has been stable for years.

Risk Factors#

1. Funding dependence on US government: If US foreign policy changes dramatically, DRL funding could be cut. Has happened partially before (2015); Tor survived.

2. Targeted by nation-states: China, Russia, Iran block Tor by default. Bridge infrastructure (obfs4, meek, Snowflake) mitigates this but requires configuration.

3. GPA vulnerability: Not a new finding but worth noting — timing correlation attacks have ~90%+ accuracy against a global passive adversary. The Tor Project’s stance: this is a known limitation; Tor is designed for the local/moderate adversary model.

4. stem maintainer concentration: Small team (~2 active maintainers). Risk of stalled development. Mitigated by: the control protocol is stable and rarely needs updates.

Strategic Verdict#

10-year confidence: HIGH. The SOCKS5 interface is eternal. stem is the canonical Python interface. Even if stem stopped receiving updates, the underlying protocol is stable enough to use directly. Tor as a network has survived 20 years and multiple funding crises.