Crate crypt_guard

Expand description

§CryptGuard v3.0.1

CryptGuard v3 makes pq_hpke the default post-quantum encryption transport. Its default profile is ML-KEM-1024/P-384, SHAKE256, and ChaCha20-Poly1305. The pure-Rust KEM adapter is revision-pinned to draft-ietf-hpke-pq-05; it must not be represented as a final IANA PQ HPKE registration.

§Default transport

pq_hpke::HpkeEnvelope is the versioned crypt_guard CGH3 container. It stores a suite, encapsulation, and ciphertext. Applications always supply HPKE setup info and per-message AEAD AAD separately when opening a record.

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=v1", b"record=1", b"payload",
)?;
let plaintext = envelope.open(keys.private_key(), b"service=v1", b"record=1")?;
assert_eq!(plaintext, b"payload");

Raw Base and PSK transport APIs return a separate HPKE encapsulation (enc) and ciphertext for RFC-style transport. The three standardized AEADs are accepted by these APIs. AES-256-GCM-SIV and XChaCha20-Poly1305 are explicit crypt_guard private extensions and require pq_hpke::HpkeEnvelope.

§CGv2 migration

CGv2 is not a v3 default API or transport. Enable cgv2-compat only to read and migrate existing CGv2 records, then remove it. Default v3 builds neither expose the legacy builders nor silently accept CGv2 ciphertext.

§Other cryptography

ML-DSA and optional SLH-DSA signing remain available. legacy-pqclean retains the historical Kyber/Falcon/Dilithium path for compatibility work.

§References

Re-exports§

pub use crate::key_control::file;
pub use markers::AesGcmSiv;
pub use markers::XChaCha20Poly1305;
pub use crate::markers::AesCtr;
pub use crate::markers::AesGcmSiv;
pub use crate::markers::AesXts;
pub use crate::markers::Data;
pub use crate::markers::Decryption;
pub use crate::markers::Encryption;
pub use crate::markers::Files;
pub use crate::markers::Message;
pub use crate::markers::XChaCha20;
pub use crate::markers::XChaCha20Poly1305;
pub use crate::markers::AES;
pub use crate::key_control::*;
pub use crate::log::*;

Modules§

builder: Builder-style API for encryption/decryption, keygen, and signature flows Fluent builder API over the legacy Kyber encryption, decryption, and signing macros.
cipher_xchacha: XChaCha20 stream cipher implementation.
cipher_xchacha_poly: XChaCha20-Poly1305 AEAD implementation.
cryptography: Cryptographic related functionalitys, enums structs and modules
error: Error types Crate-wide error types for crypt_guard.
hpke: RFC 9180 HPKE suite identifiers and labeled HKDF primitives. RFC 9180 HPKE domain-separation, KDF, and context-core primitives.
hpke_pq: Revision-pinned, vector-gated draft-ietf-hpke-pq-05 HPKE APIs.
kdf: HKDF-SHA256/512 key schedule with domain separation. HKDF-based key schedule with domain separation (Phase 2 — always compiled).
kem: ML-KEM backend trait and ML-KEM-512/768/1024 implementations (FIPS 203). KEM (Key Encapsulation Mechanism) backend trait and ML-KEM implementations.
key_control: File and Key related functionalitys, enums structs and modules Typed key and file-metadata primitives for the key-control subsystem.
kyber: Legacy hub module (src/core/kyber/): keeps KyberData, Kyber struct, KyberFunctions trait, KyberSizeVariant, deprecated size markers, and key_controler (legacy-pqclean). Hub module: Kyber<P, K, D, C> four-axis typestate, KEM variant traits, and cipher markers.
log: Logging related functionalitys Tracing-based logging surface for crypt_guard.
markers: Shared zero-sized-type axis markers (Encryption/Decryption, Files/Message/Data, cipher markers). Re-exported here so crate::* continues to expose them. Shared zero-sized-type (ZST) axis markers used across core/, legacy/, and the public API.
pq_hpke: Canonical v3 PQ HPKE transport API. Canonical v3 post-quantum HPKE API.
sign: SignAlgorithm trait and ML-DSA/SLH-DSA implementations (FIPS 204/205). Digital signature backend trait and FIPS 204/205 implementations.
signed_hpke: Application-layer, explicitly versioned signatures over HPKE transport bindings.
utils

Macros§

archive: Macro to archive a directory or file.
archive_util: Macro for archiving and extracting directories or files.
concat_cipher: Hex-encode a (key_bytes, cipher_bytes) tuple into "hex_key$hex_cipher".
decrypt_file: Macro for encryption of a file, taking a Kyber decryption instance, a PathBuf as well as a passphrase and ciphertext as arguments
decryption
encrypt_file: Macro for encryption of a file, taking a Kyber decryption instance, a PathBuf as well as a passphrase and ciphertext as arguments
encryption
extract: Macro to extract a .tar.xz archive.
log_activity: Emit a structured tracing::info! event for a named activity.
signature
split_cipher: Decode a "hex_key$hex_cipher" string back to (Vec<u8>, Vec<u8>).
verify
write_log: No-op flush macro — previously wrote the string buffer to a log file.

Structs§

Kyber: Represents a generic Kyber structure with templated parameters for process status, Kyber size, content status, and algorithm parameter.
Kyber512: Legacy KEM size marker: Kyber-512.
Kyber768: Legacy KEM size marker: Kyber-768.
Kyber1024: Legacy KEM size marker: Kyber-1024.
KyberData: Represents the data structure for Kyber algorithm, including key and nonce.

Enums§

KyberVariant: Enum representing Kyber variants.

Traits§

CryptographicFunctions: Abstract encrypt/decrypt trait.
KyberFunctions: Trait for Kyber cryptographic functions.
KyberSizeVariant: Trait to specify Kyber size variants.

Functions§

activate_log: Function activating the log, it takes one arg: &str which represents the location of the logfile

Attribute Macros§

activate_log: Attribute macro: injects an initialize_logger(path) helper alongside the annotated fn.

Derive Macros§

ErrorObservable: Derive macro: generate observable constructors for error enum variants.