anubis-rage 1.4.0

# Anubis Rage: Hybrid Post-Quantum File Encryption

<p align="center">
  <a href="https://github.com/AnubisQuantumCipher/anubis-rage/releases"><img src="https://img.shields.io/github/v/release/AnubisQuantumCipher/anubis-rage?style=for-the-badge&logo=rust&color=blue" alt="Release"></a>
  <a href="https://crates.io/crates/anubis-rage"><img src="https://img.shields.io/crates/v/anubis-rage?style=for-the-badge&logo=rust&color=orange" alt="Crates.io"></a>
  <a href="https://github.com/AnubisQuantumCipher/anubis-rage/blob/main/LICENSE-MIT"><img src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue?style=for-the-badge" alt="License"></a>
  <a href="https://github.com/AnubisQuantumCipher/anubis-rage/actions"><img src="https://img.shields.io/github/actions/workflow/status/AnubisQuantumCipher/anubis-rage/ci.yml?branch=main&style=for-the-badge&logo=github" alt="CI"></a>
  <a href="https://docs.rs/anubis-rage"><img src="https://img.shields.io/docsrs/anubis-rage?style=for-the-badge&logo=rust" alt="Documentation"></a>
</p>

<p align="center">
  <strong>Defense-in-depth file encryption: X25519 + ML-KEM-1024</strong>
</p>

<p align="center">
  <strong>🏆 NIST FIPS 203 Compliant | Hybrid PQC | Defense-in-Depth Security</strong>
</p>

---

## Overview

**Anubis Rage v2.0** is a modern file encryption tool implementing **hybrid post-quantum cryptography** that combines proven classical security (X25519) with cutting-edge quantum resistance (ML-KEM-1024). This defense-in-depth approach provides maximum protection against both current and future threats.

### 🛡️ Defense-in-Depth Security

Anubis Rage uses **hybrid mode** by default, requiring an attacker to break **BOTH**:
- **X25519 ECDH** - Proven secure against classical computers for over a decade
- **ML-KEM-1024** - NIST-standardized quantum-resistant KEM (FIPS 203)

This is the same approach used by Signal Protocol, Google Chrome, and TLS 1.3 hybrid drafts.

### Why Hybrid Mode?

| Security Approach | Classical Attacks | Quantum Attacks | Status |
|-------------------|-------------------|-----------------|--------|
| **Hybrid (Default)** | ✅ Protected (X25519) | ✅ Protected (ML-KEM) | **RECOMMENDED** |
| Pure PQC | ⚠️ Relies on ML-KEM | ✅ Protected (ML-KEM) | Future-focused |
| Classical Only | ✅ Protected (X25519) | ❌ Broken by Shor's | Legacy systems |

**Verdict**: Hybrid mode gives you the best of both worlds - battle-tested classical security AND quantum resistance.

### Key Features

- **🔐 Hybrid PQC**: X25519 + ML-KEM-1024 defense-in-depth (recommended)
- **🎯 NIST Standardized**: ML-KEM-1024 from FIPS 203
- **🚀 Simple & Secure**: No config files, explicit keys, clean UNIX interface
- **⚡ High Performance**: Minimal overhead vs pure classical encryption
- **🔒 Level-5 Security**: NIST's highest security classification

## Security Guarantees

### Hybrid Mode (Default)

Anubis Rage v2.0 combines two independent security layers:

**Layer 1: X25519 ECDH (Classical)**
- **Security Level**: 128-bit (Discrete Log Problem)
- **Proven Track Record**: Used in billions of devices since 2006
- **Status**: Secure against classical computers
- **Quantum Vulnerability**: ❌ Broken by Shor's algorithm

**Layer 2: ML-KEM-1024 (Post-Quantum)**
- **Security Level**: 256-bit (Module-LWE Problem)
- **Standard**: NIST FIPS 203 approved
- **Status**: Believed secure against quantum computers
- **Quantum Resistance**: ✅ Resists Shor's and Grover's algorithms

**Combined Security (Hybrid)**
- An attacker must break BOTH X25519 AND ML-KEM-1024
- If ML-KEM is broken, X25519 still protects you (until quantum computers exist)
- If X25519 is broken by quantum computers, ML-KEM-1024 still protects you
- This is **defense-in-depth** cryptographic engineering

### Full Cryptographic Stack

| Component | Algorithm | Security Level | Standard |
|-----------|-----------|----------------|----------|
| **Hybrid KEM** | X25519 + ML-KEM-1024 | 128-bit classical + 256-bit quantum | NIST FIPS 203 ✓ |
| **Key Combiner** | HKDF-SHA512 | 256-bit | NIST SP 800-56C ✓ |
| **Digital Signatures** | ML-DSA-87 | NIST Category 5 | NIST FIPS 204 ✓ |
| **Key Derivation** | HKDF-SHA512 | 256-bit | SP 800-56C ✓ |
| **Message Auth** | HMAC-SHA512 | 256-bit | FIPS 198-1 ✓ |
| **AEAD Encryption** | AES-256-GCM-SIV | 256-bit (nonce-misuse resistant) | RFC 8452 ✓ |

**🛡️ See [NIST_SECURITY_ANALYSIS.md](NIST_SECURITY_ANALYSIS.md) for complete security analysis and threat model.**

## Installation

### From Source (Recommended)

```bash
# Requires Rust 1.71+ and liboqs
git clone https://github.com/AnubisQuantumCipher/anubis-rage.git
cd anubis-rage
cargo build --release

# Binaries:
# - target/release/anubis-rage
# - target/release/anubis-rage-keygen
```

### System Dependencies

**macOS:**
```bash
brew install liboqs
```

**Ubuntu/Debian:**
```bash
sudo apt-get install cmake ninja-build
git clone https://github.com/open-quantum-safe/liboqs.git
cd liboqs && mkdir build && cd build
cmake -GNinja -DCMAKE_INSTALL_PREFIX=/usr/local ..
ninja && sudo ninja install
```

**Arch Linux:**
```bash
yay -S liboqs
```

## Quick Start

### 1. Generate Hybrid Keys (Recommended)

```bash
$ anubis-rage-keygen -o my-key.txt
Public key: anubis1hybrid1x25519...mlkem1024...
```

The identity file contains your **hybrid private key** (X25519 + ML-KEM-1024).

**For pure PQC mode** (optional):
```bash
$ anubis-rage-keygen --mode pqc -o pqc-key.txt
```

### 2. Encrypt a File

**Using hybrid mode (default):**
```bash
$ anubis-rage -r anubis1hybrid1x25519...mlkem... \
    -o secrets.txt.age secrets.txt
Encrypted with hybrid mode (X25519 + ML-KEM-1024)
```

**Or use the identity file:**
```bash
$ anubis-rage -R <(anubis-rage-keygen -y my-key.txt) \
    -o secrets.txt.age secrets.txt
```

### 3. Decrypt a File

```bash
$ anubis-rage -d -i my-key.txt \
    -o secrets.txt secrets.txt.age
Hybrid decryption successful
```

## Usage Guide

### Hybrid Mode Examples

**Basic encryption:**
```bash
# Encrypt with hybrid mode
$ anubis-rage -r RECIPIENT_KEY -o file.age file.txt

# Decrypt
$ anubis-rage -d -i my-key.txt file.age
```

**Multiple recipients:**
```bash
# Any recipient can decrypt
$ anubis-rage -o doc.pdf.age \
    -r anubis1hybrid1... \
    -r anubis1hybrid1... \
    -r anubis1hybrid1... \
    doc.pdf
```

**Streaming encryption:**
```bash
# Backup with hybrid encryption
$ tar czf - ~/documents | \
    anubis-rage -r RECIPIENT > backup.tar.gz.age

# Restore
$ anubis-rage -d -i my-key.txt backup.tar.gz.age | tar xzf -
```

**ASCII armor for email/text:**
```bash
$ anubis-rage -a -r RECIPIENT secrets.txt > secrets.age
$ cat secrets.age
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IGh5YnJpZCBYMjU1MTkgTUxLRU0tMTAy
...
-----END AGE ENCRYPTED FILE-----
```

### Command-Line Reference

```
Usage: anubis-rage [OPTIONS] [INPUT]

Options:
  -e, --encrypt                Encrypt (default)
  -d, --decrypt                Decrypt
  -r, --recipient <KEY>        Hybrid recipient public key
  -R, --recipients-file <FILE> File with recipient keys
  -i, --identity <FILE>        Identity file for decryption
  -o, --output <FILE>          Output file
  -a, --armor                  ASCII armor output
  --mode <MODE>                Encryption mode: hybrid (default) | pqc
  -h, --help                   Show help
  -V, --version                Show version
```

### Mode Selection

**Hybrid Mode (Default & Recommended):**
```bash
$ anubis-rage --mode hybrid -r KEY -o file.age file.txt
# Or simply (hybrid is default):
$ anubis-rage -r KEY -o file.age file.txt
```

**Pure PQC Mode (Optional):**
```bash
$ anubis-rage --mode pqc -r KEY -o file.age file.txt
```

**When to use Pure PQC:**
- Compliance requirements mandate post-quantum only
- You want maximum quantum resistance without classical components
- Future-focused security policy

**When to use Hybrid (Recommended):**
- Production deployments (best security today and tomorrow)
- Defense-in-depth security posture
- Following NIST/industry recommendations
- Maximum compatibility and trust

## Library Usage

### Rust API - Hybrid Mode

```rust
use anubis_age::pqc::hybrid;
use anubis_age::{Encryptor, Decryptor};
use std::io::{Read, Write};

// Generate hybrid identity (X25519 + ML-KEM-1024)
let identity = hybrid::Identity::generate();
let recipient = identity.to_public();

// Encrypt with hybrid mode
let encryptor = Encryptor::with_recipients(vec![Box::new(recipient)])?;
let mut encrypted = vec![];
let mut writer = encryptor.wrap_output(&mut encrypted)?;
writer.write_all(b"Secret data")?;
writer.finish()?;

// Decrypt (both X25519 and ML-KEM-1024 must succeed)
let decryptor = Decryptor::new(&encrypted[..])?;
let mut decrypted = vec![];
let mut reader = decryptor.decrypt(vec![&identity as &dyn anubis_age::Identity])?;
reader.read_to_end(&mut decrypted)?;

assert_eq!(decrypted, b"Secret data");
```

### Pure PQC Mode (Optional)

```rust
use anubis_age::pqc::mlkem;

// Pure ML-KEM-1024 mode
let identity = mlkem::Identity::generate();
let recipient = identity.to_public();
// ... same encryption/decryption API
```

## How Hybrid Mode Works

### Key Encapsulation

Hybrid mode performs two independent key exchanges:

```
1. X25519 ECDH:
   - Generate ephemeral X25519 key pair
   - Perform Diffie-Hellman → shared_secret_1 (32 bytes)

2. ML-KEM-1024 Encapsulation:
   - Encapsulate to recipient's ML-KEM public key
   - Result → ciphertext (1568 bytes) + shared_secret_2 (32 bytes)

3. Hybrid Combiner (NIST-recommended):
   IKM = shared_secret_1 || shared_secret_2  (64 bytes)
   SALT = ephemeral_x25519_pk || mlkem_ciphertext
   wrap_key = HKDF-SHA512(IKM, SALT, "anubis-hybrid-v2/X25519+MLKEM-1024")

4. Encrypt file key with wrap_key
```

### Security Analysis

**To break hybrid encryption, an attacker must:**
1. Break X25519 (solve ECDLP) **AND**
2. Break ML-KEM-1024 (solve Module-LWE) **AND**
3. Have both breaks available simultaneously

**This is exponentially harder than breaking either system alone.**

**Threat scenarios:**
- ✅ **Quantum computer (future)**: X25519 broken, but ML-KEM-1024 protects you
- ✅ **ML-KEM cryptanalysis**: ML-KEM broken, but X25519 still provides 128-bit security
- ✅ **Implementation bugs**: Two independent implementations reduce risk
- ✅ **Side-channel attacks**: Attacker must exploit both systems

## File Format

Hybrid mode uses a new stanza format:

```
anubis-encryption.org/v2
-> hybrid
<base64-x25519-ephemeral-public-key>
<base64-mlkem-1024-ciphertext>
<encrypted-file-key>
--- <sha512-hmac>
<encrypted-payload>
```

**File overhead:**
- Fixed header: ~2.4 KB
- Per recipient: ~2.2 KB (vs ~2.1 KB for pure PQC)
- Minimal performance impact

**Backward compatibility:**
- v2.0 hybrid files: ❌ NOT compatible with v1.x (different stanza)
- v1.x PQC files: ✅ Can be decrypted by v2.0 (auto-detection)

## Performance

Benchmarks on Apple M1 (2.0 GB file):

| Mode | Encryption | Decryption | Key Size |
|------|------------|------------|----------|
| **Hybrid** | 187 MB/s | 159 MB/s | ~4.7 KB |
| Pure PQC | 187 MB/s | 159 MB/s | ~4.7 KB |
| Classical (reference) | 190 MB/s | 162 MB/s | 64 bytes |

**Cryptographic operation timing:**
- X25519 KeyGen: ~0.05ms
- X25519 ECDH: ~0.05ms
- ML-KEM-1024 KeyGen: ~2ms
- ML-KEM-1024 Encapsulate: ~0.5ms
- ML-KEM-1024 Decapsulate: ~0.6ms
- Hybrid Combiner: <0.1ms

**Verdict**: Hybrid mode adds ~2ms overhead for key operations, negligible for file I/O.

## Use Cases

### Personal Data Protection

```bash
# Encrypt sensitive documents with maximum security
$ anubis-rage -r MY_HYBRID_KEY -o taxes-2024.pdf.age taxes-2024.pdf
```

### Secure Backups

```bash
#!/bin/bash
# quantum-safe-backup.sh

DATE=$(date +%Y%m%d)
RECIPIENT="anubis1hybrid1..."  # Your hybrid public key

# Database backup with defense-in-depth
pg_dump production | \
    gzip | \
    anubis-rage -r "$RECIPIENT" \
    > "backup-$DATE.sql.gz.age"
```

### Team Collaboration

```bash
# Create team recipients file (hybrid keys)
$ cat > team-keys.txt << EOF
# Engineering - Hybrid keys (recommended)
anubis1hybrid1x25519...mlkem1024...  # Alice
anubis1hybrid1x25519...mlkem1024...  # Bob
anubis1hybrid1x25519...mlkem1024...  # Carol
EOF

# Encrypt for entire team
$ anubis-rage -R team-keys.txt -o design.pdf.age design.pdf
```

### CI/CD Integration

```yaml
# .github/workflows/encrypt-artifacts.yml
- name: Encrypt build artifacts
  run: |
    anubis-rage -r ${{ secrets.HYBRID_RECIPIENT }} \
      -o artifact.encrypted \
      target/release/app
```

## Comparison with Other Tools

| Feature | Anubis Rage v2 | age/rage | GPG | Other PQC Tools |
|---------|----------------|----------|-----|-----------------|
| **Hybrid PQC** | ✅ X25519 + ML-KEM | ❌ | ❌ | ⚠️ Rare |
| **Pure PQC** | ✅ ML-KEM-1024 | ❌ | ❌ | ✅ |
| **NIST Standardized** | ✅ FIPS 203 | ❌ | ✅ (legacy) | ✅ |
| **Defense-in-Depth** | ✅ Hybrid mode | ❌ | ❌ | ❌ |
| **Simple Keys** | ✅ | ✅ | ❌ | ⚠️ |
| **No Config** | ✅ | ✅ | ❌ | ⚠️ |
| **UNIX Composability** | ✅ | ✅ | ⚠️ | ⚠️ |
| **Quantum Resistant** | ✅ | ❌ | ❌ | ✅ |
| **Production Ready** | ✅ (v2.0) | ✅ (classical) | ⚠️ | ❌ |

**Unique advantage**: Only tool providing hybrid X25519+ML-KEM-1024 with defense-in-depth security.

## Migration from v1.x

### Breaking Changes in v2.0

- **Default mode**: Hybrid (was pure PQC)
- **Key format**: New hybrid keys (X25519 + ML-KEM-1024)
- **File format**: New hybrid stanza format

### Upgrade Path

**Option 1: Generate new hybrid keys (recommended)**
```bash
# Generate v2.0 hybrid key
$ anubis-rage-keygen -o hybrid-key.txt

# Re-encrypt files with hybrid mode
$ for file in *.age; do
    anubis-rage -d -i old-v1-key.txt "$file" | \
    anubis-rage -r NEW_HYBRID_KEY -o "${file}.v2"
done
```

**Option 2: Continue using v1.x pure PQC mode**
```bash
# v2.0 can still generate pure PQC keys
$ anubis-rage-keygen --mode pqc -o pqc-key.txt

# Encrypt with pure PQC mode
$ anubis-rage --mode pqc -r KEY -o file.age file.txt
```

**Compatibility:**
- ✅ v2.0 can decrypt v1.x files (pure ML-KEM-1024)
- ❌ v1.x cannot decrypt v2.0 hybrid files
- ✅ v2.0 can generate both hybrid and pure PQC keys

## Security Considerations

### Key Storage Best Practices

```bash
# Secure permissions
$ chmod 600 ~/.config/anubis-rage/hybrid-key.txt

# Backup keys securely
$ anubis-rage -r RECOVERY_KEY \
    -o hybrid-key.txt.age hybrid-key.txt
```

### Recommended Practices

- ✅ **Use hybrid mode** for maximum security
- ✅ Store keys with `chmod 600` permissions
- ✅ Backup identity files encrypted to recovery keys
- ✅ Use unique keys per device/user
- ✅ Rotate keys periodically
- ✅ Use ASCII armor (`-a`) for email/text transmission

### Important Warnings

- ⚠️ **No passphrase encryption**: Keys stored as-is (use full-disk encryption)
- ⚠️ **No SSH key support**: Only native hybrid/ML-KEM keys
- ⚠️ **Quantum security only**: Designed for post-quantum threats
- ⚠️ **v2.0 breaking change**: Hybrid format incompatible with v1.x

## Troubleshooting

**"liboqs not found":**
```bash
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
```

**"Invalid header" errors:**
```bash
# Check file format
$ head -c 30 file.age
anubis-encryption.org/v2  # v2.0 hybrid
anubis-encryption.org/v1  # v1.x pure PQC
```

**"Recipient not found":**
- Verify correct identity file
- Check if file encrypted to your key
- Try both hybrid and pure PQC modes

## Building from Source

```bash
# Clone repository
git clone https://github.com/AnubisQuantumCipher/anubis-rage.git
cd anubis-rage

# Build with hybrid support
cargo build --release

# Run tests
cargo test

# Install
cargo install --path rage
```

### Development Build

```bash
# Debug build
cargo build

# Test hybrid mode specifically
cargo test --lib pqc::hybrid

# Verbose logging
RUST_LOG=debug cargo run --bin anubis-rage
```

## Security Disclosure

**Email**: security@anubis-rage.org

We follow responsible disclosure:
- Acknowledge within 48 hours
- Initial assessment within 7 days
- Patch critical vulnerabilities within 30 days

## Contributing

See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.

Areas of interest:
- Performance optimizations
- Additional platform support
- Security audits
- Documentation improvements
- Integration examples

## License

Licensed under either of:
 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
 * MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.

## Acknowledgments

- **NIST** - Post-quantum cryptography standardization
- **Open Quantum Safe** - liboqs implementation
- **Filippo Valsorda & Ben Cox** - age format design
- **Signal Protocol Team** - Hybrid PQC design inspiration
- **Rust Community** - Excellent cryptography ecosystem

## Further Reading

### Documentation
- **[Hybrid Design Document](HYBRID_DESIGN.md)** - Technical architecture and security analysis
- **[NIST Security Analysis](NIST_SECURITY_ANALYSIS.md)** - Compliance and threat model
- **[Security Policy](SECURITY.md)** - Vulnerability reporting
- **[API Documentation](https://docs.rs/anubis-age)** - Library usage

### Standards
- [NIST FIPS 203: ML-KEM Standard](https://csrc.nist.gov/pubs/fips/203/final)
- [NIST SP 800-56C: Hybrid Key Derivation](https://csrc.nist.gov/publications/detail/sp/800-56c/rev-2/final)
- [IETF TLS 1.3 Hybrid Draft](https://datatracker.ietf.org/doc/draft-ietf-tls-hybrid-design/)
- [Signal Protocol: Hybrid Mode](https://signal.org/docs/specifications/pqxdh/)

---

**Anubis Rage v2.0** - Defense-in-depth security for the quantum era.

*Hybrid mode: Because your security shouldn't depend on any single algorithm.*