Crate pqfile 

Quantum-resistant file encryption library.

pqfile provides authenticated, post-quantum file encryption using NIST-standardised algorithms. All format versions are stable on disk and documented in docs/FORMAT.md.

Algorithms

• Key encapsulation: ML-KEM-512, ML-KEM-768 (default), ML-KEM-1024 (NIST FIPS 203)
• Hybrid mode: X25519 + ML-KEM-768 via HKDF-SHA256
• Symmetric cipher: ChaCha20-Poly1305 (RFC 8439)
• Session key wrapping: AES-256-GCM (multi-recipient modes)
• Signatures: ML-DSA-65 (NIST FIPS 204)
• Passphrase protection: Argon2id (m=64 MiB, t=3, p=4) + AES-256-GCM

Quick start

use pqfile::{keygen, encrypt, decrypt};

// Generate a key pair
let (pub_pem, priv_pem) = keygen::keygen_bytes(768, None).unwrap();

// Encrypt
let plaintext = b"hello, post-quantum world";
let ciphertext = encrypt::encrypt_bytes(&pub_pem, plaintext).unwrap();

// Decrypt
let recovered = decrypt::decrypt_bytes(&priv_pem, &ciphertext, None).unwrap();
assert_eq!(recovered, plaintext);

Streaming

For large files, use the streaming API to avoid loading the entire file into memory:

use pqfile::{keygen, encrypt, decrypt};
use std::io::Cursor;

let (pub_pem, priv_pem) = keygen::keygen_bytes(768, None).unwrap();
let plaintext = b"streaming data";

let mut ct = Vec::new();
encrypt::encrypt_stream(&pub_pem, plaintext.len() as u64, pqfile::format::CHUNK_SIZE,
    &mut Cursor::new(plaintext), &mut ct).unwrap();

let mut out = Vec::new();
decrypt::decrypt_stream(&priv_pem, &mut ct.as_slice(), &mut out, None).unwrap();
assert_eq!(out, plaintext);

Crate layout

Items re-exported to the crate root (pqfile::PqfileError, pqfile::CHUNK_SIZE, pqfile::PqfReader, pqfile::PqfInfo, pqfile::inspect_stream, pqfile::PqfHeaderInfo, pqfile::RecipientInfo, and the typed key wrappers) are the stable, high-level surface.

Operation functions (encrypt_stream, decrypt_stream, signcrypt, etc.) are always addressed via their module path - e.g. pqfile::encrypt::encrypt_stream.

The typed wrappers in pqfile::keys (PqfPublicKey, PqfPrivateKey, PqfSigningKey, PqfVerifyingKey) are the recommended way to pass keys; they validate eagerly on construction. Raw &str PEM parameters on operation functions are the lower-level alternative when a typed wrapper is not convenient.

Stability

The public API is stable at 1.0. Items in the modules listed in STABILITY.md will not be removed or renamed before a 2.0 release. New items and new #[non_exhaustive] variants may be added in minor (1.x) releases without a major version bump. See STABILITY.md for the full policy.

Re-exports

pub use error::PqfileError;

pub use format::CHUNK_SIZE;

pub use inspect::inspect_stream;

pub use inspect::PqfHeaderInfo;

pub use inspect::RecipientInfo;

pub use keys::PqfPrivateKey;

pub use keys::PqfPublicKey;

pub use keys::PqfSigningKey;

pub use keys::PqfVerifyingKey;

pub use reader::PqfInfo;

pub use reader::PqfReader;

pub use writer::PqfWriter;

Modules

add_recipient

Add a recipient to an existing multi-recipient file without re-encrypting.

archive

Encrypted multi-file archive support (PQFA format).

cert

Signable public key certificates: a minimal PKI layer over sign. Signable public key certificates: a minimal PKI layer built entirely from existing primitives (no new dependencies).

decrypt

Decryption: all format versions v2 through v7, all KEM variants.

encrypt

Encryption: single-recipient, multi-recipient, compressed, and parallel modes.

error

Error types.

format

On-disk format constants and header structs.

hardware

Hardware-backed private key support: OS credential store, future PKCS#11.

inspect

File header inspection without decryption.

keygen

Key generation: ML-KEM (512/768/1024), hybrid X25519+ML-KEM-768.

keys

Typed key wrapper structs (PqfPublicKey, PqfPrivateKey, PqfSigningKey, PqfVerifyingKey).

padding

Plaintext-length padding (Padmé) and output truncation for stripping it back off. Plaintext-length padding (Padmé) and output truncation.

reader

Streaming decryptor: PqfReader<R> implements std::io::Read.

recipient_string

Compact Bech32m recipient strings (pqf1…): encode/decode public keys without PEM files.

rekey

Rekey: transfer a v3/v5 file to a new recipient without re-encrypting.

repassphrase

Passphrase upgrade: change or migrate the passphrase on any encrypted private key.

revoke

Key revocation: create and check .revoked sidecar files.

sealed_sender

Sealed sender: deniable sender authentication via a static X25519 identity keypair, distinct from the non-repudiable proof signcrypt provides. Sealed sender: deniable sender authentication for encrypted files.

shamir

Shamir secret sharing: split and reconstruct private keys (M-of-N).

shred

Secure file shredding: overwrite then delete.

sign

ML-DSA-65 signing key generation, signing, and verification.

signcrypt

Signcrypt: sign-then-encrypt and decrypt-then-verify in a single step.

writer

Streaming encryptor: PqfWriter<W> implements std::io::Write.

Structs

CalibrationResult

Result of benchmarking Argon2id on this machine via calibrate.

Functions

calibrate

Benchmarks Argon2id on this machine and recommends parameters whose wall-clock cost is close to target_ms milliseconds.