From aa259b1c8109bd590c1bd3abda0674729cfdf388 Mon Sep 17 00:00:00 2001 From: Daniel Schadt Date: Tue, 22 Apr 2025 21:43:03 +0200 Subject: add notes about fuzzing to readme --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index b319b24..9ceffca 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![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. @@ -27,6 +28,32 @@ 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. -- cgit v1.2.3