phantom-protocol

Post-quantum-secure L4/L6 universal transport framework in Rust.

phantom-protocol gives applications an authenticated, confidential, post-quantum-secure byte pipe. It pairs a hybrid classical-plus-PQ handshake (X25519 + ML-KEM-768 KEM, Ed25519 + ML-DSA-65 signatures — FIPS 203 / FIPS 204, pure Rust) with a transport layer (TCP / WebSocket for sessions today; WASI and embedded byte-stream framing; KCP / FakeTLS / multipath as experimental legs) and adaptive fallback. Cross-language bindings via UniFFI (Python, Swift, Kotlin, C); native wasm32 target; bare-metal EmbeddedLeg for no_std.

Pre-1.0 (0.1.x). Wire format may break between minor versions; SemVer stabilizes at 1.0. The Rust crate is phantom-protocol; the import path is phantom_protocol.

Install

[dependencies]
phantom-protocol = "0.1"

or cargo add phantom-protocol.

Highlights

• Hybrid post-quantum handshake — X25519 + ML-KEM-768 KEM, Ed25519 + ML-DSA-65 signatures; both halves must verify. Pure-Rust RustCrypto primitives (no C in the crypto path) — compiles on native, mobile, and wasm32.
• 0-RTT resumption — AEAD-sealed early-data (≤ 16 KiB) folded into the single ClientHello, one-shot anti-replay, best-effort 1-RTT fallback.
• Mid-session rekey — HKDF ratchet with a per-stream sequence watermark that forces a rekey before any AEAD nonce can repeat.
• Per-stream replay protection — RFC 4303 §3.4.3 sliding-window bitmap, checked after AEAD verify.
• DoS-resistant handshake — stateless HMAC-SHA-256 cookie + adaptive blake3 proof-of-work.
• Observability — opt-in OpenTelemetry metrics + traces (telemetry-otel), lock-free hot-path atomics.
• FIPS posture — opt-in fips feature swaps in an AWS-LC-FIPS substrate (ECDH-P-256, AES-256-GCM, HKDF-SHA256, CTR_DRBG) with power-on self-tests.

Minimal client / server

Server identity must be pinned — connect_with_transport requires a HybridVerifyingKey; there is no skip path (a core security invariant).

use phantom_protocol::api::{PhantomListener, PhantomSession, TcpSessionTransport};
use phantom_protocol::crypto::hybrid_sign::HybridVerifyingKey;
use tokio::net::TcpStream;

// (inside an async context — every call below is `.await?`)

// ── Server ──────────────────────────────────────────────────────────────
let listener    = PhantomListener::bind("127.0.0.1:0".to_string()).await?;
let server_addr = listener.local_addr();
let pinned_key  = listener.verifying_key_bytes();   // share out-of-band

tokio::spawn(async move {
    let outcome = listener.accept().await?;
    let session = outcome.session();
    let _req = session.recv().await?;
    session.send(b"hello, post-quantum world".to_vec()).await?;
    Ok::<_, phantom_protocol::errors::CoreError>(())
});

// ── Client ──────────────────────────────────────────────────────────────
let stream    = TcpStream::connect(&server_addr).await?;
let transport = TcpSessionTransport::new(stream);
let key       = HybridVerifyingKey::from_bytes(&pinned_key)?;
let session   = PhantomSession::connect_with_transport(&server_addr, transport, key);
session.send(b"ping".to_vec()).await?;
let _reply = session.recv().await?;

Feature flags

Bare-metal: --no-default-features --features embedded,no-std. WASI: --no-default-features --features std,wasi-leg.

Links

• Repository & full docs: https://github.com/snaart/phantom_protocol
• API docs: https://docs.rs/phantom-protocol
• Changelog: CHANGELOG.md
• Protocol spec: docs/protocol/PROTOCOL.md

License

Licensed under the Apache License, Version 2.0.