aes-gcm/chacha20poly1305: add NCC audit notes to doc

Updates the README.md files and crate documentation for the `aes-gcm`
and `chacha20poly1305` crates to reflect the NCC audit findings:

https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/

aes-gcm/Cargo.toml

@@ -16,7 +16,7 @@ keywords = ["aead", "aes", "encryption", "gcm", "ghash"]
 categories = ["cryptography", "no-std"]
 
 [badges]
-maintenance = { status = "experimental" }
+maintenance = { status = "actively-maintained" }
 
 [dependencies]
 aead = { version = "0.2", default-features = false }

aes-gcm/README.md

@@ -1,24 +1,22 @@
-# AES-GCM
-
-[![crate][crate-image]][crate-link]
-[![Docs][docs-image]][docs-link]
-![Apache2/MIT licensed][license-image]
-![Rust Version][rustc-image]
-![Maintenance Status: Experimental][maintenance-image]
-[![Build Status][build-image]][build-link]
+# AES-GCM [![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]
 
 Pure Rust implementation of the AES-GCM
 [Authenticated Encryption with Associated Data (AEAD)][1] cipher.
 
 [Documentation][docs-link]
 
-## Security Warning
+## Security Notes
+
+This crate has received one [audit security by NCC Group][2], with no significant
+findings. We would like to thank [MobileCoin][3] for funding the audit.
 
-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.
+All implementations contained in the crate are designed to execute in constant
+time, either by relying on hardware intrinsics (i.e. AES-NI and CLMUL on
+x86/x86_64), or using a portable implementation which is only constant time
+on processors which implement constant-time multiplication.
 
-USE AT YOUR OWN RISK!
+It is not suitable for use on processors with a variable-time multiplication
+operation (e.g. short circuit on multiply-by-zero / multiply-by-one).
 
 ## License
 
@@ -43,10 +41,11 @@ dual licensed as above, without any additional terms or conditions.
 [docs-link]: https://docs.rs/aes-gcm/
 [license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
 [rustc-image]: https://img.shields.io/badge/rustc-1.37+-blue.svg
-[maintenance-image]: https://img.shields.io/badge/maintenance-experimental-blue.svg
 [build-image]: https://travis-ci.com/RustCrypto/AEADs.svg?branch=master
 [build-link]: https://travis-ci.com/RustCrypto/AEADs
 
 [//]: # (general links)
 
 [1]: https://en.wikipedia.org/wiki/Authenticated_encryption
+[2]: https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/
+[3]: https://www.mobilecoin.com/

aes-gcm/src/lib.rs

@@ -13,16 +13,18 @@
 //! RUSTFLAGS="-Ctarget-cpu=sandybridge -Ctarget-feature=+aes,+sse2,+sse4.1,+ssse3"
 //! ```
 //!
-//! ## Security Warning
+//! ## Security Notes
 //!
-//! 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.
+//! This crate has received one [audit security by NCC Group][3], with no significant
+//! findings. We would like to thank [MobileCoin][4] for funding the audit.
 //!
-//! Where possible the implementation uses constant-time hardware intrinsics,
-//! or otherwise falls back to an implementation which contains no secret-dependent
-//! branches or table lookups, however it's possible LLVM may insert such
-//! operations in certain scenarios.
+//! All implementations contained in the crate are designed to execute in constant
+//! time, either by relying on hardware intrinsics (i.e. AES-NI and CLMUL on
+//! x86/x86_64), or using a portable implementation which is only constant time
+//! on processors which implement constant-time multiplication.
+//!
+//! It is not suitable for use on processors with a variable-time multiplication
+//! operation (e.g. short circuit on multiply-by-zero / multiply-by-one).
 //!
 //! # Usage
 //!
@@ -46,12 +48,12 @@
 //! This crate has an optional `alloc` feature which can be disabled in e.g.
 //! microcontroller environments that don't have a heap.
 //!
-//! The [`Aead::encrypt_in_place`][3] and [`Aead::decrypt_in_place`][4]
-//! methods accept any type that impls the [`aead::Buffer`][5] trait which
+//! The [`Aead::encrypt_in_place`][5] and [`Aead::decrypt_in_place`][6]
+//! methods accept any type that impls the [`aead::Buffer`][7] trait which
 //! contains the plaintext for encryption or ciphertext for decryption.
 //!
 //! Note that if you enable the `heapless` feature of this crate,
-//! you will receive an impl of `aead::Buffer` for [`heapless::Vec`][6]
+//! you will receive an impl of `aead::Buffer` for [`heapless::Vec`][8]
 //! (re-exported from the `aead` crate as `aead::heapless::Vec`),
 //! which can then be passed as the `buffer` parameter to the in-place encrypt
 //! and decrypt methods:
@@ -83,10 +85,12 @@
 //!
 //! [1]: https://en.wikipedia.org/wiki/Authenticated_encryption
 //! [2]: https://en.wikipedia.org/wiki/Galois/Counter_Mode
-//! [3]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place
-//! [4]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place
-//! [5]: https://docs.rs/aead/latest/aead/trait.Buffer.html
-//! [6]: https://docs.rs/heapless/latest/heapless/struct.Vec.html
+//! [3]: https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/
+//! [4]: https://www.mobilecoin.com/
+//! [5]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place
+//! [6]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place
+//! [7]: https://docs.rs/aead/latest/aead/trait.Buffer.html
+//! [8]: https://docs.rs/heapless/latest/heapless/struct.Vec.html
 
 #![no_std]
 #![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]
@@ -173,6 +177,7 @@ where
         }
 
         // TODO(tarcieri): interleave encryption with GHASH
+        // See: <https://github.com/RustCrypto/AEADs/issues/74>
         let mut ctr = Ctr32::new(&self.cipher, nonce);
         ctr.seek(1);
         ctr.apply_keystream(buffer);
@@ -195,7 +200,8 @@ where
             return Err(Error);
         }
 
-        // TODO(tarcieri): interleave decryption with GHASH
+        // TODO(tarcieri): interleave encryption with GHASH
+        // See: <https://github.com/RustCrypto/AEADs/issues/74>
         let mut expected_tag = compute_tag(&mut self.ghash.clone(), associated_data, buffer);
         let mut ctr = Ctr32::new(&self.cipher, nonce);
         ctr.apply_keystream(expected_tag.as_mut_slice());

chacha20poly1305/Cargo.toml

@@ -18,7 +18,7 @@ keywords = ["aead", "chacha20", "poly1305", "xchacha20", "xchacha20poly1305"]
 categories = ["cryptography", "no-std"]
 
 [badges]
-maintenance = { status = "passively-maintained" }
+maintenance = { status = "actively-maintained" }
 
 [dependencies]
 aead = { version = "0.2", default-features = false }

chacha20poly1305/README.md

@@ -1,27 +1,27 @@
-# ChaCha20Poly1305: Authenticated Encryption Cipher
+# ChaCha20Poly1305 [![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]
 
-[![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]
-
-**ChaCha20Poly1305** ([RFC 8439][1]) is an [Authenticated Encryption with Associated Data (AEAD)][2]
-cipher amenable to fast, constant-time implementations in software, based on
-the [ChaCha20][3] stream cipher and [Poly1305][4] universal hash function.
+Pure Rust implementation of **ChaCha20Poly1305** ([RFC 8439][1]): an
+[Authenticated Encryption with Associated Data (AEAD)][2] cipher amenable to
+fast, constant-time implementations in software, based on the [ChaCha20][3]
+stream cipher and [Poly1305][4] universal hash function.
 
 This crate also contains an implementation of **XChaCha20Poly1305**: a variant
 of ChaCha20Poly1305 with an extended 192-bit (24-byte) nonce.
 
 [Documentation][docs-link]
 
-## Security Warning
+## Security Notes
+
+This crate has received one [audit security by NCC Group][5], with no significant
+findings. We would like to thank [MobileCoin][6] for funding the audit.
 
-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.
+All implementations contained in the crate are designed to execute in constant
+time, either by relying on hardware intrinsics (i.e. AVX2 on x86/x86_64), or
+using a portable implementation which is only constant time on processors which
+implement constant-time multiplication.
 
-USE AT YOUR OWN RISK!
+It is not suitable for use on processors with a variable-time multiplication
+operation (e.g. short circuit on multiply-by-zero / multiply-by-one).
 
 ## License
 
@@ -55,3 +55,5 @@ dual licensed as above, without any additional terms or conditions.
 [2]: https://en.wikipedia.org/wiki/Authenticated_encryption
 [3]: https://github.com/RustCrypto/stream-ciphers/tree/master/chacha20
 [4]: https://github.com/RustCrypto/universal-hashes/tree/master/poly1305
+[5]: https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/
+[6]: https://www.mobilecoin.com/

chacha20poly1305/src/cipher.rs

@@ -46,8 +46,12 @@ where
         }
 
         self.mac.update_padded(associated_data);
+
+        // TODO(tarcieri): interleave encryption with Poly1305
+        // See: <https://github.com/RustCrypto/AEADs/issues/74>
         self.cipher.apply_keystream(buffer);
         self.mac.update_padded(buffer);
+
         self.authenticate_lengths(associated_data, buffer)?;
         Ok(self.mac.result().into_bytes())
     }
@@ -70,6 +74,8 @@ where
 
         // This performs a constant-time comparison using the `subtle` crate
         if self.mac.verify(tag).is_ok() {
+            // TODO(tarcieri): interleave decryption with Poly1305
+            // See: <https://github.com/RustCrypto/AEADs/issues/74>
             self.cipher.apply_keystream(buffer);
             Ok(())
         } else {

chacha20poly1305/src/lib.rs

@@ -3,7 +3,9 @@
 //! cipher amenable to fast, constant-time implementations in software, based on
 //! the [ChaCha20][3] stream cipher and [Poly1305][4] universal hash function.
 //!
-//! This crate also contains the following `ChaCha20Poly1305` variants:
+//! This crate contains pure Rust implementations of `ChaCha20Poly1305`
+//! (with optional AVX2 acceleration) as well as the following variants thereof:
+//!
 //! - [`XChaCha20Poly1305`] - ChaCha20Poly1305 variant with an extended 192-bit (24-byte) nonce.
 //! - [`ChaCha8Poly1305`] / [`ChaCha12Poly1305`] - nonstandard, reduced round variants
 //!   (gated under the `reduced-round` Cargo feature). See the [Too Much Crypto][5]
@@ -28,16 +30,18 @@
 //! RUSTFLAGS="-Ctarget-cpu=haswell -Ctarget-feature=+avx2"
 //! ```
 //!
-//! ## Security Warning
+//! ## Security Notes
+//!
+//! This crate has received one [audit security by NCC Group][6], with no significant
+//! findings. We would like to thank [MobileCoin][7] for funding the audit.
 //!
-//! 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.
+//! All implementations contained in the crate are designed to execute in
+//! constant time, either by relying on hardware intrinsics (i.e. AVX2 on
+//! x86/x86_64), or using a portable implementation which is only constant time
+//! on processors which implement constant-time multiplication.
 //!
-//! Where possible the implementation uses constant-time hardware intrinsics,
-//! or otherwise falls back to an implementation which contains no secret-dependent
-//! branches or table lookups, however it's possible LLVM may insert such
-//! operations in certain scenarios.
+//! It is not suitable for use on processors with a variable-time multiplication
+//! operation (e.g. short circuit on multiply-by-zero / multiply-by-one).
 //!
 //! # Usage
 //!
@@ -59,12 +63,12 @@
 //! This crate has an optional `alloc` feature which can be disabled in e.g.
 //! microcontroller environments that don't have a heap.
 //!
-//! The [`Aead::encrypt_in_place`][6] and [`Aead::decrypt_in_place`][7]
-//! methods accept any type that impls the [`aead::Buffer`][8] trait which
+//! The [`Aead::encrypt_in_place`][8] and [`Aead::decrypt_in_place`][9]
+//! methods accept any type that impls the [`aead::Buffer`][10] trait which
 //! contains the plaintext for encryption or ciphertext for decryption.
 //!
 //! Note that if you enable the `heapless` feature of this crate,
-//! you will receive an impl of `aead::Buffer` for [`heapless::Vec`][9]
+//! you will receive an impl of `aead::Buffer` for [`heapless::Vec`][11]
 //! (re-exported from the `aead` crate as `aead::heapless::Vec`),
 //! which can then be passed as the `buffer` parameter to the in-place encrypt
 //! and decrypt methods:
@@ -99,10 +103,12 @@
 //! [3]: https://github.com/RustCrypto/stream-ciphers/tree/master/chacha20
 //! [4]: https://github.com/RustCrypto/universal-hashes/tree/master/poly1305
 //! [5]: https://eprint.iacr.org/2019/1492.pdf
-//! [6]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place
-//! [7]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place
-//! [8]: https://docs.rs/aead/latest/aead/trait.Buffer.html
-//! [9]: https://docs.rs/heapless/latest/heapless/struct.Vec.html
+//! [6]: https://research.nccgroup.com/2020/02/26/public-report-rustcrypto-aes-gcm-and-chacha20poly1305-implementation-review/
+//! [7]: https://www.mobilecoin.com/
+//! [8]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place
+//! [9]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place
+//! [10]: https://docs.rs/aead/latest/aead/trait.Buffer.html
+//! [11]: https://docs.rs/heapless/latest/heapless/struct.Vec.html
 
 #![no_std]
 #![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]