Crate crypt_guard 

CryptGuard v3.1.0

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

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

Workspace layout and features

crypt_guard is a facade. The cryptography lives in crypt_guard_core and is re-exported here unchanged, so every crypt_guard::… path keeps working. Optional layers are enabled through features:

Feature	Adds
(default)	the cryptographic core only — no Tower, Hyper or Tokio
service	[service]: typed, non-Clone Tower crypto/KMS service
hyper	hyper: HTTP adapter, TowerToHyperService bridge

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. Legacy CipherChaCha symmetric cipher: raw XChaCha20 stream cipher with an HMAC-SHA512 tag.

cipher_xchacha_poly

XChaCha20-Poly1305 AEAD implementation. Legacy CipherChaChaPoly symmetric cipher: XChaCha20-Poly1305 AEAD with an outer HMAC-SHA512 tag.

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

AES

Cipher-algorithm marker: AES-256-CBC with HMAC.

AesCtr

Cipher-algorithm marker: AES-256-CTR (nonce-bearing).

AesGcmSiv

Cipher-algorithm marker: AES-256-GCM-SIV (nonce-bearing).

AesXts

Cipher-algorithm marker: AES-256-XTS (double-width key).

Data

Content-kind marker: the target is a raw byte slice.

Decryption

Process-direction marker: the Kyber instance will perform decryption.

Encryption

Process-direction marker: the Kyber instance will perform encryption.

FileMetadata

Manages metadata related to a file, including its location, type, and state within a cryptographic context.

Files

Content-kind marker: the target is a file path.

Key

Represents a cryptographic key — its type tag and raw bytes.

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.

LoggerCompat

Legacy compatibility stub.

Message

Content-kind marker: the target is a UTF-8 message string.

XChaCha20

Cipher-algorithm marker: XChaCha20 stream cipher (nonce-bearing).

XChaCha20Poly1305

Cipher-algorithm marker: XChaCha20-Poly1305 AEAD (nonce-bearing).

Enums

FileState

Enumerates possible states a file can be in, especially in the context of encryption and decryption.

FileTypes

Enumerates the types of files recognized by the cryptographic system.

KeyTypes

Enumerates the types of cryptographic keys supported by the system.

KyberVariant

Enum representing Kyber variants.

Statics

LOGGER

Global logger compatibility shim — zero state, never locks.

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

init_log

Initialize the tracing_subscriber for binary entry points.

initialize_logger

Initialize the logger from a file path — called by the activate_log proc-macro.

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.