Crate aegis 

AEGIS for Rust

This is a Rust implementation of AEGIS.

AEGIS is a new family of authenticated encryption algorithms, offering high security and exceptional performance on modern desktop, server, and mobile CPUs.

API documentation

Cargo flags

• std: allow dynamic allocations. This is the default.

• pure-rust: don’t use the cc crate to take advantage of the implementations from libaegis. Setting this flag will substantially degrade performance and some features may not be available. When using the pure-rust implementation, adding RUSTFLAGS="-C target-cpu=native" to the environment variable prior to compiling the project is highly recommended for better performance.

• rustcrypto-traits-06: add traits from rust-crypto/aead version 0.6. Alternative interfaces are available in the compat namespace.

• raf: encrypted random-access file I/O with OS-provided randomness. Requires std and the C backend (incompatible with pure-rust). See the RAF section below.

• raf-core: like raf but without getrandom. Use this on platforms where OS randomness is unavailable (e.g. freestanding wasm) and supply your own RNG via RafBuilder::with_rng().

• js: enables getrandom with the wasm_js backend for use in wasm32-unknown-unknown environments with JavaScript.

Random Access Files (RAF)

The raf feature exposes an encrypted random-access file API built on top of libaegis. Files are split into independently encrypted chunks, each authenticated with AEAD. Reads and writes at arbitrary byte offsets are supported without decrypting the entire file. An optional Merkle tree provides whole-file integrity verification.

Supported algorithms

All six AEGIS variants are available: Aegis128L, Aegis128X2, Aegis128X4, Aegis256, Aegis256X2, Aegis256X4.

Quick start

use aegis::raf::{Raf, Aegis256};

// Create a new encrypted file
let master_key = [0u8; 32];
let key = Raf::<Aegis256>::derive_master_key(&master_key, b"my-app/files").unwrap();
let mut f = Raf::<Aegis256>::create_file("data.raf", &key).unwrap();
f.write(b"hello world", 0).unwrap();
drop(f);

// Open and read back
let mut f = Raf::<Aegis256>::open_file("data.raf", &key).unwrap();
let mut buf = vec![0u8; 11];
f.read(&mut buf, 0).unwrap();
assert_eq!(&buf, b"hello world");

You can also use the builder API for more control, or to supply a custom RNG on platforms without OS randomness (e.g. freestanding wasm):

use aegis::raf::{RafBuilder, Aegis128L, FileIo};

struct MyRng;

impl aegis::raf::RafRng for MyRng {
    fn fill(&mut self, buf: &mut [u8]) -> Result<(), aegis::raf::Error> {
        // fill buf with random bytes from your source
        Ok(())
    }
}

let io = FileIo::create("data.raf").unwrap();
let key = [0u8; 16];
let mut f = RafBuilder::<Aegis128L>::with_rng(MyRng)
    .chunk_size(4096)
    .truncate(true)
    .create(io, &key)
    .unwrap();

Context-bound keys

If an application has a long-lived master key, derive a RAF key for each file or file family instead of reusing the raw master key directly:

use aegis::raf::{Aegis128L, Raf};

let master_key = [0u8; 16];
let key = Raf::<Aegis128L>::derive_master_key(&master_key, b"my-app/files").unwrap();

Different contexts produce independent keys. An empty context is allowed and still derives a RAF-scoped key; it is not a pass-through of the master key. Contexts are limited to 120 bytes for 128-bit variants and 72 bytes for 256-bit variants.

When you do not have an algorithm in hand, derive_key performs the same derivation parameterized only by the key length (16 or 32 bytes), inferred from the master key:

use aegis::raf::derive_key;

let master_key = [0u8; 32];
let key = derive_key(&master_key, b"my-app/files").unwrap();

Builder options

RafBuilder controls file creation and opening:

• chunk_size(n) – set the chunk size in bytes (default: 65536, only used on create).
• truncate(true) – truncate the file on create.
• rng(r) – supply a custom RafRng implementation.
• merkle(hasher, max_chunks) – enable Merkle tree integrity with a custom MerkleHasher.

Operations

Raf<A> provides:

• read(buf, offset) / write(data, offset) – random-access I/O at any byte offset.
• size() – current logical file size.
• truncate(new_size) – shrink the file.
• sync() – flush to storage.
• cursor() – returns a RafCursor implementing std::io::Read, Write, and Seek.
• merkle_rebuild() / merkle_verify() / merkle_commitment(out) – Merkle tree operations (requires Merkle to be enabled via the builder).

Custom I/O

Implement the RafIo trait to use any storage backend:

pub trait RafIo {
    fn read_at(&mut self, buf: &mut [u8], offset: u64) -> std::io::Result<()>;
    fn write_at(&mut self, buf: &[u8], offset: u64) -> std::io::Result<()>;
    fn get_size(&mut self) -> std::io::Result<u64>;
    fn set_size(&mut self, size: u64) -> std::io::Result<()>;
    fn sync(&mut self) -> std::io::Result<()> { Ok(()) }
}

FileIo is the provided implementation for std::fs::File.

Probing files

To inspect an encrypted file without opening it:

use aegis::raf::{self, FileIo};

let mut io = FileIo::open("data.raf").unwrap();
let info = raf::probe(&mut io).unwrap();
println!("algorithm: {:?}, chunk_size: {}, file_size: {}",
    info.algorithm, info.chunk_size, info.file_size);

WebAssembly

RAF works on WebAssembly targets:

• Freestanding wasm (wasm32-unknown-unknown without JS): use --features raf-core and supply a custom RafRng via RafBuilder::with_rng().
• wasm + JavaScript: use --features raf-core,js to get OsRng backed by crypto.getRandomValues.
• WASI: use --features raf for automatic OS-provided randomness.

Benchmarks

AEGIS is very fast on CPUs with parallel execution pipelines and AES support.

Benchmarks can be reproduced using export CC="clang -O3 -march=native" and the cargo bench or cargo-zigbuild bench commands.

For performance, clang is recommended over gcc.

Encryption (16 KB)

Authentication (64 KB)

Mobile benchmarks

Modules

aegis256

AEGIS-256.

aegis128l

AEGIS-128L.

aegis128x2

AEGIS-128X2, the 2-lane variant of AEGIS-128L.

aegis128x4

AEGIS-128X4, the 4-lane variant of AEGIS-128L.

aegis256x2

AEGIS-256X2, the 2-lane variant of AEGIS-256.

aegis256x4

AEGIS-256X4, the 4-lane variant of AEGIS-256.

compat

Implementations of third-party crate traits for the AEGIS ciphers.

rafraf

Encrypted random-access file I/O built on top of the AEGIS ciphers.

Enums

Error

Errors returned by the AEGIS encryption and authentication functions.