tholos_pq/lib.rs
1//! # tholos-pq
2//!
3//! A pure Rust implementation of post-quantum multi-recipient encryption with a stable,
4//! versioned wire format.
5//!
6//! ## Algorithm Suite
7//!
8//! - **Key Encapsulation:** ML-KEM-1024 (Kyber-1024) for per-recipient key wrapping
9//! - **Symmetric Encryption:** XChaCha20-Poly1305 for payload and CEK encryption
10//! - **Digital Signatures:** Dilithium-3 for sender authentication
11//! - **Wire Format:** Canonical CBOR with versioning
12//!
13//! ## Features
14//!
15//! - Multi-recipient encryption: encrypt once for N recipients
16//! - Sender authentication: verify sender identity and signature
17//! - Post-quantum security: all primitives are quantum-resistant
18//! - Stable wire format: versioned format for interoperability
19//! - Pure Rust: no C dependencies
20//!
21//! ## Example
22//!
23//! ```rust
24//! use tholos_pq::*;
25//!
26//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! // Generate recipient keypairs
28//! let (pub_a, priv_a) = gen_recipient_keypair("A");
29//! let (pub_b, priv_b) = gen_recipient_keypair("B");
30//!
31//! // Generate sender keypair
32//! let sender = gen_sender_keypair("S1");
33//!
34//! // Build allowed sender list
35//! let allowed = vec![(sender.sid.clone(), sender_pub(&sender).pk_dilithium)];
36//!
37//! // Encrypt message for multiple recipients
38//! let message = b"Hello, post-quantum world!";
39//! let wire = encrypt(message, &sender, &[pub_a.clone(), pub_b.clone()])?;
40//!
41//! // Each recipient can decrypt
42//! let decrypted_a = decrypt(&wire, "A", &priv_a.sk_kyber, &allowed)?;
43//! let decrypted_b = decrypt(&wire, "B", &priv_b.sk_kyber, &allowed)?;
44//!
45//! assert_eq!(decrypted_a, message);
46//! assert_eq!(decrypted_b, message);
47//! # Ok(())
48//! # }
49//! ```
50//!
51//! ## Security Considerations
52//!
53//! - All cryptographic operations use secure random number generation
54//! - Keys should be stored securely and never exposed
55//! - The allowed sender list must be managed carefully to prevent unauthorized access
56//! - Wire formats should be validated before decryption
57//!
58//! ## License
59//!
60//! Licensed under the Apache License, Version 2.0.
61
62mod errors;
63mod types;
64mod crypto;
65
66pub use errors::TholosError;
67pub use types::*;
68pub use crypto::*;
69