add metadata

1 files changed, 60 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f11059c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,60 @@
+# leona 
+
+[![Crates.io Version](https://img.shields.io/crates/v/leona?style=flat-square)](https://crates.io/crates/leona)
+[![Crates.io License](https://img.shields.io/crates/l/leona?style=flat-square)](https://choosealicense.com/licenses/mit/)
+[![docs.rs](https://img.shields.io/docsrs/leona?style=flat-square)](https://docs.rs/leona)
+
+Implementation of
+[LIONESS](https://link.springer.com/content/pdf/10.1007/3-540-60865-6_48.pdf)
+in Rust. Works with `no_std` and generic over hashes/ciphers.
+
+## ☣️ Cryptographic hazmat ☣️
+
+This crate is not battle tested and not audited. It exists as a learning
+exercise. Use it at your own risk.
+
+## LIONESS
+
+LIONESS is a wide block cipher, constructed using a hash algorithm and a stream
+cipher. From the paper:
+
+> Each ciphertext bit depends on all the plaintext bits in a very complex way,
+> which contributes to the cryptographic strength.
+
+## Example use
+
+You need a hash algorithm and a compatible stream cipher (compatible means that
+the hash output has the same size as the stream cipher key):
+
+```rust
+use leona::{Lioness, ZeroIv};
+use blake2::Blake2sMac256;
+use chacha20::ChaCha20;
+
+type Cipher = Lioness<ZeroIv<ChaCha20>, Blake2sMac256>;
+
+let mut data = [0u8; 64];
+data[..11].copy_from_slice(b"hello world");
+
+let cipher = Cipher::new_dynamic(b"secret");
+cipher.encrypt(&mut data);
+assert_ne!(&data[..11], b"hello world");
+cipher.decrypt(&mut data);
+assert_eq!(&data[..11], b"hello world");
+```
+
+## Alternatives
+
+There are two drawbacks to LIONESS:
+
+1. It is slow.
+2. It cannot encrypt short messages (shorther than the hash output size).
+
+If you require a wide block cipher, consider using a different construction
+(like aez via [aez](https://crates.io/crates/aez) or
+[zears](https://crates.io/crates/zears)).
+
+## License
+
+This crate is licensed under the terms of the MIT license. You can find the full license text in LICENSE.
+