add notes about fuzzing to readme

1 files changed, 27 insertions, 0 deletions

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.