spt-onion

Onion routing and traffic obfuscation with post-quantum ML-KEM encryption for SPT

Overview

spt-onion implements multi-layer onion routing using ML-KEM-768 key encapsulation and ChaCha20-Poly1305 symmetric encryption per hop. It includes circuit management, a mix network for batched message shuffling with dummy traffic, and traffic analysis resistance through pattern mimicking and protocol disguise. This crate is the transport privacy layer of the SPT network stack.

Key Features

• ML-KEM onion routing -- multi-layer encryption using ML-KEM-768 KEM + ChaCha20-Poly1305 per hop
• Circuit management -- build, activate, rotate, and tear down multi-hop circuits
• Mix network -- batched message processing with shuffling and dummy traffic injection
• Traffic analysis resistance -- pattern mimicking, burst obfuscation, flow correlation resistance
• Traffic obfuscation -- message normalization and protocol disguise (HTTP/TLS/WS/DNS)
• Metadata protection -- timestamp obfuscation, header randomization, IP anonymization

Dependencies

Key internal dependencies:

• spt-pq-crypto -- ML-KEM-768 key encapsulation for onion layers

Usage

use spt_onion::{MlKemOnionRouter, Circuit, CircuitManager, MixNode, MixConfig};

// Create an onion router
let router = MlKemOnionRouter::new();

// Build a circuit through relay nodes
let circuit = CircuitManager::new();

API Reference

Core Types

Type	Description
MlKemOnionRouter	Main onion router using ML-KEM-768 encryption
Circuit	A multi-hop onion circuit
CircuitManager	Manages circuit lifecycle (build/rotate/teardown)
OnionLayer	Single encryption layer with hop metadata
MixNode	Mix network node that batches and shuffles messages
DirectoryClient	Fetches relay node information
MetadataProtector	Strips/randomizes metadata from messages
TrafficAnalysisResistance	Configurable traffic analysis countermeasures
OnionError	Crate error type

Feature Flags

Feature	Default	Description
pq	yes	Post-quantum ML-KEM encryption
traffic-obfuscation	yes	Protocol disguise and message normalization