anubis-age 0.11.1

Post-quantum secure encryption library using ML-KEM-1024 (internal dependency for anubis-rage)
Documentation

age Rust library (Anubis Rage Edition)

Post-quantum secure file encryption library with ML-KEM-1024 support

age is a simple, modern, and secure file encryption library. This is the Anubis Rage edition, which extends the original age library with NIST Level-5 post-quantum cryptography through ML-KEM-1024 (Module-Lattice-Based Key-Encapsulation Mechanism).

Features

  • 🔐 Quantum-Resistant: ML-KEM-1024 (NIST FIPS 203) for post-quantum security
  • 🎯 Classical Algorithms: X25519, scrypt, and SSH key support remain available
  • 🚀 Simple API: Small explicit keys, no config options, UNIX-style composability
  • ⚡ High Performance: Efficient implementations via liboqs and Rust crypto ecosystem
  • 🔒 NIST Level-5: Highest standardized post-quantum security level (256-bit equivalent)

What's New in Anubis Rage

This crate provides a set of Rust APIs that can be used to build tools based on the age format, with additional support for post-quantum cryptography:

  • ML-KEM-1024 Recipients: Encrypt to quantum-resistant public keys
  • ML-KEM-1024 Identities: Decrypt with quantum-resistant private keys
  • Backward Compatible: Still supports X25519, scrypt, and SSH keys
  • NIST Standardized: Implements FIPS 203 approved post-quantum KEM

The primary consumer of these APIs is the anubis-rage CLI tool, which provides straightforward quantum-resistant encryption and decryption of files or streams.

Format Specification

The age format specification is at age-encryption.org/v1.

Anubis Rage extends this with ML-KEM-1024 recipient stanzas:

-> MLKEM-1024 [base64-encoded-ciphertext]
[base64-encoded-wrapped-file-key]

The age format was designed by @Benjojo and @FiloSottile.

The reference interoperable Go implementation is available at filippo.io/age.

Installation

Add this line to your Cargo.toml:

age = "0.11"

For post-quantum features, ensure you have liboqs installed:

macOS:

brew install liboqs

Ubuntu/Debian:

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

Usage

Basic Encryption/Decryption

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

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

// Encrypt
let encryptor = Encryptor::with_recipients(vec![&recipient as &dyn age::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(std::iter::once(&identity as &dyn age::Identity))?;
reader.read_to_end(&mut decrypted)?;

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

Using X25519 (Classical)

use age::x25519;

let identity = x25519::Identity::generate();
let recipient = identity.to_public();

// Use same Encryptor/Decryptor API as above

Using Passphrase Encryption

use age::scrypt;

let identity = scrypt::Identity::new("correct horse battery staple");

// Encrypt
let encryptor = Encryptor::with_user_passphrase(
    secrecy::SecretString::new("correct horse battery staple".to_string())
);

// Decrypt using scrypt::Identity

API Documentation

See the documentation for complete API details and examples.

Feature Flags

  • armor - Enables the age::armor module for ASCII-armored age files
  • async - Enables asynchronous APIs for encryption and decryption
  • cli-common - Common helper functions for building age CLI tools
  • ssh - Enables the age::ssh module for reusing SSH key files
  • web-sys - WebAssembly support for passphrase work factor calculation
  • unstable - In-development functionality (no stability guarantees)

Security Considerations

Post-Quantum Security

ML-KEM-1024 provides:

  • IND-CCA2 security: Indistinguishability under adaptive chosen-ciphertext attack
  • NIST Level-5: Equivalent to AES-256 classical security
  • Quantum resistance: Secure against Shor's and Grover's algorithms
  • Standardized: NIST FIPS 203 compliant

Classical Security

X25519, scrypt, and SSH support remain available for:

  • Backward compatibility with existing age files
  • Integration with existing SSH infrastructure
  • Scenarios where post-quantum security is not required

Recommendations

For long-term data protection or high-security scenarios, use ML-KEM-1024 recipients to ensure quantum resistance.

For short-term encryption or integration with existing systems, X25519 and SSH keys remain secure against classical attacks.

Comparison with Original rage

Feature Anubis Rage Original rage
Post-Quantum Security ✅ ML-KEM-1024 ❌ No
NIST Standardized PQC ✅ FIPS 203 ❌
X25519 Support ✅ Yes ✅ Yes
SSH Key Support ✅ Yes ✅ Yes
Passphrase Encryption ✅ Yes ✅ Yes
File Compatibility ✅ Full ✅ Standard age
Quantum Resistant ✅ With ML-KEM ❌ No

Examples

Multiple Recipients

use age::{x25519, pqc::mlkem};

let x25519_identity = x25519::Identity::generate();
let mlkem_identity = mlkem::Identity::generate();

// Encrypt to both classical and post-quantum recipients
let recipients: Vec<&dyn age::Recipient> = vec![
    &x25519_identity.to_public(),
    &mlkem_identity.to_public(),
];

let encryptor = Encryptor::with_recipients(recipients.into_iter())
    .expect("we provided recipients");

Streaming Encryption

use age::Encryptor;
use std::io::Write;

let recipient = mlkem::Identity::generate().to_public();
let encryptor = Encryptor::with_recipients(vec![&recipient])?;

let output = std::fs::File::create("encrypted.age")?;
let mut writer = encryptor.wrap_output(output)?;

// Stream data in chunks
for chunk in data_chunks {
    writer.write_all(chunk)?;
}

writer.finish()?;

ASCII Armoring

use age::armor::ArmoredWriter;

let recipient = mlkem::Identity::generate().to_public();
let encryptor = Encryptor::with_recipients(vec![&recipient])?;

let output = Vec::new();
let armored = ArmoredWriter::wrap_output(output, age::armor::Format::AsciiArmor)?;
let mut writer = encryptor.wrap_output(armored)?;

writer.write_all(b"Secret data")?;
let armored_output = writer.finish()?.into_inner()?;

// armored_output contains ASCII-armored ciphertext

Library Development

Building

# Build the library
cargo build --release

# Run tests
cargo test

# Build with all features
cargo build --all-features

Contributing

See CONTRIBUTING.md for guidelines on:

  • Code style and conventions
  • Adding new features
  • Localization support
  • Testing requirements

License

Licensed under either of:

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 post-quantum cryptography standardization (FIPS 203)
  • Open Quantum Safe - For the liboqs ML-KEM-1024 implementation
  • Filippo Valsorda & Ben Cox - For designing the age format
  • Original rage contributors - For the excellent foundation
  • Rust crypto community - For high-quality cryptography crates

Further Reading

Anubis Rage - Protecting your data in the quantum era.