CryptGuard v2

crypt_guard is a post-quantum sealing library centered on one safe default flow:

ML-KEM (FIPS 203) -> HKDF -> Authenticated Envelope (HPKE-shaped)

The primary API produces one self-contained CGv2 envelope. Nonce handling, key derivation, and KEM encapsulation are all internal — the caller provides a public key and plaintext and receives a sealed Envelope back.

Current release status: 2.0.0. The Phase 4 safe-default upgrade is implemented, externally consumer-tested, and test-green. Before publishing, close the release hygiene gates in guides/release-readiness.md.

Safe Default: Encryptor / Decryptor

use crypt_guard::{Decryptor, Encryptor};
use crypt_guard::XChaCha20Poly1305;
# #[cfg(feature = "ml-kem-backend")]
use crypt_guard::{MlKem768, kem::{KemBackend, ml_kem::MlKem768Impl}};
use crypt_guard::kem::backend::OsRng;

fn main() -> Result<(), crypt_guard::error::CryptError> {
    #[cfg(feature = "ml-kem-backend")]
    {
    let mut rng = OsRng;
    let (public_key, secret_key) = MlKem768Impl::keypair(&mut rng)?;

    // Seal: ML-KEM encapsulate -> HKDF -> XChaCha20-Poly1305 AEAD
    let envelope = Encryptor::<MlKem768, XChaCha20Poly1305>::new()
        .recipient(public_key.as_ref().to_vec())
        .plaintext(b"hello post-quantum world")
        .seal()?;

    // Open: ML-KEM decapsulate -> HKDF -> AEAD verify + decrypt
    let plaintext = Decryptor::<MlKem768, XChaCha20Poly1305>::new()
        .secret_key(secret_key.as_ref().to_vec())
        .open(&envelope)?;

    assert_eq!(plaintext, b"hello post-quantum world");
    }
    Ok(())
}

The Envelope type is a self-describing serialisable blob: { header, kem_ciphertext, nonce, ciphertext }. The nonce is generated internally and bound into the AEAD AAD; callers never juggle it separately.

What is New in v2

Protocol: HPKE-shaped CGv2 Envelope

crypt_guard v2 follows the structural pattern of HPKE (RFC 9180) as deployed by Cloudflare, AWS, and Google for post-quantum TLS:

Sender:
  (kem_ct, shared_secret) = ML-KEM.Encapsulate(recipient_pk)
  session_key, base_nonce = HKDF(ikm=shared_secret, salt=kem_ct,
                                  info="crypt_guard:v2:aead:<alg>")
  ciphertext = AEAD.Seal(session_key, nonce, aad, plaintext)
  envelope   = { header, kem_ct, nonce, ciphertext }

Receiver:
  shared_secret = ML-KEM.Decapsulate(kem_ct, recipient_sk)
  session_key   = HKDF(same params)
  plaintext     = AEAD.Open(session_key, nonce, aad, ciphertext)

The shared secret is zeroized immediately after key derivation, following the NIST SP 800-227 direction for KEM-based protocols. The header field carries the algorithm identifiers (kem_id, kdf_id, aead_id) so the envelope is self-describing and forwards-compatible.

Supported Algorithms

Key Encapsulation (KEM)

Authenticated Encryption (AEAD)

Digital Signatures

Feature Flags

To use only the new FIPS path without legacy code:

[dependencies]
crypt_guard = { version = "2.0.0", default-features = true }

To include the legacy path for reading data encrypted with v1.x:

[dependencies]
crypt_guard = { version = "2.0.0", features = ["legacy-pqclean"] }

Typestate Design: Kyber<Process, Size, Content, Algorithm>

The underlying Kyber<P, S, C, A> type encodes four axes in the type:

Calling encrypt_file on a Message instance is a compile error (E0599). The Encryptor/Decryptor builders use the same underlying type but expose only the safe Data path by default.

Signing

use crypt_guard::kem::backend::OsRng;
use crypt_guard::sign::{SignAlgorithm, ml_dsa::MlDsa65Impl};

let mut rng = OsRng;
let (sk, vk) = MlDsa65Impl::keypair(&mut rng)?;
let sig = MlDsa65Impl::sign(&sk, b"my message")?;
MlDsa65Impl::verify(&vk, b"my message", &sig)?;
# Ok::<(), crypt_guard::error::CryptError>(())

Architecture

crypt_guard::api           (Encryptor / Decryptor — safe entry points)
  -> crypt_guard::protocol (CGv2 Envelope + Header + AAD construction)
  -> crypt_guard::kem      (ML-KEM backend trait + ML-KEM-512/768/1024)
  -> crypt_guard::kdf      (HKDF-SHA256/512 with domain-separated labels)
  -> crypt_guard::core     (AEAD wiring; typestate Kyber<P,S,C,A>)
  -> crypt_guard::sign     (ML-DSA, SLH-DSA)
  -> crypt_guard::legacy   (pqcrypto Kyber/Falcon/Dilithium — feature-gated)

Release Readiness

The safe-default upgrade is complete and currently verified across:

cargo fmt --check
cargo test
cargo test --no-default-features --features ml-kem-backend,ml-dsa-backend
cargo test --no-default-features --features legacy-pqclean

Before publishing the release, finish the release gates:

• clean the Git index so generated/cache artifacts such as old/.cargo-home/** and test.log are not part of the release
• run and address a release clippy pass, or explicitly scope warning cleanup to a post-2.0 maintenance milestone
• keep the known non-blocking design debt documented: raw byte keys at the Encryptor/Decryptor boundary, broad compatibility re-exports, and legacy module cleanup

See guides/release-readiness.md for the current checklist.

Legacy Compatibility

If you have data encrypted with crypt_guard v1.x (pqcrypto Kyber, tuple-return API, manual nonce), enable the legacy-pqclean feature:

[dependencies]
crypt_guard = { version = "2.0.0", features = ["legacy-pqclean"] }

The old Kyber<Encryption, Kyber1024, Message, AES> types, the encryption! / decryption! macros, the kyber_keypair! macro, and the tuple-returning encrypt_msg / decrypt_msg functions remain available under the legacy module and through the crate re-exports.

// Legacy usage (requires --features legacy-pqclean)
use crypt_guard::{*, error::*};

let (public_key, secret_key) = kyber_keypair!(1024);
let (ciphertext, kyber_secret) = encryption!(
    public_key.to_owned(), 1024,
    b"hello".to_vec(), "passphrase", AES
)?;
let plaintext = decryption!(
    secret_key.to_owned(), 1024,
    ciphertext, "passphrase", kyber_secret, AES
)?;

References

• FIPS 203 — ML-KEM
• FIPS 204 — ML-DSA
• FIPS 205 — SLH-DSA
• NIST SP 800-227 — Recommendations for Key-Encapsulation Mechanisms
• RFC 9180 — Hybrid Public Key Encryption (HPKE)