Crate quantum_shield

Expand description

§Quantum Shield

Hybrid post-quantum cryptography for Rust:

Encryption: X25519 + ML-KEM-1024 (FIPS 203) hybrid KEM feeding a SHA3-256 combiner, with AES-256-GCM payload encryption. Both key agreements enter one KDF, so an attacker must break both the classical and the post-quantum layer to recover a message.
Signatures: Ed25519 + ML-DSA-87 (FIPS 204), both always present and both required to verify — the post-quantum signature cannot be stripped.

All algorithm implementations are pure Rust (RustCrypto and dalek crates); the crate builds and runs natively on Apple Silicon, x86-64, and other targets without a C toolchain.

§Security status

This library and the underlying ml-kem/ml-dsa crates have not been independently audited. The library implements the FIPS 203/204 algorithms via RustCrypto; the library itself is not FIPS-validated. Evaluate accordingly before using it to protect production data.

Artifacts produced by quantum-shield 0.1.x use a cryptographically broken format and are rejected with Error::LegacyV1Artifact.

§Example

use quantum_shield::{HybridCrypto, verify};

let alice = HybridCrypto::generate()?;
let bob = HybridCrypto::generate()?;

// Alice encrypts a message for Bob.
let envelope = alice.seal_for(b"Hybrid PQ message", bob.public_keys())?;
let plaintext = bob.open(&envelope)?;
assert_eq!(plaintext, b"Hybrid PQ message");

// Alice signs a message; Bob verifies it.
let signature = alice.sign(b"I agree to these terms", b"contract")?;
verify(b"I agree to these terms", b"contract", &signature, alice.public_keys())?;

Wire objects (Envelope, HybridSignature, PublicKeyBundle) serialize to versioned binary formats via to_bytes/from_bytes; the format is specified in docs/design.md.

Modules§

prelude: Commonly used items.

Structs§

Envelope: An encrypted message: hybrid KEM ciphertext plus AEAD-protected payload.
HybridCrypto: A hybrid keypair with convenience methods for the common workflows.
HybridSignature: A hybrid signature: Ed25519 and ML-DSA-87, both always present.
KeyId: A short, stable identifier for a public-key bundle: the first KEY_ID_LEN bytes of SHA3-256(QSP2 bytes). Useful for referencing or pinning a key (e.g. in a rotation record) without carrying the full bundle.
KeyPair: A complete hybrid keypair: private seeds plus derived key objects.
MultiRecipientEnvelope: An encrypted message addressed to one or more recipients.
PublicKeyBundle: The public keys of a hybrid keypair.
RotationAttestation: A signed statement that one keypair authorizes a successor public bundle at a given epoch.
StreamOpener: Decrypts a stream produced by StreamSealer, one chunk at a time.
StreamSealer: Encrypts a payload as a sequence of independently authenticated chunks.
Zeroizing: Zeroizing is a a wrapper for any Z: Zeroize type which implements a Drop handler which zeroizes dropped values.

Enums§

Error: Errors that can occur during cryptographic operations.

Constants§

CEK_COMMIT_LEN: Length of the CEK commitment in a multi-recipient envelope (bytes).
CEK_LEN: Content-encryption key length for multi-recipient envelopes (bytes).
ED25519_PK_LEN: Ed25519 public key length in bytes.
ED25519_SEED_LEN: Ed25519 private key seed length in bytes.
ED25519_SIG_LEN: Ed25519 signature length in bytes.
ENVELOPE_AAD_LEN: Length of the authenticated envelope header (everything before the AEAD ciphertext): header + ephemeral X25519 key + ML-KEM ciphertext + nonce. This entire prefix is bound into the AEAD tag as associated data.
ENVELOPE_OVERHEAD: Total envelope overhead on top of the plaintext length.
HEADER_LEN: Length of the common wire header: magic (4) + version (1) + suite (1).
KEY_ID_LEN: Length of a truncated key identifier (SHA3-256(QSP2)[..16]).
MAGIC_ENVELOPE: Magic prefix of a serialized Envelope.
MAGIC_MULTI: Magic prefix of a serialized multi-recipient envelope.
MAGIC_PUBLIC_BUNDLE: Magic prefix of a serialized PublicKeyBundle.
MAGIC_ROTATION: Magic prefix of a serialized rotation attestation.
MAGIC_SECRET_BUNDLE: Magic prefix of a serialized secret-key bundle.
MAGIC_SIGNATURE: Magic prefix of a serialized HybridSignature.
MAGIC_STREAM: Magic prefix of a serialized streaming header.
MAX_CONTEXT_LEN: Maximum signing/verification context length in bytes (mirrors the FIPS 204 context-string limit).
MAX_PLAINTEXT_LEN: Maximum plaintext length accepted by seal (64 MiB).
MAX_RECIPIENTS: Maximum recipients per multi-recipient envelope (DoS bound; enforced at both seal and parse time, since open trial-decrypts every wrap).
MLDSA87_SIG_LEN: ML-DSA-87 signature length in bytes.
MLDSA87_VK_LEN: ML-DSA-87 verifying (public) key length in bytes.
MLDSA_SEED_LEN: ML-DSA private key seed (xi) length in bytes (FIPS 204 Algorithm 6).
MLKEM1024_CT_LEN: ML-KEM-1024 ciphertext length in bytes.
MLKEM1024_EK_LEN: ML-KEM-1024 encapsulation (public) key length in bytes.
MLKEM_SEED_LEN: ML-KEM (d,z) seed length in bytes (FIPS 203 private key seed form).
NONCE_LEN: AES-256-GCM nonce length in bytes.
PUBLIC_BUNDLE_LEN: Serialized PublicKeyBundle length in bytes.
ROTATION_CONTEXT: Signing context for rotation attestations.
SECRET_BUNDLE_LEN: Serialized secret-key bundle length in bytes (seeds only).
SIGNATURE_LEN: Serialized HybridSignature length in bytes.
STREAM_CHUNK_SIZE: Plaintext bytes per chunk in a streaming envelope (64 KiB).
STREAM_HEADER_LEN: Length of a streaming header: header + ephemeral X25519 key + ML-KEM ciphertext + nonce prefix.
STREAM_NONCE_PREFIX_LEN: Length of the random nonce prefix in a streaming envelope. The 12-byte AES-GCM nonce is prefix (7) || u32 chunk counter (4) || last-flag (1).
SUITE_ID: Cipher suite id 1: X25519 + ML-KEM-1024, AES-256-GCM, Ed25519 + ML-DSA-87.
TAG_LEN: AES-256-GCM authentication tag length in bytes.
WIRE_VERSION: Wire format version produced and accepted by this crate.
WRAP_LEN: Per-recipient wrap length in a multi-recipient envelope: ephemeral X25519 key + ML-KEM ciphertext + wrap nonce + wrapped CEK (CEK + AEAD tag).
X25519_PK_LEN: X25519 public key length in bytes.
X25519_SK_LEN: X25519 secret key length in bytes.

Functions§

open: Decrypt an Envelope with keypair.
open_multi: Decrypt a multi-recipient envelope with keypair, if it is a recipient.
seal: Encrypt plaintext for recipient.
seal_multi: Encrypt plaintext for every recipient in recipients.
verify: Verify a HybridSignature over message and context against the signer’s PublicKeyBundle.
verify_rotation: Verify a rotation attestation against the trusted old public bundle.

Type Aliases§

Result: Result type alias for quantum-shield operations.