Skip to content

Latest commit

 

History

History
67 lines (40 loc) · 3.04 KB

ARCHITECTURE.md

File metadata and controls

67 lines (40 loc) · 3.04 KB

Architecture Details

1. Physical Space Verification Layer

The first line of defense ensures that only someone physically present in the same room can initiate a secure connection.

  • Rotating QR Code: Refreshes every 3 seconds with a new payload containing the session ID, server endpoint, and certificate fingerprint.
  • 4-Digit Verification Code: Displayed alongside the QR code. Must be entered manually by the user.
  • IP Highlight Confirmation: The server IP is prominently displayed on screen. The user must visually confirm it matches their device's network.

Trust anchor: The act of scanning the QR code is assumed to be private (no one else can see the screen).

2. TOFU Certificate Pinning Layer

Trust On First Use (TOFU) pins the server's public key fingerprint to the QR code payload.

  • The QR code contains a SHA-256 hash of the server's public key.
  • The client verifies this fingerprint on first connection and stores it.
  • Any subsequent connection with a different fingerprint is rejected (MITM detection).

This defends against ARP spoofing, DNS hijacking, and other LAN-level MITM attacks.

3. One-Time Handshake State Machine

The core security mechanism. A single handshake code can only be verified once.

States: Idle → Active → Consumed | Expired

  • Atomic state transitions: Uses tokio::sync::RwLock to prevent race conditions.
  • One-code-one-verify: After verification, the state immediately transitions to Consumed. Any replay attempt returns HTTP 409 Conflict.
  • Brute-force protection: After max attempts (default 3), the state transitions to Expired. Returns HTTP 410 Gone.
  • Constant-time comparison: Uses constant_time_eq to prevent timing side-channels.

4. Dual-Token Depth + Channel Binding

After successful handshake, the client receives two tokens:

  • Access Token: Short-lived (5-15 minutes, random expiry). Used for API access.
  • Refresh Token: Long-lived (1 hour). Bound to the TLS channel via a channel binding hash.

Channel binding prevents token reuse across different TLS sessions. If an attacker steals a Refresh Token, they cannot use it without the same TLS channel.

5. CSPRNG (OS-Level)

All randomness comes from the OS kernel:

  • getrandom on Linux/macOS
  • BCryptGenRandom on Windows (via rand::rngs::OsRng)

No application-layer entropy mixing. We trust the kernel's ChaCha20-based CSPRNG.

6. Memory Anti-Forensics

Sensitive data is protected in memory:

  • mlock / VirtualLock: Prevents memory pages from being swapped to disk.
  • zeroize: Sensitive data is explicitly overwritten with zeros when dropped.
  • SecureToken / SecureMemory / SecureString: Wrapper types that enforce these protections.

7. Boundary Constraints + Traffic Padding

  • NIC binding: The server only binds to specific network interfaces. Binding to 0.0.0.0 is explicitly forbidden.
  • Traffic padding (optional): Constant-rate padding packets to obscure traffic patterns.

Threat Model

See THREAT_MODEL.md for the complete threat model and security assumptions.