SRX — Stochastic Routing eXtended

A next-generation VPN protocol library for Rust.

Key features

• Multi-transport channel splitting — simultaneous operation over TCP, UDP, QUIC, WebSocket, gRPC, and HTTP/2-3 with stochastic transport selection
• QUIC multi-stream multiplexing - one QUIC connection can carry multiple logical bidi channels in parallel
• DPI evasion — protocol mimicry (TLS 1.3, HTTP/2 DATA, DTLS 1.2 record headers), jitter modeling, randomized padding, cover traffic, no static signatures
• Post-quantum cryptography — hybrid Kyber + X25519 key exchange with HKDF-SHA256 derivation
• Stochastic routing — seed-synchronized pseudo-random decisions for port hopping, transport selection, and traffic shaping
• Health-aware routing — per-transport RTT/failure tracking, automatic fallback when DPI blocks a transport
• gRPC TLS-first - secure https:// gRPC client path by default; plaintext requires explicit insecure API
• AEAD encryption — ChaCha20-Poly1305 or AES-256-GCM with automatic deterministic re-keying (both peers rotate keys at the same packet boundary)
• Persistent anti-replay protection - sliding 1024-packet replay window with pluggable storage backends (file, optional sqlite/redis), monotonic clustered merge (CAS+retry), replay snapshot integrity checks (checksum/hmac), and replay-store CAS telemetry counters
• Certificate pinning option - TLS TCP / WSS / QUIC clients can enforce SHA-256 certificate pins after handshake
• Cover traffic - background noise matching messenger/web/API profiles, indistinguishable from real data
• Obfuscated wire format — frame IDs are XOR-masked, no sequential counters visible on the wire
• In-band signaling — encrypted control signals (re-key, seed rotation, transport switch) embedded in normal traffic, indistinguishable from data
• Self-healing — automatic DPI interference detection with exponential backoff, seed rotation, and environment-aware transport reordering (Wifi/Cellular/Corporate)
• Decoy endpoints — external-facing HTTP endpoints (REST API, health-check, Prometheus metrics) that answer probes with plausible responses; hidden control data embedded via base64 payload injection

Installation

[dependencies]
stochastic-routing-extended = "1.0.2"

The library name is srx, so imports use the short form:

use srx::{SrxNode, SrxConfig};
use srx::config::{AeadCipher, MimicryMode};

For app-level usage without manual handshake wiring, use:

use srx::SecureTcpSession;

Feature flags

Quick start

High-level API (SrxNode)

use srx::{SrxNode, SrxConfig, TransportManager};

// Both peers share a master secret (from handshake).
let master = [0xAA; 32];
let config = SrxConfig::default();
// Replay state is persisted by default at ".srx/replay_state.json" (file backend).
// Optional: config.replay.backend = ReplayBackend::Sqlite { .. } / Redis { .. }
// Integrity defaults to SHA-256 checksum; for tamper-resistance use HMAC mode.
// HMAC key source is configurable:
// StaticConfig / EnvVar / File / Custom (app-registered provider).

// Build a node from the shared secret.
let mut node = SrxNode::from_master_secret(
    config,
    master,
    TransportManager::new(), // add transports before use
).unwrap();

// Prepare an encrypted, framed, mimicry-wrapped envelope.
let envelope = node.prepare_outgoing(b"hello SRX").unwrap();

// On the other side, process_incoming recovers the plaintext.
let plaintext = node.process_incoming(&envelope).unwrap();
assert_eq!(plaintext, b"hello SRX");

High-level secure session API (no manual handshake)

use srx::{SecureTcpSession, SrxConfig};

let cfg = SrxConfig::default();
let session = SecureTcpSession::connect("127.0.0.1:9000".parse().unwrap(), cfg).await?;
session.send_data(b"hello").await?;

Pipeline with real transport

use std::sync::Arc;
use srx::{
    SrxPipeline, Session, AeadPipeline, TransportManager, TcpTransport,
};
use srx::config::{AeadCipher, MimicryMode};
use srx::masking::padding::PaddingStrategy;
use srx::seed::SeedRng;
use srx::transport::{Transport, TransportKind};

// Shared session parameters (from handshake).
let seed = [0xAB; 32];
let key  = [0xCD; 32];
let aead = Arc::new(
    AeadPipeline::new(AeadCipher::ChaCha20Poly1305, &key, 0).unwrap()
);

// Connect a TCP transport.
// let tcp = TcpTransport::connect("127.0.0.1:9000".parse().unwrap()).await?;
// let mut mgr = TransportManager::new();
// mgr.add_transport(Arc::new(tcp));

// Build the pipeline.
let mut pipe = SrxPipeline::new(
    Session::new(1, seed, key),
    aead,
    PaddingStrategy::new(SeedRng::new(seed), 128),
    MimicryMode::Https,
    None, // jitter
    TransportManager::new(),
);

// Send: pad -> encrypt -> frame -> mimicry -> dispatch
// pipe.send(b"payload").await?;

// Recv: transport -> unwrap -> decode -> decrypt -> unpad
// let data = pipe.recv_from(TransportKind::Tcp).await?;

Handshake (3-message hybrid PQC/ECDH)

use srx::session::Handshake;

let mut client = Handshake::new_initiator();
let mut server = Handshake::new_responder();

let client_hello   = client.client_hello().unwrap();
let server_hello   = server.server_hello(&client_hello).unwrap();
let client_finished = client.finalize(&server_hello).unwrap();
server.server_finish(&client_finished).unwrap();

// Both sides now share the same master secret.
assert_eq!(client.master_secret(), server.master_secret());

Examples

The project ships with a full SRX messenger demo:

# Terminal 1 - server (monitor-only UI)
cargo run --example messenger_server -- 127.0.0.1:9000

# Terminal 2 - client alice
cargo run --example messenger_client -- 127.0.0.1:9000 alice

# Terminal 3 - client bob
cargo run --example messenger_client -- 127.0.0.1:9000 bob

Demo capabilities:

• Username auth and multi-client chat (broadcast + /w user msg).
• Tabbed console UI (Chat, Contacts, Metrics, Logs).
• SRX handshake + encrypted pipeline + in-band signaling.
• Automatic and manual transport rotation across all transport kinds.

See examples/README.md and examples/RUN.md.

Testing

Unit/integration tests and Criterion benchmark suites:

cargo test --all-features        # run all tests
cargo clippy --all-targets --all-features
cargo bench                      # Criterion benchmarks

Focused benchmark suites:

cargo bench --bench reconnect_overhead
cargo bench --bench rate_limiter
cargo bench --bench metrics_contention

Publish script

# Dry run (default)
powershell -ExecutionPolicy Bypass -File scripts/publish.ps1

# Real publish
powershell -ExecutionPolicy Bypass -File scripts/publish.ps1 -Publish

Architecture

See ARCHITECTURE.md for a detailed description of all modules and data flows.

License

Licensed under the Apache License, Version 2.0 (LICENSE).