diff --git a/aes-ctr/src/lib.rs b/aes-ctr/src/lib.rs index 9f77ec6f..ba15ebdb 100644 --- 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 index 28f49026..7268dbde 100644 --- 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 index 8e88d95c..c0136147 100644 --- 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 index 4772498f..e0ccb9ce 100644 --- 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 new file mode 100644 index 00000000..328a48f8 --- /dev/null +++ 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 index de02d5be..3d3a3165 100644 --- 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 index ca191165..8267ad43 100644 --- 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 index 0ab51fb9..52428ecf 100644 --- 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 index 4f60ad58..9f3ee933 100644 --- 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 index 16f24ccd..d859d3f7 100644 --- 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 new file mode 100644 index 00000000..c22e6891 --- /dev/null +++ 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 index b9f7674e..1ba35b65 100644 --- 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;