Document chacha20 and salsa20 crates (closes #17)

Improve rustdoc with examples and add a `README.md` to each crate
RustCrypto · Aug 16, 2019 · 3dec15f · 3dec15f
1 parent 936daf9
commit 3dec15f
Show file tree

Hide file tree

Showing 12 changed files with 217 additions and 17 deletions.
diff --git a/aes-ctr/src/lib.rs b/aes-ctr/src/lib.rs
@@ -9,8 +9,8 @@
 //! it either by using `RUSTFLAGS="-C target-feature=+aes,+ssse3"` or by editing
 //! your `.cargo/config`. (`sse2` target feature is usually enabled by default)
 //!
-//! # Warning
-//! This crate does not provide any authentification! Thus ciphertext integrity
+//! # Security Warning
+//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
 //! is not verified, which can lead to serious vulnerabilities!
 //!
 //! # Usage example

diff --git a/cfb-mode/src/lib.rs b/cfb-mode/src/lib.rs
@@ -2,8 +2,8 @@
 //!
 //! This crate implements CFB as a [self-synchronizing stream cipher][2].
 //!
-//! # Warning
-//! This crate does not provide any authentification! Thus ciphertext integrity
+//! # Security Warning
+//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
 //! is not verified, which can lead to serious vulnerabilities!
 //!
 //! # Examples

diff --git a/cfb8/src/lib.rs b/cfb8/src/lib.rs
@@ -2,8 +2,8 @@
 //!
 //! This crate implements CFB8 as a [self-synchronizing stream cipher][2].
 //!
-//! # Warning
-//! This crate does not provide any authentification! Thus ciphertext integrity
+//! # Security Warning
+//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
 //! is not verified, which can lead to serious vulnerabilities!
 //!
 //! # Examples

diff --git a/chacha20/Cargo.toml b/chacha20/Cargo.toml
@@ -7,6 +7,7 @@ description = "Chacha20 Stream Cipher"
 repository = "https://github.com/RustCrypto/stream-ciphers"
 keywords = ["crypto", "stream-cipher", "xchacha20"]
 categories = ["cryptography", "no-std"]
+readme = "README.md"
 
 [dependencies]
 block-cipher-trait = "0.6"

diff --git a/chacha20/README.md b/chacha20/README.md
@@ -0,0 +1,58 @@
+# ChaCha20
+
+[![crate][crate-image]][crate-link]
+[![Docs][docs-image]][docs-link]
+![Apache2/MIT licensed][license-image]
+![Rust Version][rustc-image]
+[![Build Status][build-image]][build-link]
+
+[ChaCha20][1] is a [stream cipher][2] which is designed to support
+high-performance software implementations.
+
+It improves upon the previous [Salsa20][3] stream cipher with increased
+per-round diffusion at no cost to performance.
+
+[Documentation][docs-link]
+
+## Security Warning
+
+This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
+is not verified, which can lead to serious vulnerabilities!
+
+No security audits of this crate have ever been performed, and it has not been
+thoroughly assessed to ensure its operation is constant-time on common CPU
+architectures.
+
+USE AT YOUR OWN RISK!
+
+## License
+
+Licensed under either of:
+
+ * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+ * [MIT license](http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.
+
+[//]: # (badges)
+
+[crate-image]: https://img.shields.io/crates/v/chacha20.svg
+[crate-link]: https://crates.io/crates/chacha20
+[docs-image]: https://docs.rs/chacha20/badge.svg
+[docs-link]: https://docs.rs/chacha20/
+[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
+[rustc-image]: https://img.shields.io/badge/rustc-1.27+-blue.svg
+[build-image]: https://travis-ci.org/RustCrypto/stream-ciphers.svg?branch=master
+[build-link]: https://travis-ci.org/RustCrypto/stream-ciphers
+
+[//]: # (general links)
+
+[1]: https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant
+[2]: https://en.wikipedia.org/wiki/Stream_cipher
+[3]: https://en.wikipedia.org/wiki/Salsa20
diff --git a/chacha20/src/lib.rs b/chacha20/src/lib.rs
@@ -1,12 +1,58 @@
-//! The ChaCha20 stream cipher
+//! The ChaCha20 stream cipher.
+//!
+//! ChaCha20 is an improvement upon the previous [Salsa20] stream cipher,
+//! with increased per-round diffusion at no cost to performance.
+//!
+//! Cipher functionality is accessed using traits from re-exported
+//! [`stream-cipher`](https://docs.rs/stream-cipher) crate.
+//!
+//! This crate contains three variants of ChaCha20:
+//!
+//! - `ChaCha20`: standard IETF variant with 96-bit nonce
+//! - `ChaCha20Legacy`: (gated under the `legacy` feature) "djb" variant iwth 64-bit nonce
+//! - `XChaCha20`: (gated under the `xchacha20` feature) 192-bit extended nonce variant
+//!
+//! # Security Warning
+//!
+//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
+//! is not verified, which can lead to serious vulnerabilities!
+//!
+//! # Usage
+//!
+//! ```
+//! use chacha20::ChaCha20;
+//! use chacha20::stream_cipher::generic_array::GenericArray;
+//! use chacha20::stream_cipher::{NewStreamCipher, StreamCipher};
+//!
+//! let mut data = [1, 2, 3, 4, 5, 6, 7];
+//!
+//! let key = GenericArray::from_slice(b"an example very very secret key.");
+//! let nonce = GenericArray::from_slice(b"secret nonce");
+//!
+//! // create cipher instance
+//! let mut cipher = ChaCha20::new(&key, &nonce);
+//!
+//! // encrypt data
+//! cipher.encrypt(&mut data);
+//! assert_eq!(data, [73, 98, 234, 202, 73, 143, 0]);
+//!
+//! // (re)create cipher instance
+//! let mut cipher = ChaCha20::new(&key, &nonce);
+//!
+//! // decrypt data
+//! cipher.decrypt(&mut data);
+//! assert_eq!(data, [1, 2, 3, 4, 5, 6, 7]);
+//! ```
+//!
+//! [Salsa20]: https://docs.rs/salsa20
 
 #![no_std]
 #![deny(missing_docs)]
 
+pub extern crate stream_cipher;
+
 extern crate block_cipher_trait;
 extern crate salsa20_core;
-extern crate stream_cipher;
-
 // TODO: replace with `u32::from_le_bytes`/`to_le_bytes` in libcore (1.32+)
 #[cfg(feature = "xchacha20")]
 extern crate byteorder;

diff --git a/ctr/src/lib.rs b/ctr/src/lib.rs
@@ -3,8 +3,8 @@
 //! Mode functionality is accessed using traits from re-exported
 //! [`stream-cipher`](https://docs.rs/stream-cipher) crate.
 //!
-//! # Warning
-//! This crate does not provide any authentification! Thus ciphertext integrity
+//! # Security Warning
+//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
 //! is not verified, which can lead to serious vulnerabilities!
 //!
 //! # Usage example

diff --git a/ofb/src/lib.rs b/ofb/src/lib.rs
@@ -2,8 +2,8 @@
 //!
 //! This crate implements OFB as a [synchronous stream cipher][2].
 //!
-//! # Warning
-//! This crate does not provide any authentification! Thus ciphertext integrity
+//! # Security Warning
+//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
 //! is not verified, which can lead to serious vulnerabilities!
 //!
 //! # Examples

diff --git a/salsa20-core/src/lib.rs b/salsa20-core/src/lib.rs
@@ -1,5 +1,8 @@
-//! Shared functionality common to ciphers in the Salsa20 Family, i.e.
-//! Salsa20 and ChaCha20
+//! Shared functionality common to ciphers in the Salsa20 Family
+//! (i.e. Salsa20 and ChaCha20)
+//!
+//! This crate isn't designed to be used directly, but is instead an
+//! implementation detail fo the `salsa20` and `chacha20` crates.
 
 #![no_std]
 #![deny(missing_docs)]

diff --git a/salsa20/Cargo.toml b/salsa20/Cargo.toml
@@ -7,6 +7,7 @@ description = "Salsa20 Stream Cipher"
 repository = "https://github.com/RustCrypto/stream-ciphers"
 keywords = ["crypto", "stream-cipher", "trait"]
 categories = ["cryptography", "no-std"]
+readme = "README.md"
 
 [dependencies]
 block-cipher-trait = "0.6"

diff --git a/salsa20/README.md b/salsa20/README.md
@@ -0,0 +1,55 @@
+# Salsa20
+
+[![crate][crate-image]][crate-link]
+[![Docs][docs-image]][docs-link]
+![Apache2/MIT licensed][license-image]
+![Rust Version][rustc-image]
+[![Build Status][build-image]][build-link]
+
+[Salsa20][1] is a [stream cipher][2] which is designed to support
+high-performance software implementations.
+
+[Documentation][docs-link]
+
+## Security Warning
+
+This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
+is not verified, which can lead to serious vulnerabilities!
+
+No security audits of this crate have ever been performed, and it has not been
+thoroughly assessed to ensure its operation is constant-time on common CPU
+architectures.
+
+USE AT YOUR OWN RISK!
+
+## License
+
+Licensed under either of:
+
+ * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+ * [MIT license](http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.
+
+[//]: # (badges)
+
+[crate-image]: https://img.shields.io/crates/v/salsa20.svg
+[crate-link]: https://crates.io/crates/salsa20
+[docs-image]: https://docs.rs/salsa20/badge.svg
+[docs-link]: https://docs.rs/salsa20/
+[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
+[rustc-image]: https://img.shields.io/badge/rustc-1.27+-blue.svg
+[build-image]: https://travis-ci.org/RustCrypto/stream-ciphers.svg?branch=master
+[build-link]: https://travis-ci.org/RustCrypto/stream-ciphers
+
+[//]: # (general links)
+
+[1]: https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant
+[2]: https://en.wikipedia.org/wiki/Stream_cipher
+[3]: https://en.wikipedia.org/wiki/Salsa20
diff --git a/salsa20/src/lib.rs b/salsa20/src/lib.rs
@@ -1,11 +1,47 @@
-//! The Salsa20 stream cipher
+//! The Salsa20 stream cipher.
+//!
+//! Cipher functionality is accessed using traits from re-exported
+//! [`stream-cipher`](https://docs.rs/stream-cipher) crate.
+//!
+//! # Security Warning
+//!
+//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
+//! is not verified, which can lead to serious vulnerabilities!
+//!
+//! # Usage
+//!
+//! ```
+//! use salsa20::Salsa20;
+//! use salsa20::stream_cipher::generic_array::GenericArray;
+//! use salsa20::stream_cipher::{NewStreamCipher, StreamCipher};
+//!
+//! let mut data = [1, 2, 3, 4, 5, 6, 7];
+//!
+//! let key = GenericArray::from_slice(b"an example very very secret key.");
+//! let nonce = GenericArray::from_slice(b"a nonce.");
+//!
+//! // create cipher instance
+//! let mut cipher = Salsa20::new(&key, &nonce);
+//!
+//! // encrypt data
+//! cipher.encrypt(&mut data);
+//! assert_eq!(data, [182, 14, 133, 113, 210, 25, 165]);
+//!
+//! // (re)create cipher instance
+//! let mut cipher = Salsa20::new(&key, &nonce);
+//!
+//! // decrypt data
+//! cipher.decrypt(&mut data);
+//! assert_eq!(data, [1, 2, 3, 4, 5, 6, 7]);
+//! ```
 
 #![no_std]
 #![deny(missing_docs)]
 
+pub extern crate stream_cipher;
+
 extern crate block_cipher_trait;
 extern crate salsa20_core;
-extern crate stream_cipher;
 
 #[cfg(feature = "zeroize")]
 extern crate zeroize;