anubis_rage/

lib.rs

//! # Anubis Rage - Post-Quantum Secure File Encryption
//!
//! <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 20px; border-radius: 10px; margin: 20px 0;">
//! <h2 style="color: white; margin: 0;">🔐 Quantum-Resistant File Encryption</h2>
//! <p style="color: white; margin: 10px 0 0 0;">Powered by ML-KEM-1024 (NIST FIPS 203) and ML-DSA-87 (NIST FIPS 204)</p>
//! </div>
//!
//! **Anubis Rage** is a modern, secure file encryption tool and library implementing **NIST-standardized
//! post-quantum cryptography** to protect your data against both current and future threats, including
//! attacks from quantum computers.
//!
//! ## 🎯 Key Features
//!
//! - **🔒 Post-Quantum Security**: ML-KEM-1024 encryption resistant to quantum attacks
//! - **✍️ Digital Signatures**: Mandatory ML-DSA-87 signatures for authenticated encryption (v1.1.0+)
//! - **🏆 NIST Level-5 Security**: Highest standardized post-quantum security level (256-bit equivalent)
//! - **⚡ High Performance**: Efficient implementation via liboqs
//! - **🚀 Simple API**: Clean, ergonomic interface for both CLI and library usage
//! - **🔐 Secure by Default**: No passphrases, no config files, explicit keys only
//!
//! ## 📦 Installation
//!
//! ### As a Library
//!
//! Add to your `Cargo.toml`:
//! ```toml
//! [dependencies]
//! anubis-rage = "1.1"
//! ```
//!
//! ### As CLI Tools
//!
//! ```bash
//! cargo install anubis-rage
//! ```
//!
//! This installs three command-line tools:
//! - **`anubis-rage`** - Encrypt/decrypt files with quantum-resistant encryption
//! - **`anubis-rage-keygen`** - Generate ML-KEM-1024 encryption keys
//! - **`anubis-rage-sign`** - Generate ML-DSA-87 signing keys
//!
//! ## 🚀 Quick Start (Library)
//!
//! ### Basic Encryption/Decryption
//!
//! ```rust
//! use anubis_rage::pqc::mlkem;
//! use std::io::{Read, Write};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Generate ML-KEM-1024 keypair
//! let identity = mlkem::Identity::generate();
//! let recipient = identity.to_public();
//!
//! // Encrypt data
//! let plaintext = b"Secret quantum-resistant message!";
//! let encryptor = anubis_rage::Encryptor::with_recipients(vec![&recipient as _])?;
//! let mut ciphertext = vec![];
//! let mut writer = encryptor.wrap_output(&mut ciphertext)?;
//! writer.write_all(plaintext)?;
//! writer.finish()?;
//!
//! // Decrypt data
//! let decryptor = anubis_rage::Decryptor::new(&ciphertext[..])?;
//! let mut decrypted = vec![];
//! decryptor.decrypt(vec![&identity as _])?.read_to_end(&mut decrypted)?;
//!
//! assert_eq!(decrypted, plaintext);
//! println!("✓ Encryption and decryption successful!");
//! # Ok(())
//! # }
//! ```
//!
//! ### Multiple Recipients
//!
//! ```rust
//! use anubis_rage::pqc::mlkem;
//! use std::io::Write;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Generate keys for multiple recipients
//! let alice_identity = mlkem::Identity::generate();
//! let bob_identity = mlkem::Identity::generate();
//!
//! let alice_recipient = alice_identity.to_public();
//! let bob_recipient = bob_identity.to_public();
//!
//! // Encrypt to multiple recipients (any one can decrypt)
//! let encryptor = anubis_rage::Encryptor::with_recipients(vec![
//!     &alice_recipient as _,
//!     &bob_recipient as _,
//! ])?;
//!
//! let mut ciphertext = vec![];
//! let mut writer = encryptor.wrap_output(&mut ciphertext)?;
//! writer.write_all(b"Team secret")?;
//! writer.finish()?;
//!
//! // Both Alice and Bob can decrypt
//! let decryptor = anubis_rage::Decryptor::new(&ciphertext[..])?;
//! let mut decrypted = vec![];
//! decryptor.decrypt(vec![&alice_identity as _])?.read_to_end(&mut decrypted)?;
//! assert_eq!(decrypted, b"Team secret");
//! # Ok(())
//! # }
//! ```
//!
//! ## 💻 Quick Start (CLI)
//!
//! ### Generate Keys
//!
//! ```bash
//! # Generate encryption keys
//! anubis-rage-keygen -o my-key.txt
//! # Public key: anubis1mlkem11ptpjg078r7rjw3x86e0mj346h8223derqruv8qx...
//!
//! # Generate signing keys (required for v1.1.0+)
//! anubis-rage-sign keygen --output signing-key.txt
//! # verification key: anubis1mldsa871tu22gw7ysld7gsw3c8dn7aydpagllmunu...
//! ```
//!
//! ### Encrypt with Mandatory Signature (v1.1.0+)
//!
//! ```bash
//! anubis-rage -r anubis1mlkem1... \
//!     --signing-key signing-key.txt \
//!     -o secrets.txt.age secrets.txt
//! # File encrypted and signed with ML-DSA-87
//! ```
//!
//! ### Decrypt with Mandatory Verification (v1.1.0+)
//!
//! ```bash
//! anubis-rage -d \
//!     --verify-key anubis1mldsa87... \
//!     -i my-key.txt \
//!     -o secrets.txt secrets.txt.age
//! # Signature verified successfully
//! ```
//!
//! ## 🔐 Security Guarantees
//!
//! ### Encryption (ML-KEM-1024)
//!
//! - **Algorithm**: Module-Lattice-Based Key-Encapsulation Mechanism
//! - **Standard**: NIST FIPS 203 (approved August 2024)
//! - **Security Level**: NIST Category 5 (≥256-bit equivalent)
//! - **Security Property**: IND-CCA2 (Indistinguishability under Adaptive Chosen-Ciphertext Attack)
//! - **Quantum Resistance**: Secure against Shor's and Grover's algorithms
//! - **Key Sizes**:
//!   - Public Key: 1,568 bytes
//!   - Secret Key: 3,168 bytes
//!   - Ciphertext: 1,568 bytes
//!
//! ### Digital Signatures (ML-DSA-87, Mandatory in v1.1.0+)
//!
//! - **Algorithm**: Module-Lattice-Based Digital Signature Algorithm
//! - **Standard**: NIST FIPS 204 (approved August 2024)
//! - **Security Level**: NIST Category 5 (≥256-bit equivalent)
//! - **Security Property**: SUF-CMA (Strong Unforgeability under Chosen-Message Attack)
//! - **Quantum Resistance**: Secure against quantum forgery attacks
//! - **Key/Signature Sizes**:
//!   - Public Key: 2,592 bytes
//!   - Secret Key: 4,896 bytes
//!   - Signature: 4,595 bytes
//!
//! ### Additional Security Features
//!
//! - **AEAD Encryption**: AES-256-GCM-SIV (RFC 8452, nonce-misuse resistant)
//! - **Key Derivation**: HKDF-SHA512 (NIST SP 800-56C)
//! - **Header Authentication**: HMAC-SHA512 (64-byte MAC)
//! - **Forward Secrecy**: Ephemeral key wrapping
//! - **No Metadata Leakage**: Recipient public keys not stored in ciphertext
//!
//! ## 🔄 Version Compatibility
//!
//! ### v1.1.0+ (Current) - Mandatory Signatures
//!
//! All files are automatically signed with ML-DSA-87:
//! - Encryption requires `--signing-key`
//! - Decryption requires `--verify-key`
//! - Provides authenticated encryption
//! - Detects tampering automatically
//!
//! ### v1.0.0 - Encryption Only
//!
//! - No signature support
//! - Files lack authentication
//! - **⚠️ Not compatible with v1.1.0+**
//!
//! **Migration**: Re-encrypt files with v1.1.0+ to add mandatory signatures.
//!
//! ## ⚡ Performance
//!
//! Benchmarks on 2023 MacBook Pro M2:
//!
//! | Operation | File Size | Time | Throughput |
//! |-----------|-----------|------|------------|
//! | Key Generation | - | ~2ms | - |
//! | Encryption | 1 MB | ~8ms | 125 MB/s |
//! | Encryption | 1 GB | ~7.5s | 133 MB/s |
//! | Decryption | 1 MB | ~8ms | 125 MB/s |
//! | Decryption | 1 GB | ~7.3s | 137 MB/s |
//!
//! ML-DSA-87 signature overhead (v1.1.0+):
//! - Signing: +3-5ms
//! - Verification: +3-5ms
//! - File size: +4.6KB
//!
//! ## 📚 Advanced Usage
//!
//! ### Streaming Large Files
//!
//! ```rust
//! use anubis_rage::pqc::mlkem;
//! use std::fs::File;
//! use std::io::{BufReader, BufWriter, copy};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let identity = mlkem::Identity::generate();
//! let recipient = identity.to_public();
//!
//! // Encrypt large file with streaming
//! let input = BufReader::new(File::open("large-file.bin")?);
//! let output = BufWriter::new(File::create("large-file.bin.age")?);
//!
//! let encryptor = anubis_rage::Encryptor::with_recipients(vec![&recipient as _])?;
//! let mut writer = encryptor.wrap_output(output)?;
//!
//! // Stream data efficiently
//! let mut reader = input;
//! copy(&mut reader, &mut writer)?;
//! writer.finish()?;
//! # Ok(())
//! # }
//! ```
//!
//! ### ASCII Armor Format
//!
//! ```rust
//! use anubis_rage::pqc::mlkem;
//! use anubis_rage::armor::{ArmoredWriter, Format};
//! use std::io::Write;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let identity = mlkem::Identity::generate();
//! let recipient = identity.to_public();
//!
//! let encryptor = anubis_rage::Encryptor::with_recipients(vec![&recipient as _])?;
//!
//! let mut output = vec![];
//! let armored = ArmoredWriter::wrap_output(&mut output, Format::AsciiArmor)?;
//! let mut writer = encryptor.wrap_output(armored)?;
//!
//! writer.write_all(b"Text-safe encrypted data")?;
//! writer.finish()?.finish()?;
//!
//! // Output is ASCII-armored
//! let armored_text = String::from_utf8(output)?;
//! assert!(armored_text.starts_with("-----BEGIN AGE ENCRYPTED FILE-----"));
//! # Ok(())
//! # }
//! ```
//!
//! ## 🆚 Comparison with Other Tools
//!
//! | Feature | Anubis Rage | age/rage | GPG | NaCl |
//! |---------|-------------|----------|-----|------|
//! | Post-Quantum | ✅ ML-KEM-1024 | ❌ X25519 | ❌ RSA/ECC | ❌ X25519 |
//! | PQ Signatures | ✅ ML-DSA-87 | ❌ | ❌ | ❌ |
//! | NIST Standardized | ✅ FIPS 203/204 | ❌ | ✅ (legacy) | ❌ |
//! | Quantum Resistant | ✅ | ❌ | ❌ | ❌ |
//! | Simple API | ✅ | ✅ | ❌ | ✅ |
//! | No Config Files | ✅ | ✅ | ❌ | ✅ |
//!
//! ## 📖 Technical Documentation
//!
//! ### File Format
//!
//! Anubis Rage encrypted files use the following structure:
//!
//! ```text
//! anubis-encryption.org/v1
//! -> MLKEM-1024
//! [base64-encoded-encapsulated-key]
//! [base64-encoded-wrapped-file-key]
//! -> [grease-stanza]
//! [grease-body]
//! --- [86-character-SHA512-MAC]
//! [encrypted-payload]
//! ```
//!
//! With ML-DSA-87 signatures (v1.1.0+), the entire encrypted file is signed.
//!
//! ### Cryptographic Primitives
//!
//! All primitives achieve strong security guarantees:
//!
//! | Component | Algorithm | Security |
//! |-----------|-----------|----------|
//! | KEM | ML-KEM-1024 | NIST L5 (≥256-bit) |
//! | Signature | ML-DSA-87 | NIST L5 (≥256-bit) |
//! | KDF | HKDF-SHA512 | 256-bit |
//! | MAC | HMAC-SHA512 | 256-bit |
//! | AEAD | AES-256-GCM-SIV | 256-bit + nonce-misuse resistant |
//!
//! ## 🔗 Resources
//!
//! - **GitHub**: [AnubisQuantumCipher/anubis-rage](https://github.com/AnubisQuantumCipher/anubis-rage)
//! - **Crates.io**: [anubis-rage](https://crates.io/crates/anubis-rage)
//! - **NIST PQC**: [Post-Quantum Cryptography Project](https://csrc.nist.gov/projects/post-quantum-cryptography)
//! - **FIPS 203**: [ML-KEM Standard](https://csrc.nist.gov/pubs/fips/203/final)
//! - **FIPS 204**: [ML-DSA Standard](https://csrc.nist.gov/pubs/fips/204/final)
//!
//! ## 🛡️ Security Disclosure
//!
//! If you discover a security vulnerability, please report it via:
//! - **GitHub Security Advisories**: [Report a vulnerability](https://github.com/AnubisQuantumCipher/anubis-rage/security/advisories/new)
//! - **GitHub Issues**: [Create an issue](https://github.com/AnubisQuantumCipher/anubis-rage/issues)
//!
//! ## 📄 License
//!
//! Licensed under either of:
//! - Apache License, Version 2.0 ([LICENSE-APACHE](https://github.com/AnubisQuantumCipher/anubis-rage/blob/main/LICENSE-APACHE))
//! - MIT license ([LICENSE-MIT](https://github.com/AnubisQuantumCipher/anubis-rage/blob/main/LICENSE-MIT))
//!
//! at your option.

#![cfg_attr(docsrs, feature(doc_cfg))]
#![forbid(unsafe_code)]
#![deny(rustdoc::broken_intra_doc_links)]
#![deny(missing_docs)]

// Re-export the entire anubis-age library
// Note: cargo will auto-download anubis-age and its dependencies
pub use anubis_age::*;