crypto.pq

A sub-namespace of crypto (not a separate package), mirroring the form of the current crypto. The standardized NIST schemes: ML-KEM (Kyber, key encapsulation) and ML-DSA (Dilithium, signature). Tier 1 (an addition to crypto), it enters without touching the core.

ML-KEM: key encapsulation (KEM)

fn pq.ml_kem_keypair() -> (public: [1184]byte, secret: [2400]byte)        // ML-KEM-768 (level 3)
fn pq.ml_kem_encapsulate(their_public: [1184]byte) -> (ciphertext: [1088]byte, shared: [32]byte)
fn pq.ml_kem_decapsulate(my_secret: [2400]byte, ciphertext: [1088]byte) -> Result[[32]byte, error{Invalid}]

(Sizes for level 3, ML-KEM-768; levels 512/1024 follow the same form with arrays of another size.)

ML-DSA: signature

fn pq.ml_dsa_keypair() -> (public: [1952]byte, secret: [4032]byte)        // ML-DSA-65
fn pq.ml_dsa_sign(secret: [4032]byte, message: []byte) -> [3309]byte
fn pq.ml_dsa_verify(public: [1952]byte, message: []byte, signature: [3309]byte) -> bool

Hybrid: the recommended mode

The transition is hybrid (classic + PQ): if one breaks, the other holds. It combines X25519 (from crypto) with ML-KEM into a single secret:

fn pq.hybrid_x25519_mlkem_keypair() -> (public: HybridPublic, secret: HybridSecret)
fn pq.hybrid_encapsulate(their_public: HybridPublic) -> (ciphertext: HybridCiphertext, shared: [32]byte)
fn pq.hybrid_decapsulate(my_secret: HybridSecret, ct: HybridCiphertext) -> Result[[32]byte, error{Invalid}]

decl HybridPublic { ... }   decl HybridSecret { ... }   decl HybridCiphertext { ... }

Curation

• Sub-namespace, not a package: it is crypto with extra schemes; same form (keypair/encapsulate/ sign/verify), same fixed-size buffers ([N]byte), same posture (verification failure is Result/bool, not panic).
• Hybrid is the recommended default in the prose: pure PQ exists, but the mature transition combines it with the classic.
• Only the NIST-standardized ones (ML-KEM/ML-DSA); pre-standard candidates (Falcon/SPHINCS+) stay out until they standardize, like the rest of crypto.