https://github.com/jedisct1/rust-aegis
AEGIS high performance ciphers for Rust.
https://github.com/jedisct1/rust-aegis
aead aegis aegis128 aegis128l aegis256 cipher crypto
Last synced: 3 days ago
JSON representation
AEGIS high performance ciphers for Rust.
- Host: GitHub
- URL: https://github.com/jedisct1/rust-aegis
- Owner: jedisct1
- License: mit
- Created: 2021-10-13T12:23:31.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2026-06-01T07:09:55.000Z (3 days ago)
- Last Synced: 2026-06-01T08:25:12.528Z (3 days ago)
- Topics: aead, aegis, aegis128, aegis128l, aegis256, cipher, crypto
- Language: Rust
- Homepage:
- Size: 3.14 MB
- Stars: 43
- Watchers: 1
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AEGIS for Rust
This is a Rust implementation of [AEGIS](https://datatracker.ietf.org/doc/draft-irtf-cfrg-aegis-aead/).
AEGIS is a new family of authenticated encryption algorithms, offering high security and exceptional performance on modern desktop, server, and mobile CPUs.
# [API documentation](https://docs.rs/aegis)
# 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`](https://github.com/jedisct1/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](#random-access-files-raf) 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
```rust,ignore
use aegis::raf::{Raf, Aegis256};
// Create a new encrypted file
let key = [0u8; 32];
let mut f = Raf::::create_file("data.raf", &key).unwrap();
f.write(b"hello world", 0).unwrap();
drop(f);
// Open and read back
let mut f = Raf::::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):
```rust,ignore
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::::with_rng(MyRng)
.chunk_size(4096)
.truncate(true)
.create(io, &key)
.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` 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:
```rust,ignore
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;
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:
```rust,ignore
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
