add documentation

1 files changed, 29 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f4d867b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,29 @@
+# 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");
+```
+
+## License
+
+This crate is licensed under the terms of the MIT license. You can find the full license text in LICENSE.