Encryption

Cryptographic primitives, key exchange, and session encryption

Overview

Crosslink uses a layered cryptographic design:

Identity keys (Ed25519) -- long-term, one per device
        |
Ephemeral keys (X25519) -- per-session, forward secrecy
        |
HKDF-SHA256 -- derive session keys
        |
XChaCha20-Poly1305 -- encrypt/decrypt session frames

Identity keys

Each device (host or client) has a long-term Ed25519 key pair:

• Private key: Stored in OS keychain (host) or WebCrypto non-extractable key (client)
• Public key: Shared during pairing, used for authentication
• Fingerprint: SHA-256 of the public key, first 16 hex chars displayed in QR code

Host identity:  Ed25519 key pair, persisted in OS keychain
Client identity: Ed25519 key pair, persisted under WebCrypto key

Key generation

// Host (Node.js)
// Identity is generated automatically by createCrosslinkServer()
// Stored in .crosslink-data/<appId>/ via OS keychain (if available) or encrypted file

// Client (Browser)
// Identity is generated automatically by CrosslinkClient.create()
// Stored in IndexedDB under AES-256-GCM encryption

CLX1 handshake

The CLX1 handshake authenticates both parties and establishes a shared secret:

1. Client sends `sinit`: its static X25519 key, a fresh ephemeral X25519 key,
   a nonce, and an Ed25519 signature over the canonical transcript T0
2. Host looks the device up by id and verifies that signature against the key in
   its own stored record -- never against a key offered on the wire
3. Host replies `sack`: its ephemeral key, a nonce, and a signature over T1
4. Client verifies that signature against the host key it pinned at pairing
5. Both compute ikm = X25519(eph, eph_peer) || X25519(static_x, static_x_peer)
6. Both derive two directional keys from ikm via HKDF-SHA256

Handshake security properties

Property	Mechanism
Authentication	Ed25519 signatures on ephemeral keys
Forward secrecy	Ephemeral X25519 keys (deleted after session)
Key confirmation	Both parties derive same session keys
Replay protection	Nonces + sequence numbers in frames

Session encryption

Once the handshake completes, all communication uses XChaCha20-Poly1305:

Frame format:
+--------+--------+----------------+----------------+
| Nonce  |  Tag   |   Ciphertext   |  Sequence Num  |
| 12 B   | 16 B   |  variable      |  4 B           |
+--------+--------+----------------+----------------+

Why XChaCha20-Poly1305?

Feature	XChaCha20-Poly1305	AES-GCM
Nonce size	192 bits (random safe)	96 bits (collision risk)
Hardware dependency	None (software)	AES-NI preferred
Performance	Fast on all platforms	Fast with AES-NI
Forward secrecy	Yes (ephemeral keys)	Yes (ephemeral keys)

The 192-bit nonce makes random nonce generation safe without worrying about collisions, which is critical for the concurrent frame streams in Crosslink.

Key derivation

Session keys are derived using HKDF-SHA256:

ikm  = X25519(eph, eph_peer) || X25519(static_x, static_x_peer)
salt = ncC || nh                        (both sides' handshake nonces)
info = "crosslink-session-keys-v1"

okm  = HKDF-SHA256(ikm, salt, info, 64)
kC   = okm[0..32]     client -> host traffic key
kH   = okm[32..64]    host -> client traffic key

The ephemeral term gives forward secrecy; the static-static term binds the session to the two paired identities, so a stolen ephemeral alone proves nothing. Each direction gets its own key, so a frame cannot be reflected back at its sender. See Protocol for the full transcript.

Secret storage encryption

Host (Node.js)

When the OS keychain is unavailable, the SDK falls back to AES-256-GCM file encryption:

Key derivation:
  passphrase = CROSSLINK_SECRET_KEY env var OR machine-bound key
  salt = random (16 bytes)
  key = scrypt(passphrase, salt, N=2^14, r=8, p=1, dkLen=32)

Encryption:
  iv = random (12 bytes)
  ciphertext = AES-256-GCM(key, iv, plaintext)
  stored = { v:1, salt, iv, tag, ciphertext }

Client (Browser)

When using CrosslinkClient.create(), the SDK encrypts at rest with AES-256-GCM under a WebCrypto key:

Key generation:
  key = crypto.subtle.generateKey(
    { name: "AES-GCM", length: 256 },
    extractable: false,  // <-- critical: cannot be exported
    ["encrypt", "decrypt"]
  )

Encryption:
  iv = crypto.getRandomValues(12)
  ciphertext = crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, plaintext)

The extractable: false flag prevents JavaScript from reading the key material. However, a script running on the same origin can still use the key to decrypt data. This protects against copy-and-leave attacks (XSS exfiltration), not against code execution on the origin.

Algorithm choices and alternatives

Primitive	Chosen	Alternatives considered
Identity	Ed25519	ECDSA-P256 (slower, larger keys), RSA (legacy)
Key exchange	X25519	ECDH-P256 (same curve as identity is cleaner)
AEAD	XChaCha20-Poly1305	AES-256-GCM (nonce collision risk), ChaCha20-Poly1305 (smaller nonce)
KDF	HKDF-SHA256	PBKDF2 (slower, not needed here)
Hash	SHA-256	SHA-512 (overkill for fingerprints)

Security limitations

• No post-quantum resistance: Ed25519 and X25519 are vulnerable to quantum computers
• No key escrow: Lost identity keys cannot be recovered (by design)
• No anonymity: Device fingerprints are visible during pairing
• No traffic analysis resistance: Frame sizes and timing are visible to network observers