pqfile/
lib.rs

1//! Quantum-resistant file encryption library.
2//!
3//! pqfile provides authenticated, post-quantum file encryption using NIST-standardised
4//! algorithms. All format versions are stable on disk and documented in `docs/FORMAT.md`.
5//!
6//! # Algorithms
7//!
8//! - **Key encapsulation**: ML-KEM-512, ML-KEM-768 (default), ML-KEM-1024 (NIST FIPS 203)
9//! - **Hybrid mode**: X25519 + ML-KEM-768 via HKDF-SHA256
10//! - **Symmetric cipher**: ChaCha20-Poly1305 (RFC 8439)
11//! - **Session key wrapping**: AES-256-GCM (multi-recipient modes)
12//! - **Signatures**: ML-DSA-65 (NIST FIPS 204)
13//! - **Passphrase protection**: Argon2id (m=64 MiB, t=3, p=1) + AES-256-GCM
14//!
15//! # Quick start
16//!
17//! ```no_run
18//! use pqfile::{keygen, encrypt, decrypt};
19//!
20//! // Generate a key pair
21//! let (pub_pem, priv_pem) = keygen::keygen_bytes(768, None).unwrap();
22//!
23//! // Encrypt
24//! let plaintext = b"hello, post-quantum world";
25//! let ciphertext = encrypt::encrypt_bytes(&pub_pem, plaintext).unwrap();
26//!
27//! // Decrypt
28//! let recovered = decrypt::decrypt_bytes(&priv_pem, &ciphertext, None).unwrap();
29//! assert_eq!(recovered, plaintext);
30//! ```
31//!
32//! # Streaming
33//!
34//! For large files, use the streaming API to avoid loading the entire file into memory:
35//!
36//! ```no_run
37//! use pqfile::{keygen, encrypt, decrypt};
38//! use std::io::Cursor;
39//!
40//! let (pub_pem, priv_pem) = keygen::keygen_bytes(768, None).unwrap();
41//! let plaintext = b"streaming data";
42//!
43//! let mut ct = Vec::new();
44//! encrypt::encrypt_stream(&pub_pem, plaintext.len() as u64, pqfile::format::CHUNK_SIZE,
45//!     &mut Cursor::new(plaintext), &mut ct).unwrap();
46//!
47//! let mut out = Vec::new();
48//! decrypt::decrypt_stream(&priv_pem, &mut ct.as_slice(), &mut out, None).unwrap();
49//! assert_eq!(out, plaintext);
50//! ```
51//!
52//! # Stability
53//!
54//! The public API is not yet stabilised for 1.0. Breaking changes between minor versions
55//! are possible until a stable 1.0 release is announced. See the roadmap.
56
57#![warn(missing_docs)]
58
59// ── Public modules ─────────────────────────────────────────────────────────
60
61/// Encrypted multi-file archive support (PQFA format).
62pub mod archive;
63
64/// Decryption: all format versions v2 through v7, all KEM variants.
65pub mod decrypt;
66
67/// Encryption: single-recipient, multi-recipient, compressed, and parallel modes.
68pub mod encrypt;
69
70/// Error types.
71pub mod error;
72
73/// On-disk format constants and header structs.
74pub mod format;
75
76/// Key generation: ML-KEM (512/768/1024), hybrid X25519+ML-KEM-768.
77pub mod keygen;
78
79/// Passphrase-based key protection (Argon2id + AES-256-GCM).
80pub mod passphrase;
81
82/// Streaming decryptor: `PqfReader<R>` implements `std::io::Read`.
83pub mod reader;
84
85/// Rekey: transfer a v3/v5 file to a new recipient without re-encrypting.
86pub mod rekey;
87
88/// Key revocation: create and check `.revoked` sidecar files.
89pub mod revoke;
90
91/// Shamir secret sharing: split and reconstruct private keys (M-of-N).
92pub mod shamir;
93
94/// ML-DSA-65 signing key generation, signing, and verification.
95pub mod sign;
96
97/// Signcrypt: sign-then-encrypt and decrypt-then-verify in a single step.
98pub mod signcrypt;
pqfile/lib.rs

pqfile/
lib.rs
