CryptGuard v3.0.0

crypt_guard is a pure-Rust post-quantum sealing library. Version 3 makes a revision-pinned PQ HPKE construction the default transport:

ML-KEM (FIPS 203) -> HPKE KEM/KDF schedule -> AEAD

The default suite is ML-KEM-1024/P-384 + SHAKE256 + ChaCha20-Poly1305. CGv2 is no longer part of the default public API; read or write CGv2 data only with the explicit cgv2-compat feature during a deliberate migration.

Default API: pq_hpke

pq_hpke keeps the HPKE KEM output (enc) and ciphertext distinct for raw transport users, and provides HpkeEnvelope (CGH3, version 1) for crypt_guard deployments that need a self-describing record. Setup info and per-message AAD are caller inputs; neither is hidden in encrypted plaintext.

use crypt_guard::pq_hpke::{
    generate_recipient_key_pair, HpkeEnvelope, DEFAULT_SUITE,
};

let keys = generate_recipient_key_pair(DEFAULT_SUITE.kem())?;
let envelope = HpkeEnvelope::seal(
    DEFAULT_SUITE,
    keys.public_key(),
    b"service=payments",
    b"record=42",
    b"post-quantum payload",
)?;

let encoded = envelope.to_bytes();
let parsed = HpkeEnvelope::from_bytes(&encoded)?;
let plaintext = parsed.open(keys.private_key(), b"service=payments", b"record=42")?;
assert_eq!(plaintext, b"post-quantum payload");
# Ok::<(), Box<dyn std::error::Error>>(())

For standardized AEAD suites, raw Base and PSK APIs are available through setup_base_sender, setup_base_receiver, setup_psk_sender, and setup_psk_receiver. They return / consume separate Encapsulation (enc) and stateful sender or recipient contexts.

Suites and interoperability

The revision-pinned PQ HPKE adapter exposes ML-KEM-512/768/1024 and the ML-KEM-768/P-256, ML-KEM-768/X25519, and ML-KEM-1024/P-384 hybrid KEMs. Suite selection is explicit through Suite::new(Kem, Kdf, Aead).

The two private extensions use explicit 0xff01 / 0xff02 identifiers. They must not be represented as RFC 9180 or IANA-interoperable HPKE suites.

The PQ KEM registry and vector corpus are pinned to draft-ietf-hpke-pq-05. This is an Internet-Draft, not an RFC or final IANA assignment; applications that persist raw artifacts should persist the literal draft revision and all suite identifiers alongside them.

Feature flags

[dependencies]
crypt_guard = "3.0.0"

To migrate CGv2 records, opt in explicitly:

[dependencies]
crypt_guard = { version = "3.0.0", features = ["cgv2-compat"] }

Migration from v2

1. Deploy a reader with cgv2-compat enabled.
2. Decrypt each CGv2 record using the legacy API.
3. Re-encrypt it with pq_hpke::HpkeEnvelope and persist the new CGH3 record plus its application info / AAD contract.
4. Remove cgv2-compat once all records are migrated.

Default v3 builds neither emit nor expose CGv2 ergonomic APIs. Do not trial-decrypt CGv2 and PQ HPKE records; dispatch by the stored transport type.

Security properties

• Private key seed handling, ML-KEM validation, implicit rejection, and shared secret zeroization remain in the PQCA/libcrux-backed KEM adapter.
• Sender and recipient contexts are non-Clone, derive AEAD nonces from the HPKE sequence number, and reject sequence wrap.
• Authentication failures for wrong AAD, info, ciphertext, or same-size tampered encapsulations are intentionally opaque.
• HpkeEnvelope authenticates no caller metadata by itself: callers must pass matching info and AAD when opening.

References

• FIPS 203 — ML-KEM
• FIPS 204 — ML-DSA
• RFC 9180 — HPKE
• draft-ietf-hpke-pq-05