nym/docs/LP_PROTOCOL.md

Lewes Protocol (LP) - Technical Specification

Overview

The Lewes Protocol (LP) is a direct TCP-based registration protocol for Nym gateways. It provides an alternative to mixnet-based registration with different trade-offs: lower latency at the cost of revealing client IP to the gateway.

Design Goals:

• Low latency: Direct TCP connection vs multi-hop mixnet routing
• High reliability: KCP protocol provides ordered, reliable delivery with ARQ
• Strong security: Noise XKpsk3 provides mutual authentication and forward secrecy
• Replay protection: Bitmap-based counter validation prevents replay attacks
• Observability: Prometheus metrics for production monitoring

Non-Goals:

• Network-level anonymity (use mixnet registration for that)
• Persistent connections (LP is registration-only, single-use)
• Backward compatibility with legacy protocols

Architecture

Protocol Stack

┌─────────────────────────────────────────┐
│  Application Layer                      │
│  - Registration Requests                │
│  - E-cash Credential Verification       │
│  - WireGuard Peer Management            │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  LP Layer (Lewes Protocol)              │
│  - Noise XKpsk3 Handshake               │
│  - Replay Protection (1024-pkt window)  │
│  - Counter-based Sequencing             │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  KCP Layer (Reliability)                │
│  - Ordered Delivery                     │
│  - ARQ with Selective ACK               │
│  - Congestion Control                   │
│  - RTT Estimation                       │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  TCP Layer                              │
│  - Connection Establishment             │
│  - Byte Stream Delivery                 │
└─────────────────────────────────────────┘

Why This Layering?

TCP: Provides connection-oriented byte stream and handles network-level retransmission.

KCP: Adds application-level reliability optimized for low latency:

• Fast retransmit: Triggered after 2 duplicate ACKs (vs TCP's 3)
• Selective ACK: Acknowledges specific packets, not just cumulative
• Configurable RTO: Minimum RTO of 100ms (configurable)
• No Nagle: Immediate sending for low-latency applications

LP: Provides cryptographic security and session management:

• Noise XKpsk3: Mutual authentication with pre-shared key
• Replay protection: Prevents duplicate packet acceptance
• Session isolation: Each session has unique cryptographic state

Application: Business logic for registration and credential verification.

Protocol Flow

1. Connection Establishment

Client                                    Gateway
  |                                          |
  |--- TCP SYN --------------------------->  |
  |<-- TCP SYN-ACK ------------------------  |
  |--- TCP ACK ----------------------------> |
  |                                          |

• Control Port: 41264 (default, configurable)
• Data Port: 51264 (reserved for future use, not currently used)

2. Session Initialization

Client generates session parameters:

// Client-side session setup
let client_lp_keypair = Keypair::generate(); // X25519 keypair
let gateway_lp_public = gateway.lp_public_key; // From gateway descriptor
let salt = [timestamp (8 bytes) || nonce (24 bytes)]; // 32-byte salt

// Derive PSK using ECDH + Blake3 KDF
let shared_secret = ECDH(client_private, gateway_public);
let psk = Blake3_derive_key(
    context = "nym-lp-psk-v1",
    input = shared_secret,
    salt = salt
);

// Calculate session IDs (deterministic from keys)
let lp_id = hash(client_lp_public || 0xCC || gateway_lp_public) & 0xFFFFFFFF;
let kcp_conv_id = hash(client_lp_public || 0xFF || gateway_lp_public) & 0xFFFFFFFF;

Session ID Properties:

• Deterministic: Same key pair always produces same ID
• Order-independent: ID(A, B) == ID(B, A) due to sorted hashing
• Collision-resistant: Uses full hash, truncated to u32
• Unique per protocol: Different delimiters (0xCC for LP, 0xFF for KCP)

3. Noise Handshake (XKpsk3 Pattern)

Client (Initiator)                        Gateway (Responder)
  |                                          |
  |--- e ----------------------------------> | [1] Client ephemeral
  |                                          |
  |<-- e, ee, s, es ---------------------  | [2] Gateway ephemeral + static
  |                                          |
  |--- s, se, psk ------------------------->  | [3] Client static + PSK mix
  |                                          |
  [Transport mode established]

Message Contents:

[1] Initiator → Responder: e

• Payload: Client ephemeral public key (32 bytes)
• Encrypted: No (initial message)

[2] Responder → Initiator: e, ee, s, es

• e: Responder ephemeral public key
• ee: Mix ephemeral-ephemeral DH
• s: Responder static public key (encrypted)
• es: Mix ephemeral-static DH
• Encrypted: Yes (with keys from ee)

[3] Initiator → Responder: s, se, psk

• s: Initiator static public key (encrypted)
• se: Mix static-ephemeral DH
• psk: Mix pre-shared key (at position 3)
• Encrypted: Yes (with keys from ee, es)

Security Properties:

• ✅ Mutual authentication: Both sides prove identity via static keys
• ✅ Forward secrecy: Ephemeral keys provide PFS
• ✅ PSK authentication: Binds session to out-of-band PSK
• ✅ Identity hiding: Static keys encrypted after first message

Handshake Characteristics:

• Messages: 3 (1.5 round trips)
• Minimum network RTTs: 1.5
• Cryptographic operations: ECDH, ChaCha20-Poly1305, SHA-256

4. PSK Derivation Details

Formula:

shared_secret = X25519(client_private_lp, gateway_public_lp)
psk = Blake3_derive_key(
    context = "nym-lp-psk-v1",
    key_material = shared_secret (32 bytes),
    salt = timestamp || nonce (32 bytes)
)

Implementation (from common/nym-lp/src/psk.rs:48):

pub fn derive_psk(
    local_private: &PrivateKey,
    remote_public: &PublicKey,
    salt: &[u8; 32],
) -> [u8; 32] {
    let shared_secret = local_private.diffie_hellman(remote_public);
    nym_crypto::kdf::derive_key_blake3(PSK_CONTEXT, shared_secret.as_bytes(), salt)
}

Why This Design:

1. Identity-bound: PSK tied to LP keypairs, not ephemeral

   • Prevents MITM without LP private key
   • Links session to long-term identities

2. Session-specific via salt: Different registrations use different PSKs

   • timestamp: 8-byte Unix timestamp (milliseconds)
   • nonce: 24-byte random value
   • Prevents PSK reuse across sessions

3. Symmetric derivation: Both sides derive same PSK

   • Client: ECDH(client_priv, gateway_pub)
   • Gateway: ECDH(gateway_priv, client_pub)
   • Mathematical property: ECDH(a, B) == ECDH(b, A)

4. Blake3 KDF with domain separation:

   • Context string prevents cross-protocol attacks
   • Generates uniform 32-byte output suitable for Noise

Salt Transmission:

• Included in ClientHello message (cleartext)
• Gateway extracts salt before deriving PSK
• Timestamp validation rejects stale salts

5. Replay Protection

Mechanism: Sliding Window with Bitmap (from common/nym-lp/src/replay/validator.rs:32):

const WORD_SIZE: usize = 64;
const N_WORDS: usize = 16;  // 1024 bits total
const N_BITS: usize = WORD_SIZE * N_WORDS;  // 1024

pub struct ReceivingKeyCounterValidator {
    next: u64,              // Next expected counter
    receive_cnt: u64,       // Total packets received
    bitmap: [u64; 16],      // 1024-bit bitmap
}

Algorithm:

For each incoming packet with counter C:
  1. Quick check (branchless):
     - If C >= next: Accept (growing)
     - If C + 1024 < next: Reject (too old, outside window)
     - If bitmap[C % 1024] is set: Reject (duplicate)
     - Else: Accept (out-of-order within window)

  2. After successful processing, mark:
     - Set bitmap[C % 1024] = 1
     - If C >= next: Update next = C + 1
     - Increment receive_cnt

Performance Optimizations:

1. SIMD-accelerated bitmap operations (from common/nym-lp/src/replay/simd/):

   • AVX2 support (x86_64)
   • SSE2 support (x86_64)
   • NEON support (ARM)
   • Scalar fallback (portable)

2. Branchless execution (constant-time):

   // No early returns - prevents timing attacks
   let result = if is_growing {
       Some(Ok(()))
   } else if too_far_back {
       Some(Err(ReplayError::OutOfWindow))
   } else if duplicate {
       Some(Err(ReplayError::DuplicateCounter))
   } else {
       Some(Ok(()))
   };
   result.unwrap()
   

3. Overflow-safe arithmetic:

   let too_far_back = if counter > u64::MAX - 1024 {
       false  // Can't overflow, so not too far back
   } else {
       counter + 1024 < self.next
   };
   

Memory Usage (verified from common/nym-lp/src/replay/validator.rs:738):

// test_memory_usage()
size = size_of::<u64>() * 2 +        // next + receive_cnt = 16 bytes
       size_of::<u64>() * N_WORDS;   // bitmap = 128 bytes
// Total: 144 bytes

6. Registration Request

After handshake completes, client sends encrypted registration request:

pub struct RegistrationRequest {
    pub mode: RegistrationMode,
    pub credential: EcashCredential,
    pub gateway_identity: String,
}

pub enum RegistrationMode {
    Dvpn {
        wg_public_key: [u8; 32],
    },
    Mixnet {
        client_id: String,
        mix_address: Option<String>,
    },
}

Encryption:

• Encrypted using Noise transport mode
• Includes 16-byte Poly1305 authentication tag
• Replay protection via LP counter

7. Credential Verification

Gateway verifies the e-cash credential:

// Gateway-side verification
pub async fn verify_credential(
    &self,
    credential: &EcashCredential,
) -> Result<VerifiedCredential, CredentialError> {
    // 1. Check credential signature (BLS12-381)
    verify_blinded_signature(&credential.signature)?;

    // 2. Check credential not already spent (nullifier check)
    if self.storage.is_nullifier_spent(&credential.nullifier).await? {
        return Err(CredentialError::AlreadySpent);
    }

    // 3. Extract bandwidth allocation
    let bandwidth_bytes = credential.bandwidth_value;

    // 4. Mark nullifier as spent
    self.storage.mark_nullifier_spent(&credential.nullifier).await?;

    Ok(VerifiedCredential {
        bandwidth_bytes,
        expiry: credential.expiry,
    })
}

For dVPN Mode:

let peer_config = WireguardPeerConfig {
    public_key: request.wg_public_key,
    allowed_ips: vec!["10.0.0.0/8"],
    bandwidth_limit: verified.bandwidth_bytes,
};
self.wg_controller.add_peer(peer_config).await?;

8. Registration Response

pub enum RegistrationResponse {
    Success {
        bandwidth_allocated: u64,
        expiry: u64,
        gateway_data: GatewayData,
    },
    Error {
        code: ErrorCode,
        message: String,
    },
}

pub enum ErrorCode {
    InvalidCredential = 1,
    CredentialExpired = 2,
    CredentialAlreadyUsed = 3,
    InsufficientBandwidth = 4,
    WireguardPeerRegistrationFailed = 5,
    InternalError = 99,
}

State Machine and Security Protocol

Protocol Components

The Lewes Protocol combines three cryptographic protocols for secure, post-quantum resistant communication:

1. KKT (KEM Key Transfer) - Dynamically fetches responder's KEM public key with Ed25519 authentication
2. PSQ (Post-Quantum Secure PSK) - Derives PSK using KEM-based protocol for HNDL resistance
3. Noise XKpsk3 - Provides encrypted transport with mutual authentication and forward secrecy

State Machine

The LP state machine orchestrates the complete protocol flow from connection to encrypted transport:

┌─────────────────────────────────────────────────────────────────────┐
│                    LEWES PROTOCOL STATE MACHINE                     │
└─────────────────────────────────────────────────────────────────────┘

                    ┌──────────────────┐
                    │ ReadyToHandshake │
                    │                  │
                    │ • Keys loaded    │
                    │ • Session ID set │
                    └────────┬─────────┘
                             │
                    StartHandshake input
                             │
                             ▼
         ┌───────────────────────────────────────┐
         │          KKTExchange                  │
         │                                       │
         │  Initiator:                          │
         │  1. Send KKT request (signed)        │
         │  2. Receive KKT response             │
         │  3. Validate Ed25519 signature       │
         │  4. Extract KEM public key           │
         │                                       │
         │  Responder:                          │
         │  1. Wait for KKT request             │
         │  2. Validate signature               │
         │  3. Send signed KEM key              │
         └───────────────┬───────────────────────┘
                         │
                  KKT Complete
                         │
                         ▼
         ┌───────────────────────────────────────┐
         │           Handshaking                 │
         │                                       │
         │  PSQ Protocol:                       │
         │  1. Initiator encapsulates PSK       │
         │     (embedded in Noise msg 1)        │
         │  2. Responder decapsulates PSK       │
         │     (sends ctxt_B in Noise msg 2)    │
         │  3. Both derive final PSK:           │
         │     KDF(ECDH || KEM_shared)          │
         │                                       │
         │  Noise XKpsk3 Handshake:             │
         │  → msg 1: e, es, ss + PSQ payload    │
         │  ← msg 2: e, ee, se + ctxt_B         │
         │  → msg 3: s, se (handshake complete) │
         └───────────────┬───────────────────────┘
                         │
                  Handshake Complete
                         │
                         ▼
         ┌───────────────────────────────────────┐
         │            Transport                  │
         │                                       │
         │  • Encrypted data transfer            │
         │  • AEAD with ChaCha20-Poly1305       │
         │  • Replay protection (counters)       │
         │  • Bidirectional communication        │
         └───────────────┬───────────────────────┘
                         │
                    Close input
                         │
                         ▼
                   ┌──────────┐
                   │  Closed  │
                   │          │
                   │ • Reason │
                   └──────────┘

Message Sequence

Complete protocol flow from connection to encrypted transport:

Initiator                                                    Responder
    │                                                            │
    │ ════════════════ KKT EXCHANGE ════════════════            │
    │                                                            │
    │  KKTRequest (signed with Ed25519)                         │
    ├──────────────────────────────────────────────────────────>│
    │                                                            │ Validate
    │                                                            │ signature
    │                        KKTResponse (signed KEM key + hash) │
    │<──────────────────────────────────────────────────────────┤
    │                                                            │
    │ Validate signature                                         │
    │ Extract kem_pk                                             │
    │                                                            │
    │ ══════════════ PSQ + NOISE HANDSHAKE ══════════════       │
    │                                                            │
    │  Noise msg 1: e, es, ss                                   │
    │  + PSQ InitiatorMsg (KEM encapsulation)                   │
    ├──────────────────────────────────────────────────────────>│
    │                                                            │
    │                                                            │ PSQ: Decapsulate
    │                                                            │ Derive PSK
    │                                                            │ Inject into Noise
    │                                  Noise msg 2: e, ee, se    │
    │                                  + ctxt_B (encrypted PSK)  │
    │<──────────────────────────────────────────────────────────┤
    │                                                            │
    │ Extract ctxt_B                                             │
    │ Store for re-registration                                 │
    │ Inject PSK into Noise                                      │
    │                                                            │
    │  Noise msg 3: s, se                                       │
    ├──────────────────────────────────────────────────────────>│
    │                                                            │
    │ Handshake Complete ✓                                       │ Handshake Complete ✓
    │ Transport mode active                                      │ Transport mode active
    │                                                            │
    │ ═══════════════ TRANSPORT MODE ═══════════════            │
    │                                                            │
    │  EncryptedData (AEAD, counter N)                          │
    ├──────────────────────────────────────────────────────────>│
    │                                                            │
    │                                  EncryptedData (counter M) │
    │<──────────────────────────────────────────────────────────┤
    │                                                            │
    │  (bidirectional encrypted communication)                  │
    │◄──────────────────────────────────────────────────────────►
    │                                                            │

KKT (KEM Key Transfer) Protocol

Purpose: Securely obtain responder's KEM public key before PSQ can begin.

Key Features:

• Ed25519 signatures for authentication (both request and response signed)
• Optional hash validation for key pinning (future directory service integration)
• Currently signature-only mode (deployable without infrastructure)
• Easy upgrade path to hash-based key pinning

Initiator Flow:

1. Generate KKT request with Ed25519 signature
2. Send KKTRequest to responder
3. Receive KKTResponse with signed KEM key
4. Validate Ed25519 signature
5. (Optional) Validate key hash against directory
6. Store KEM key for PSQ encapsulation

Responder Flow:

1. Receive KKTRequest from initiator
2. Validate initiator's Ed25519 signature
3. Generate KKTResponse with:
   - Responder's KEM public key
   - Ed25519 signature over (key || timestamp)
   - Blake3 hash of KEM key
4. Send KKTResponse to initiator

PSQ (Post-Quantum Secure PSK) Protocol

Purpose: Derive a post-quantum secure PSK for Noise protocol.

Security Properties:

• HNDL resistance: PSK derived from KEM-based protocol
• Forward secrecy: Ephemeral KEM keypair per session
• Authentication: Ed25519 signatures prevent MitM
• Algorithm agility: Easy upgrade from X25519 to ML-KEM

PSK Derivation:

Classical ECDH:
  ecdh_secret = X25519_DH(local_private, remote_public)

KEM Encapsulation (Initiator):
  (kem_shared_secret, ciphertext) = KEM.Encap(responder_kem_pk)

KEM Decapsulation (Responder):
  kem_shared_secret = KEM.Decap(kem_private, ciphertext)

Final PSK:
  combined = ecdh_secret || kem_shared_secret || salt
  psk = Blake3_KDF("nym-lp-psk-psq-v1", combined)

Integration with Noise:

• PSQ payload embedded in first Noise message (no extra round-trip)
• Responder sends encrypted PSK handle (ctxt_B) in second Noise message
• Both sides inject derived PSK before completing Noise handshake
• Noise validates PSK correctness during handshake

PSK Handle (ctxt_B): The responder's encrypted PSK handle allows future re-registration without repeating PSQ:

• Encrypted with responder's long-term key
• Can be presented in future sessions
• Enables fast re-registration for returning clients

Security Guarantees

Achieved Properties:

• ✅ Mutual authentication: Ed25519 signatures in KKT and PSQ
• ✅ Forward secrecy: Ephemeral keys in Noise handshake
• ✅ Post-quantum PSK: KEM-based PSK derivation
• ✅ HNDL resistance: PSK safe even if private keys compromised later
• ✅ Replay protection: Monotonic counters with sliding window
• ✅ Key confirmation: Noise handshake validates PSK correctness

Implementation Status:

• 🔄 Key pinning: Hash validation via directory service (signature-only for now)
• 🔄 ML-KEM support: Easy config upgrade from X25519 to ML-KEM-768
• 🔄 PSK re-use: ctxt_B handle stored for future re-registration

Algorithm Choices

Current (Testing/Development):

• KEM: X25519 (DHKEM) - Classical ECDH, widely tested
• Hash: Blake3 - Fast, secure, parallel
• Signature: Ed25519 - Fast verification, compact
• AEAD: ChaCha20-Poly1305 - Fast, constant-time

Future (Production):

• KEM: ML-KEM-768 - NIST-approved post-quantum KEM
• Hash: Blake3 - No change needed
• Signature: Ed25519 - No change needed (or upgrade to ML-DSA)
• AEAD: ChaCha20-Poly1305 - No change needed

Migration Path:

# Current deployment
[lp.crypto]
kem_algorithm = "x25519"

# Future upgrade (config change only)
[lp.crypto]
kem_algorithm = "ml-kem-768"

Message Types

KKT Messages:

// Message Type 0x0004
struct KKTRequest {
    timestamp: u64,              // Unix timestamp (replay protection)
    initiator_ed25519_pk: [u8; 32], // Initiator's public key
    signature: [u8; 64],         // Ed25519 signature
}

// Message Type 0x0005
struct KKTResponse {
    kem_pk: Vec<u8>,             // Responder's KEM public key
    key_hash: [u8; 32],          // Blake3 hash of KEM key
    timestamp: u64,              // Unix timestamp
    signature: [u8; 64],         // Ed25519 signature
}

PSQ Embedding:

• PSQ InitiatorMsg embedded in Noise message 1 payload (after 'e, es, ss')
• PSQ ResponderMsg (ctxt_B) embedded in Noise message 2 payload (after 'e, ee, se')
• No additional round-trips beyond standard 3-message Noise handshake

KCP Protocol Details

KCP Configuration

From common/nym-kcp/src/session.rs:

pub struct KcpSession {
    conv: u32,           // Conversation ID
    mtu: usize,          // Default: 1400 bytes
    snd_wnd: u16,        // Send window: 128 segments
    rcv_wnd: u16,        // Receive window: 128 segments
    rx_minrto: u32,      // Minimum RTO: 100ms (configurable)
}

KCP Packet Format

┌────────────────────────────────────────────────┐
│ Conv ID (4 bytes) - Conversation identifier    │
├────────────────────────────────────────────────┤
│ Cmd (1 byte) - PSH/ACK/WND/ERR                │
├────────────────────────────────────────────────┤
│ Frg (1 byte) - Fragment number (reverse order) │
├────────────────────────────────────────────────┤
│ Wnd (2 bytes) - Receive window size           │
├────────────────────────────────────────────────┤
│ Timestamp (4 bytes) - Send timestamp           │
├────────────────────────────────────────────────┤
│ Sequence Number (4 bytes) - Packet sequence    │
├────────────────────────────────────────────────┤
│ UNA (4 bytes) - Unacknowledged sequence       │
├────────────────────────────────────────────────┤
│ Length (4 bytes) - Data length                 │
├────────────────────────────────────────────────┤
│ Data (variable) - Payload                      │
└────────────────────────────────────────────────┘

Total header: 24 bytes

KCP Features

Reliability Mechanisms:

• Sequence Numbers (sn): Track packet ordering
• Fragment Numbers (frg): Handle message fragmentation
• UNA (Unacknowledged): Cumulative ACK up to this sequence
• Selective ACK: Via individual ACK packets
• Fast Retransmit: Triggered by duplicate ACKs (configurable threshold)
• RTO Calculation: Smoothed RTT with variance

LP Packet Format

LP Header

┌────────────────────────────────────────────────┐
│ Protocol Version (1 byte) - Currently: 1       │
├────────────────────────────────────────────────┤
│ Session ID (4 bytes) - LP session identifier   │
├────────────────────────────────────────────────┤
│ Counter (8 bytes) - Replay protection counter  │
└────────────────────────────────────────────────┘

Total header: 13 bytes

LP Message Types

pub enum LpMessage {
    Handshake(Vec<u8>),
    EncryptedData(Vec<u8>),
    ClientHello {
        client_lp_public: [u8; 32],
        salt: [u8; 32],
        timestamp: u64,
    },
    Busy,
}

Complete Packet Structure

┌─────────────────────────────────────┐
│  LP Header (13 bytes)               │
│  - Version, Session ID, Counter     │
├─────────────────────────────────────┤
│  LP Message (variable)              │
│  - Type tag (1 byte)                │
│  - Message data                     │
├─────────────────────────────────────┤
│  Trailer (16 bytes)                 │
│  - Reserved for future MAC/tag      │
└─────────────────────────────────────┘

Security Properties

Threat Model

Protected Against:

• ✅ Passive eavesdropping: Noise encryption (ChaCha20-Poly1305)
• ✅ Active MITM: Mutual authentication via static keys + PSK
• ✅ Replay attacks: Counter-based validation with 1024-packet window
• ✅ Packet injection: Poly1305 authentication tags
• ✅ Timestamp replay: 30-second window for ClientHello timestamps (configurable)
• ✅ DoS (connection flood): Connection limit (default: 10,000, configurable)
• ✅ Credential reuse: Nullifier tracking in database

Not Protected Against:

• ❌ Network-level traffic analysis: LP is not anonymous (use mixnet for that)
• ❌ Gateway compromise: Gateway sees client registration data
• ⚠️ Per-IP DoS: No per-IP rate limiting (global limit only)

Cryptographic Primitives

Component	Algorithm	Key Size	Source
Key Exchange	X25519	256 bits	RustCrypto
Encryption	ChaCha20	256 bits	RustCrypto
Authentication	Poly1305	256 bits	RustCrypto
KDF	Blake3	256 bits	nym_crypto
Hash (Noise)	SHA-256	256 bits	snow crate
Signature (E-cash)	BLS12-381	381 bits	E-cash contract

Forward Secrecy

Noise XKpsk3 provides forward secrecy through ephemeral keys:

1. Initial handshake: Uses ephemeral + static keys

2. Key compromise scenario:

   • Compromise of static key: Past sessions remain secure (ephemeral keys destroyed)
   • Compromise of PSK: Attacker needs static key too (two-factor security)
   • Compromise of both: Only future sessions affected, not past

3. Session key lifetime: Destroyed after single registration completes

Timing Attack Resistance

Constant-time operations:

• ✅ Replay protection check (branchless)
• ✅ Bitmap bit operations (branchless)
• ✅ Noise crypto operations (via snow/RustCrypto)

Variable-time operations:

• ⚠️ Credential verification (database lookup time varies)
• ⚠️ WireGuard peer registration (filesystem operations)

Configuration

Gateway Configuration

From gateway/src/node/lp_listener/mod.rs:78:

[lp]
# Enable/disable LP listener
enabled = true

# Bind address
bind_address = "0.0.0.0"

# Control port (for LP handshake and registration)
control_port = 41264

# Data port (reserved for future use)
data_port = 51264

# Maximum concurrent connections
max_connections = 10000

# Timestamp validation window (seconds)
# ClientHello messages older than this are rejected
timestamp_tolerance_secs = 30

# Use mock e-cash verifier (TESTING ONLY!)
use_mock_ecash = false

Firewall Rules

Required inbound rules:

# Allow TCP connections to LP control port
iptables -A INPUT -p tcp --dport 41264 -j ACCEPT

# Optional: Rate limiting
iptables -A INPUT -p tcp --dport 41264 -m state --state NEW \
    -m recent --set --name LP_LIMIT
iptables -A INPUT -p tcp --dport 41264 -m state --state NEW \
    -m recent --update --seconds 60 --hitcount 100 --name LP_LIMIT \
    -j DROP

Metrics

From gateway/src/node/lp_listener/mod.rs:4:

Connection Metrics:

• active_lp_connections: Gauge tracking current active LP connections
• lp_connections_total: Counter for total LP connections handled
• lp_connection_duration_seconds: Histogram of connection durations
• lp_connections_completed_gracefully: Counter for successful completions
• lp_connections_completed_with_error: Counter for error terminations

Handshake Metrics:

• lp_handshakes_success: Counter for successful handshakes
• lp_handshakes_failed: Counter for failed handshakes
• lp_handshake_duration_seconds: Histogram of handshake durations
• lp_client_hello_failed: Counter for ClientHello failures

Registration Metrics:

• lp_registration_attempts_total: Counter for all registration attempts
• lp_registration_success_total: Counter for successful registrations
• lp_registration_failed_total: Counter for failed registrations
• lp_registration_duration_seconds: Histogram of registration durations

Mode-Specific:

• lp_registration_dvpn_attempts/success/failed: dVPN mode counters
• lp_registration_mixnet_attempts/success/failed: Mixnet mode counters

Credential Metrics:

• lp_credential_verification_attempts/success/failed: Verification counters
• lp_bandwidth_allocated_bytes_total: Total bandwidth allocated

Error Metrics:

• lp_errors_handshake: Handshake errors
• lp_errors_timestamp_too_old/too_far_future: Timestamp validation errors
• lp_errors_wg_peer_registration: WireGuard peer registration failures

Error Codes

Handshake Errors

Error	Description
NOISE_DECRYPT_ERROR	Invalid ciphertext or wrong keys
NOISE_PROTOCOL_ERROR	Unexpected message or state
REPLAY_DUPLICATE	Counter already seen
REPLAY_OUT_OF_WINDOW	Counter outside 1024-packet window
TIMESTAMP_TOO_OLD	ClientHello > configured tolerance
TIMESTAMP_FUTURE	ClientHello from future

Registration Errors

Code	Name	Description
CREDENTIAL_INVALID	Invalid credential	Signature verification failed
CREDENTIAL_EXPIRED	Credential expired	Past expiry timestamp
CREDENTIAL_SPENT	Already used	Nullifier already in database
INSUFFICIENT_BANDWIDTH	Not enough bandwidth	Requested > credential value
WIREGUARD_FAILED	Peer registration failed	Kernel error adding WireGuard peer

Limitations

Current Limitations

1. No persistent sessions: Each registration is independent
2. Single registration per session: Connection closes after registration
3. No streaming: Protocol is request-response only
4. No gateway discovery: Client must know gateway's LP public key beforehand
5. No version negotiation: Protocol version fixed at 1
6. No per-IP rate limiting: Only global connection limit

Testing Gaps

1. No end-to-end integration tests: Unit tests exist, integration tests pending
2. No performance benchmarks: Latency/throughput not measured
3. No load testing: Concurrent connection limits not stress-tested
4. No security audit: Cryptographic implementation not externally reviewed

References

Specifications

• Noise Protocol Framework: https://noiseprotocol.org/noise.html
• XKpsk3 Pattern: https://noiseexplorer.com/patterns/XKpsk3/
• KCP Protocol: https://github.com/skywind3000/kcp
• Blake3: https://github.com/BLAKE3-team/BLAKE3-specs

Implementations

• snow: Rust Noise protocol implementation
• RustCrypto: Cryptographic primitives (ChaCha20-Poly1305, X25519)
• tokio: Async runtime for network I/O

Security Audits

• Noise implementation audit (pending)
• Replay protection audit (pending)
• E-cash integration audit (pending)
• Penetration testing (pending)

Changelog

Version 1.1 (Post-Quantum PSK with KKT)

Implemented:

• KKTExchange state in state machine for pre-handshake KEM key transfer
• PSQ (Post-Quantum Secure PSK) protocol integration
• KKT (KEM Key Transfer) protocol with Ed25519 authentication
• Optional hash validation for KEM key pinning (signature-only mode active)
• PSK handle (ctxt_B) storage for future re-registration
• X25519 DHKEM support (ready for ML-KEM upgrade)
• Comprehensive state machine tests (7 test cases)
• generate_fresh_salt() utility for session creation

Security Improvements:

• Post-quantum PSK derivation (KEM-based)
• HNDL (Harvest Now, Decrypt Later) resistance
• Mutual authentication via Ed25519 signatures
• Easy migration path to ML-KEM-768

Architecture:

• State flow: ReadyToHandshake → KKTExchange → Handshaking → Transport
• PSQ embedded in Noise handshake (no extra round-trip)
• Automatic KKT on StartHandshake (no manual key distribution)

Related Issues:

• nym-4za: Add KKTExchange state to LpStateMachine

Version 1.0 (Initial Implementation)

Implemented:

• Noise XKpsk3 handshake
• KCP reliability layer
• Replay protection (1024-packet window with SIMD)
• PSK derivation (ECDH + Blake3)
• dVPN and Mixnet registration modes
• E-cash credential verification
• WireGuard peer management
• Prometheus metrics
• DoS protection (connection limits, timestamp validation)

Pending:

• End-to-end integration tests
• Performance benchmarks
• Security audit
• Client implementation
• Gateway probe support
• Per-IP rate limiting