Cryptography

Primitives, domain-separated key derivation, and the hybrid classical + post-quantum pairing profile in Yakr v1.0.

Crypto stack

Purpose	Primitive	Key size
Identity signing	Ed25519	32 B seed
Key agreement	X25519	32 B
Post-quantum KEM	ML-KEM-768	shared 32 B
PQ invite signing	ML-DSA-65	optional
KDF	HKDF-SHA256	32 B output
Message encryption	XChaCha20-Poly1305	32 B key, 24 B nonce
Mailbox tag	HMAC-SHA256	32 B tag
Safety code	SHA-256 → digits	display only

HKDF domain separation

Every derived key uses a distinct info string so keys cannot be swapped across contexts:

flowchart TB
  subgraph v01 ["yakr-v0.1"]
    M[yakr/v0.1/master]
    MK["yakr/v0.1/message-key + seq"]
    MT["yakr/v0.1/mailbox-tag + direction"]
  end
  subgraph v04 ["yakr-v0.4"]
    PM[yakr/v0.4/pair-master]
    DR["yakr/v1.0/double-ratchet-*"]
  end
  subgraph v06 ["yakr-v0.6"]
    HM[yakr/v0.6/hybrid-master]
  end

Key derivation chain

flowchart TB
  X25519[X25519 shared secret] --> MASTER["master_secret<br/>HKDF pair-master"]
  MASTER --> MSG["message_key seq<br/>HKDF message-key"]
  MASTER --> MBSEC["mailbox_secret<br/>HKDF mailbox-tag + direction"]
  MBSEC --> TAG["mailbox tag<br/>HMAC direction|epoch"]
  MSG --> AEAD[XChaCha encrypt inner JSON]
  AEAD --> BLOB[outer blob ciphertext]
  TAG --> BLOB

Hybrid PQ pairing

The v1.0 profile combines X25519 with ML-KEM-768 for pairing handshakes. Seehybrid-pq-v1.md and the live Python↔Rust interop tests in the repository.