# zears

[![Crates.io Version](https://img.shields.io/crates/v/zears?style=flat-square)](https://crates.io/crates/zears)
[![Crates.io License](https://img.shields.io/crates/l/zears?style=flat-square)](https://choosealicense.com/licenses/mit/)
[![docs.rs](https://img.shields.io/docsrs/zears?style=flat-square)](https://docs.rs/zears)

Implementation of [AEZ v5](https://www.cs.ucdavis.edu/~rogaway/aez/index.html) in Rust. Works without hardware AES support.

## ☣️ Cryptographic hazmat ☣️

This crate is not battle tested and not audited. It exists as a learning exercise. Use it at your own risk.

## AEZ encryption

From the AEZ website:

> AEZ is an authenticated-encryption (AE) scheme optimized for ease of correct use ("AE made EZ"). It was invented by Viet Tung Hoang, Ted Krovetz, and Phillip Rogaway. The algorithm encrypts a plaintext by appending to it a fixed authentication block (some zero bits) and then enciphering the resulting string with an arbitrary-input-length blockcipher, this tweaked by the nonce, AD, and authenticator length. The approach results in strong security and usability properties, including nonce-reuse misuse resistance, automatic exploitation of decryption-verified redundancy, and arbitrary, user-selectable length expansion.

## Example use

This crate provides an easy-to-use interface for AEZ:

```rust
use zears::Aez;
let aez = Aez::new(b"my key");
let ciphertext = aez.encrypt(b"nonce", &[b"associated data"], 16, b"message");
let plaintext = aez.decrypt(b"nonce", &["associated data"], 16, &ciphertext);
assert_eq!(plaintext.unwrap(), b"message");
```

## Correctness

We cannot guarantee that this implementation implements the AEZ specification
correctly. However, we increase our confidence that it does in two ways:

### Test vectors

The normal unit tests test the encryption (and its parts) based on reference
*test vectors* generated by the reference C code. The vectors are generated via
[Nick Mathewson's tool](https://github.com/nmathewson/aez_test_vectors) and
included in `src/testvectors.rs`.

You check the implementation against the test vectors by running `cargo test`.

### Fuzzing

We use `cargo-fuzz` and include a fuzz target `zears_vs_aez` that takes random
inputs and runs them through both, `zears` and the reference AEZ
implementation. You can start fuzzing by running `cargo fuzz run zers_vs_aez`.

Note that this builds the `aezref` crate, which is a thin wrapper around the
reference implementation. This requires a working C compiler.

**The `aezref` (sub)crate is not meant for actual encryption work! Its
underlying implementation is slow and has side channels.**

## License

This crate is licensed under the terms of the MIT license. You can find the full license text in LICENSE.