anubis-rage 1.2.0

# Anubis Rage: Post-Quantum Secure File Encryption

<p align="center">
  <strong>Quantum-resistant file encryption powered by ML-KEM-1024</strong>
</p>

<p align="center">
  <strong>🏆 NIST Category 5 Certified | FIPS 203 Compliant | CNSA 2.0 Compatible</strong>
</p>

---

## Overview

**Anubis Rage** is a modern, secure file encryption tool implementing **NIST Level-5 post-quantum cryptography** through ML-KEM-1024 (Module-Lattice-Based Key-Encapsulation Mechanism). Built on the age encryption format specification, Anubis Rage provides quantum-resistant protection for your sensitive data.

### Why Anubis Rage?

- **🔐 Quantum-Resistant**: Protected against both classical and quantum computer attacks
- **🎯 NIST Standardized**: Implements ML-KEM-1024 from FIPS 203
- **🚀 Simple & Secure**: No config files, explicit keys, clean UNIX-style interface
- **⚡ High Performance**: Efficient post-quantum cryptography implementation via liboqs
- **🔒 Level-5 Security**: NIST's highest security classification (256-bit equivalent)

### Security Guarantees

Anubis Rage uses **ML-KEM-1024** (formerly Kyber1024) for encryption and **ML-DSA-87** for signatures:

**Encryption (ML-KEM-1024):**
- **IND-CCA2 security** (Indistinguishability under Adaptive Chosen-Ciphertext Attack)
- **NIST Level-5 security**: Equivalent to AES-256
- **Quantum resistance**: Secure against Shor's and Grover's algorithms
- **Standardized**: NIST FIPS 203 approved post-quantum KEM

**Signatures (ML-DSA-87 - Mandatory):**
- **Strong unforgeability** (SUF-CMA security)
- **NIST Level-5 security**: Highest post-quantum security level
- **Quantum resistance**: Secure against quantum forgery attacks
- **Standardized**: NIST FIPS 204 approved post-quantum signature scheme
- **Mandatory**: All encrypted files are automatically signed and verified

### NIST Category 5 Compliance

Anubis Rage achieves **NIST's maximum security classification** throughout its entire cryptographic stack:

| Component | Algorithm | Security Level | Standard |
|-----------|-----------|----------------|----------|
| **Key Encapsulation** | ML-KEM-1024 | NIST Category 5 | FIPS 203 ✓ |
| **Digital Signatures** | ML-DSA-87 | NIST Category 5 | FIPS 204 ✓ |
| **Key Derivation** | HKDF-SHA512 | 256-bit | SP 800-56C ✓ |
| **Message Authentication** | HMAC-SHA512 | 256-bit (64-byte MAC) | FIPS 198-1 ✓ |
| **AEAD Encryption** | AES-256-GCM-SIV | 256-bit | RFC 8452 ✓ |
| **Alternative AEAD** | ChaCha20-Poly1305 | 256-bit | RFC 8439 ✓ |

**🛡️ Complete Security Analysis**: See [NIST_SECURITY_ANALYSIS.md](NIST_SECURITY_ANALYSIS.md) for comprehensive security evaluation, threat model, and CNSA 2.0 compliance details.

## Installation

### From Source (Recommended)

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

# Binaries will be available at:
# - target/release/anubis-rage
# - target/release/anubis-rage-keygen
```

### System Dependencies

Anubis Rage requires **liboqs** (Open Quantum Safe library) for ML-KEM-1024:

**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
```

### Pre-built Binaries

Download the latest release from [GitHub Releases](https://github.com/anubis-rage/anubis-rage/releases).

## Quick Start

### 1. Generate Keys

**Generate encryption keys:**
```bash
$ anubis-rage-keygen -o my-key.txt
Public key: anubis1mlkem11ptpjg078r7rjw3x86e0mj346h8223derqruv8qx...
```

**Generate signing keys (required for encryption):**
```bash
$ anubis-rage-sign keygen --output signing-key.txt
# verification key: anubis1mldsa871tu22gw7ysld7gsw3c8dn7aydpagllmunu...
```

The identity file (`my-key.txt`) contains:
- Your **private key** (ANUBIS-MLKEM-1024-SECRET-...)
- Your **public key** (anubis1mlkem1...)

The signing key file (`signing-key.txt`) contains:
- Your **signing key** (ANUBIS-MLDSA-87-SECRET-...)
- Your **verification key** (anubis1mldsa87...)

**Keep both identity and signing key files secure!**

### 2. Encrypt a File (with mandatory signature)

```bash
$ anubis-rage -r anubis1mlkem11ptpjg078r7rjw3x86e0mj346h8223derqruv8qx... \
    --signing-key signing-key.txt \
    -o secrets.txt.age secrets.txt
File encrypted and signed with ML-DSA-87
```

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

### 3. Decrypt a File (with mandatory verification)

```bash
$ anubis-rage -d \
    --verify-key anubis1mldsa871tu22gw7ysld7gsw3c8dn7aydpagllmunu... \
    -i my-key.txt \
    -o secrets.txt \
    secrets.txt.age
Signature verified successfully
```

You can also pass the verification key file instead of the key string:
```bash
$ anubis-rage -d \
    --verify-key signing-key.txt \
    -i my-key.txt \
    -o secrets.txt \
    secrets.txt.age
```

## Usage Guide

### Command-Line Syntax

```
Usage: anubis-rage [--encrypt] (-r RECIPIENT | -R PATH)... --signing-key <PATH> [-i IDENTITY] [-a] [-o OUTPUT] [INPUT]
       anubis-rage --decrypt --verify-key <KEY> [-i IDENTITY] [-o OUTPUT] [INPUT]

Arguments:
  [INPUT]  Path to a file to read from.

Options:
  -h, --help                    Print this help message and exit.
  -V, --version                 Print version info and exit.
  -e, --encrypt                 Encrypt the input (the default).
  -d, --decrypt                 Decrypt the input.
  -a, --armor                   Encrypt to ASCII-armored format.
  -r, --recipient <RECIPIENT>   Encrypt to the specified ML-KEM-1024 recipient.
  -R, --recipients-file <PATH>  Encrypt to recipients listed at PATH.
  -s, --signing-key <PATH>      ML-DSA-87 signing key file (REQUIRED for encryption).
  -k, --verify-key <KEY>        ML-DSA-87 verification key (REQUIRED for decryption).
  -i, --identity <IDENTITY>     Use the ML-KEM-1024 identity file at IDENTITY.
  -o, --output <OUTPUT>         Write the result to OUTPUT.
```

**Note**: As of v1.1.0, all encrypted files are automatically signed with ML-DSA-87, and all decryption operations automatically verify signatures. The `--signing-key` and `--verify-key` flags are mandatory.

### Multiple Recipients

Encrypt to multiple recipients - any one can decrypt:

```bash
$ anubis-rage -o document.pdf.age \
    --signing-key signing-key.txt \
    -r anubis1mlkem1... \
    -r anubis1mlkem1... \
    document.pdf
```

### Recipients File

Create a file with multiple recipients:

```bash
$ cat team-keys.txt
# Alice - Security Team
anubis1mlkem11ptpjg078r7rjw3x86e0mj346h8223derqruv8qx...
# Bob - DevOps Team
anubis1mlkem11724vpdwkkn80k3jn52dmztr2gf4frmp6ggpet8r...
# Carol - Management
anubis1mlkem115x7s4wgppgwhxzdsnwqf2hugaa3tfe8a9c5hun...

$ anubis-rage -R team-keys.txt --signing-key signing-key.txt -o project-data.tar.gz.age project-data.tar.gz
```

### ASCII Armor

Create ASCII-armored output for safe transmission through text channels:

```bash
$ anubis-rage -a --signing-key signing-key.txt -r anubis1mlkem1... secrets.txt > secrets.txt.age
$ cat secrets.txt.age
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IE1MS0VNLTEwMjQKK1FLMm5sd2lWVEpv
...
-----END AGE ENCRYPTED FILE-----
```

### Streaming Encryption

Anubis Rage works seamlessly with pipes and streams:

```bash
# Encrypt and compress a directory
$ tar czf - ~/documents | anubis-rage --signing-key signing-key.txt -r anubis1mlkem1... > documents.tar.gz.age

# Decrypt and extract
$ anubis-rage -d --verify-key signing-key.txt -i my-key.txt documents.tar.gz.age | tar xzf -

# Database backup
$ pg_dump mydb | anubis-rage --signing-key signing-key.txt -R backup-keys.txt > mydb-$(date +%Y%m%d).sql.age
```

### Identity Management

Convert identity to public key for sharing:

```bash
$ anubis-rage-keygen -y my-key.txt > my-pubkey.txt
$ cat my-pubkey.txt
anubis1mlkem11ptpjg078r7rjw3x86e0mj346h8223derqruv8qx...
```

## Advanced Features

### Format Specification

Anubis Rage uses a quantum-resistant file format based on the age specification:

```
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]
```

The file structure ensures:
- **Authenticated encryption** via AES-256-GCM-SIV or ChaCha20-Poly1305
- **Key encapsulation** via ML-KEM-1024 (2592-byte ciphertext)
- **Header authentication** via HMAC-SHA512 (64-byte MAC, 86 base64 characters)
- **Forward secrecy** through ephemeral key wrapping
- **Recipient privacy** (no public key metadata in file)

### Key Derivation

The file encryption key is derived using:

1. **ML-KEM-1024 Encapsulation**: Generate shared secret (32 bytes)
2. **HKDF-SHA512**: Derive wrapping key from:
   - Shared secret
   - Recipient public key
   - Ciphertext
   - Label: `anubis-encryption.org/v1/MLKEM-1024`
   - NIST Level-5 security with SHA-512
3. **ChaCha20-Poly1305**: Encrypt the file key (16 bytes)
4. **AES-256-GCM-SIV or ChaCha20-Poly1305**: Encrypt payload with derived file key

### Security Considerations

#### ✅ **Recommended Practices**

- Store identity files with `chmod 600` (owner-only access)
- Use unique keys per device/user
- Rotate keys periodically
- Keep backups of identity files in secure locations
- Use `-a/--armor` for transmission over text channels

#### ⚠️ **Important Warnings**

- **No Passphrase Support**: ML-KEM-1024 keys cannot be encrypted with passphrases
- **No SSH Key Support**: Only native ML-KEM-1024 keys are supported
- **No Plugin Support**: Anubis Rage is standalone, no age plugins
- **Quantum Security Only**: This is a specialized post-quantum tool

#### 🔒 **Key Storage Best Practices**

```bash
# Set secure permissions
chmod 600 ~/.config/anubis-rage/identity.txt

# Use hardware security modules (recommended for production)
# Store keys on encrypted volumes
# Consider key escrow for organizational keys
```

## Use Cases

### Personal Data Protection

```bash
# Encrypt personal documents
$ anubis-rage -R ~/.config/anubis-rage/recipients.txt \
    -o ~/Documents/tax-returns-2024.pdf.age \
    ~/Documents/tax-returns-2024.pdf

# Decrypt when needed
$ anubis-rage -d -i ~/.config/anubis-rage/identity.txt \
    ~/Documents/tax-returns-2024.pdf.age \
    -o ~/Documents/tax-returns-2024.pdf
```

### Secure Backups

```bash
#!/bin/bash
# backup.sh - Quantum-safe backup script

DATE=$(date +%Y%m%d)
BACKUP_DIR="/mnt/backups"
RECIPIENTS="~/.config/anubis-rage/backup-keys.txt"

# Backup database with encryption
pg_dump production_db | \
    anubis-rage -R "$RECIPIENTS" \
    > "$BACKUP_DIR/db-$DATE.sql.age"

# Backup application data
tar czf - /var/www/app | \
    anubis-rage -R "$RECIPIENTS" \
    > "$BACKUP_DIR/app-$DATE.tar.gz.age"

echo "Backups completed: $DATE"
```

### Team Collaboration

```bash
# Create shared team key file
$ cat > team-recipients.txt << EOF
# Engineering Team
anubis1mlkem11ptpjg...  # Alice - alice@company.com
anubis1mlkem11724vpd...  # Bob - bob@company.com
anubis1mlkem115x7s4w...  # Carol - carol@company.com
EOF

# Encrypt shared document
$ anubis-rage -R team-recipients.txt \
    -o design-specs.pdf.age design-specs.pdf

# Any team member can decrypt
$ anubis-rage -d -i ~/.ssh/company-key.txt design-specs.pdf.age
```

### Automated Encryption in CI/CD

```yaml
# .github/workflows/secure-artifacts.yml
name: Encrypt Build Artifacts

on:
  push:
    branches: [main]

jobs:
  build-and-encrypt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Anubis Rage
        run: |
          curl -L https://github.com/anubis-rage/anubis-rage/releases/latest/download/anubis-rage-x86_64-linux.tar.gz | tar xz
          sudo mv anubis-rage* /usr/local/bin/

      - name: Build application
        run: cargo build --release

      - name: Encrypt artifacts
        env:
          RECIPIENT_KEY: ${{ secrets.ARTIFACT_RECIPIENT_KEY }}
        run: |
          anubis-rage -r "$RECIPIENT_KEY" \
            -o target/release/app.encrypted \
            target/release/app

      - name: Upload encrypted artifact
        uses: actions/upload-artifact@v3
        with:
          name: encrypted-binary
          path: target/release/app.encrypted
```

## Comparison with Other Tools

| Feature | Anubis Rage | age/rage | GPG | NaCl/libsodium |
|---------|-------------|----------|-----|----------------|
| Post-Quantum Security | ✅ ML-KEM-1024 | ❌ X25519 only | ❌ RSA/ECC | ❌ X25519 only |
| NIST Standardized | ✅ FIPS 203 | ❌ | ✅ (legacy) | ❌ |
| Simple Key Format | ✅ | ✅ | ❌ | ✅ |
| No Config Files | ✅ | ✅ | ❌ | ✅ |
| Forward Secrecy | ✅ | ✅ | ❌ | ✅ |
| Quantum Resistant | ✅ | ❌ | ❌ | ❌ |
| UNIX Composability | ✅ | ✅ | ⚠️ | ⚠️ |

## Performance

Typical performance on modern hardware (2023 MacBook Pro M2):

| Operation | File Size | Time | Throughput |
|-----------|-----------|------|------------|
| Key Generation | - | ~2ms | - |
| Encryption | 1 MB | ~8ms | 125 MB/s |
| Encryption | 100 MB | ~750ms | 133 MB/s |
| Encryption | 1 GB | ~7.5s | 133 MB/s |
| Decryption | 1 MB | ~8ms | 125 MB/s |
| Decryption | 100 MB | ~740ms | 135 MB/s |
| Decryption | 1 GB | ~7.3s | 137 MB/s |

ML-KEM-1024 operations add minimal overhead compared to classical encryption.

## Library Usage

Applications can integrate Anubis Rage functionality using the `age` crate:

```rust
use age::pqc::mlkem::{Identity, Recipient};
use age::{Encryptor, Decryptor};
use std::io::{Read, Write};

// Generate a new ML-KEM-1024 identity
let identity = Identity::generate();
let recipient = identity.to_public();

// Encrypt
let encryptor = Encryptor::with_recipients(vec![Box::new(recipient)])
    .expect("we provided a recipient");

let mut encrypted = vec![];
let mut writer = encryptor.wrap_output(&mut encrypted)?;
writer.write_all(b"Secret message")?;
writer.finish()?;

// Decrypt
let decryptor = match Decryptor::new(&encrypted[..])? {
    Decryptor::Recipients(d) => d,
    _ => unreachable!(),
};

let mut decrypted = vec![];
let mut reader = decryptor.decrypt(vec![&identity as &dyn age::Identity].into_iter())?;
reader.read_to_end(&mut decrypted)?;

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

See the [age crate documentation](https://docs.rs/age) for complete API details.

## Building from Source

### Prerequisites

- **Rust 1.71+**: Install from [rustup.rs](https://rustup.rs/)
- **liboqs**: Open Quantum Safe library
- **CMake & Ninja**: For building liboqs
- **Git**: For cloning the repository

### Build Steps

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

# Build release binaries
cargo build --release

# Run tests
cargo test

# Install locally
cargo install --path rage
```

### Development Build

```bash
# Build with debug symbols
cargo build

# Run with verbose output
RUST_LOG=debug cargo run --bin anubis-rage -- --help

# Run specific tests
cargo test --lib pqc::mlkem
```

## Troubleshooting

### Common Issues

**1. "liboqs not found"**
```bash
# Ensure liboqs is installed and in library path
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH  # Linux
export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH  # macOS
```

**2. "Permission denied" when decrypting**
```bash
# Check identity file permissions
chmod 600 ~/.config/anubis-rage/identity.txt
```

**3. "Invalid header" errors**
```bash
# Verify file is actually encrypted with Anubis Rage
head -c 50 encrypted-file.age
# Should start with: anubis-encryption.org/v1
```

**4. "Recipient not found"**
- Ensure you're using the correct identity file
- Verify the file was encrypted to your public key
- Check for file corruption

## Security Disclosure

If you discover a security vulnerability in Anubis Rage, please email:

**security@anubis-rage.org**

We follow responsible disclosure practices:
- Acknowledge receipt within 48 hours
- Provide initial assessment within 7 days
- Aim to patch critical vulnerabilities within 30 days
- Credit reporters (with permission) in security advisories

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.

### Areas of Interest

- Performance optimizations
- Additional platform support
- Documentation improvements
- Security audits
- Integration examples

## License

Licensed under either of:

 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

## Acknowledgments

- **NIST** - For standardizing post-quantum cryptography
- **Open Quantum Safe** - For the liboqs implementation
- **age specification** - For the elegant file format design
- **Filippo Valsorda & Ben Cox** - For designing the age format
- **Rust community** - For excellent cryptography crates

## Further Reading

### Anubis Rage Documentation
- **[NIST Security Analysis](NIST_SECURITY_ANALYSIS.md)** - Comprehensive NIST Category 5 compliance analysis
- **[Security Policy](SECURITY.md)** - Cryptographic guarantees and vulnerability reporting
- **[Contributing Guide](docs/CONTRIBUTING.md)** - Development and contribution guidelines

### Standards and Specifications
- [NIST Post-Quantum Cryptography Standardization](https://csrc.nist.gov/projects/post-quantum-cryptography)
- [FIPS 203: ML-KEM Standard](https://csrc.nist.gov/pubs/fips/203/final)
- [NIST SP 800-56C: Key Derivation](https://csrc.nist.gov/publications/detail/sp/800-56c/rev-2/final)
- [age specification v1](https://age-encryption.org/v1)
- [Open Quantum Safe Project](https://openquantumsafe.org/)

---

**Anubis Rage** - Protecting your data in the quantum era.