Merge pull request #51 from RustCrypto/heapless

Add a `heapless` feature to all crates + docs to use it

.travis.yml

@@ -6,7 +6,7 @@ rust:
   - nightly
 
 script:
-  - cargo test --all --release
+  - cargo test --all --release --lib
   - cargo test --all --all-features --release
 
 env:

aes-gcm-siv/Cargo.toml

@@ -32,6 +32,10 @@ criterion-cycles-per-byte = "0.1.1"
 [features]
 default = ["alloc"]
 alloc = ["aead/alloc"]
+heapless = ["aead/heapless"]
+
+[package.metadata.docs.rs]
+all-features = true
 
 [[bench]]
 name = "aes-gcm-siv"

aes-gcm-siv/src/lib.rs

@@ -40,6 +40,8 @@
 //!
 //! # Usage
 //!
+//! Simple usage (allocating, no associated data):
+//!
 //! ```
 //! use aes_gcm_siv::Aes256GcmSiv; // Or `Aes128GcmSiv`
 //! use aead::{Aead, NewAead, generic_array::GenericArray};
@@ -62,22 +64,35 @@
 //! methods accept any type that impls the [`aead::Buffer`][9] trait which
 //! contains the plaintext for encryption or ciphertext for decryption.
 //!
-//! Note that if you enable the `heapless` feature of the `aead` crate,
-//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][10]
-//! type, which can then be passed as the `buffer` parameter to the
-//! in-place encrypt and decrypt methods.
+//! Note that if you enable the `heapless` feature of this crate,
+//! you will receive an impl of `aead::Buffer` for [`heapless::Vec`][10]
+//! (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:
+//!
+//! ```
+//! use aes_gcm_siv::Aes256GcmSiv; // Or `Aes128GcmSiv`
+//! use aead::{Aead, NewAead};
+//! use aead::generic_array::{GenericArray, typenum::U128};
+//! use aead::heapless::Vec;
+//!
+//! let key = GenericArray::clone_from_slice(b"an example very very secret key.");
+//! let aead = Aes256GcmSiv::new(key);
+//!
+//! let nonce = GenericArray::from_slice(b"unique nonce"); // 96-bits; unique per message
+//!
+//! let mut buffer: Vec<u8, U128> = Vec::new();
+//! buffer.extend_from_slice(b"plaintext message");
 //!
-//! In `Cargo.toml`, add:
+//! // Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
+//! aead.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");
 //!
-//! ```toml
-//! [dependencies.aead]
-//! version = "0.2"
-//! default-features = false
-//! features = ["heapless"]
+//! // `buffer` now contains the message ciphertext
+//! assert_ne!(&buffer, b"plaintext message");
 //!
-//! [dependencies.aes-gcm-siv]
-//! version = "0.2"
-//! default-features = false
+//! // Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
+//! aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
+//! assert_eq!(&buffer, b"plaintext message");
 //! ```
 //!
 //! [1]: https://en.wikipedia.org/wiki/AES-GCM-SIV

aes-gcm/Cargo.toml

@@ -33,6 +33,10 @@ hex-literal = "0.2"
 [features]
 default = ["alloc"]
 alloc = ["aead/alloc"]
+heapless = ["aead/heapless"]
+
+[package.metadata.docs.rs]
+all-features = true
 
 [[bench]]
 name = "aes-gcm"

aes-gcm/src/lib.rs

@@ -26,6 +26,8 @@
 //!
 //! # Usage
 //!
+//! Simple usage (allocating, no associated data):
+//!
 //! ```
 //! use aes_gcm::Aes256Gcm; // Or `Aes128Gcm`
 //! use aead::{Aead, NewAead, generic_array::GenericArray};
@@ -48,22 +50,35 @@
 //! methods accept any type that impls the [`aead::Buffer`][5] trait which
 //! contains the plaintext for encryption or ciphertext for decryption.
 //!
-//! Note that if you enable the `heapless` feature of the `aead` crate,
-//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][6]
-//! type, which can then be passed as the `buffer` parameter to the
-//! in-place encrypt and decrypt methods.
+//! Note that if you enable the `heapless` feature of this crate,
+//! you will receive an impl of `aead::Buffer` for [`heapless::Vec`][6]
+//! (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:
+//!
+//! ```
+//! use aes_gcm::Aes256Gcm; // Or `Aes128Gcm`
+//! use aead::{Aead, NewAead};
+//! use aead::generic_array::{GenericArray, typenum::U128};
+//! use aead::heapless::Vec;
+//!
+//! let key = GenericArray::clone_from_slice(b"an example very very secret key.");
+//! let aead = Aes256Gcm::new(key);
+//!
+//! let nonce = GenericArray::from_slice(b"unique nonce"); // 96-bits; unique per message
+//!
+//! let mut buffer: Vec<u8, U128> = Vec::new();
+//! buffer.extend_from_slice(b"plaintext message");
 //!
-//! In `Cargo.toml`, add:
+//! // Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
+//! aead.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");
 //!
-//! ```toml
-//! [dependencies.aead]
-//! version = "0.2"
-//! default-features = false
-//! features = ["heapless"]
+//! // `buffer` now contains the message ciphertext
+//! assert_ne!(&buffer, b"plaintext message");
 //!
-//! [dependencies.aes-gcm]
-//! version = "0.2"
-//! default-features = false
+//! // Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
+//! aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
+//! assert_eq!(&buffer, b"plaintext message");
 //! ```
 //!
 //! [1]: https://en.wikipedia.org/wiki/Authenticated_encryption

aes-siv/Cargo.toml

@@ -35,6 +35,7 @@ hex-literal = "0.2"
 [features]
 default = ["alloc"]
 alloc = ["aead/alloc"]
+heapless = ["aead/heapless"]
 
 [package.metadata.docs.rs]
 all-features = true

aes-siv/src/lib.rs

@@ -2,6 +2,22 @@
 //! [Authenticated Encryption with Associated Data (AEAD)][3] cipher which also
 //! provides [nonce reuse misuse resistance][4].
 //!
+//! # Usage
+//!
+//! Simple usage (allocating, no associated data):
+//!
+//! ```
+//! use aes_siv::Aes128SivAead; // Or `Aes256Siv`
+//! use aead::{Aead, NewAead, generic_array::GenericArray};
+//!
+//! let key = GenericArray::clone_from_slice(b"an example very very secret key.");
+//! let aead = Aes128SivAead::new(key);
+//!
+//! let nonce = GenericArray::from_slice(b"any unique nonce"); // 128-bits; unique per message
+//! let ciphertext = aead.encrypt(nonce, b"plaintext message".as_ref()).expect("encryption failure!");
+//! let plaintext = aead.decrypt(nonce, ciphertext.as_ref()).expect("decryption failure!");
+//! assert_eq!(&plaintext, b"plaintext message");
+//! ```
 //!
 //! ## In-place Usage (eliminates `alloc` requirement)
 //!
@@ -12,22 +28,35 @@
 //! 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 the `aead` crate,
-//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][8]
-//! type, which can then be passed as the `buffer` parameter to the
-//! in-place encrypt and decrypt methods.
+//! Note that if you enable the `heapless` feature of this crate,
+//! 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:
+//!
+//! ```
+//! use aes_siv::Aes128SivAead; // Or `Aes256SivAead`
+//! use aead::{Aead, NewAead};
+//! use aead::generic_array::{GenericArray, typenum::U128};
+//! use aead::heapless::Vec;
+//!
+//! let key = GenericArray::clone_from_slice(b"an example very very secret key.");
+//! let aead = Aes128SivAead::new(key);
+//!
+//! let nonce = GenericArray::from_slice(b"any unique nonce"); // 128-bits; unique per message
+//!
+//! let mut buffer: Vec<u8, U128> = Vec::new();
+//! buffer.extend_from_slice(b"plaintext message");
 //!
-//! In `Cargo.toml`, add:
+//! // Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
+//! aead.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");
 //!
-//! ```toml
-//! [dependencies.aead]
-//! version = "0.2"
-//! default-features = false
-//! features = ["heapless"]
+//! // `buffer` now contains the message ciphertext
+//! assert_ne!(&buffer, b"plaintext message");
 //!
-//! [dependencies.aes-siv]
-//! version = "0.2"
-//! default-features = false
+//! // Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
+//! aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
+//! assert_eq!(&buffer, b"plaintext message");
 //! ```
 //!
 //! [1]: https://github.com/miscreant/meta/wiki/AES-SIV

chacha20poly1305/Cargo.toml

@@ -27,4 +27,8 @@ zeroize = { version = "1", default-features = false }
 [features]
 default = ["alloc", "xchacha20poly1305"]
 alloc = ["aead/alloc"]
+heapless = ["aead/heapless"]
 xchacha20poly1305 = ["chacha20/xchacha20"]
+
+[package.metadata.docs.rs]
+all-features = true

chacha20poly1305/src/lib.rs

@@ -20,7 +20,7 @@
 //! # Usage
 //!
 //! ```
-//! use chacha20poly1305::ChaCha20Poly1305;
+//! use chacha20poly1305::ChaCha20Poly1305; // Or `XChaCha20Poly1305`
 //! use aead::{Aead, NewAead, generic_array::GenericArray};
 //!
 //! let key = GenericArray::clone_from_slice(b"an example very very secret key."); // 32-bytes
@@ -41,22 +41,35 @@
 //! 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 the `aead` crate,
-//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][8]
-//! type, which can then be passed as the `buffer` parameter to the
-//! in-place encrypt and decrypt methods.
+//! Note that if you enable the `heapless` feature of this crate,
+//! 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:
 //!
-//! In `Cargo.toml`, add:
+//! ```
+//! use chacha20poly1305::ChaCha20Poly1305; // Or `XChaCha20Poly1305`
+//! use aead::{Aead, NewAead};
+//! use aead::generic_array::{GenericArray, typenum::U128};
+//! use aead::heapless::Vec;
+//!
+//! let key = GenericArray::clone_from_slice(b"an example very very secret key.");
+//! let aead = ChaCha20Poly1305::new(key);
+//!
+//! let nonce = GenericArray::from_slice(b"unique nonce"); // 128-bits; unique per message
+//!
+//! let mut buffer: Vec<u8, U128> = Vec::new();
+//! buffer.extend_from_slice(b"plaintext message");
+//!
+//! // Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
+//! aead.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");
 //!
-//! ```toml
-//! [dependencies.aead]
-//! version = "0.2"
-//! default-features = false
-//! features = ["heapless"]
+//! // `buffer` now contains the message ciphertext
+//! assert_ne!(&buffer, b"plaintext message");
 //!
-//! [dependencies.chacha20poly1305]
-//! version = "0.2"
-//! default-features = false
+//! // Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
+//! aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
+//! assert_eq!(&buffer, b"plaintext message");
 //! ```
 //!
 //! [1]: https://tools.ietf.org/html/rfc8439

xsalsa20poly1305/Cargo.toml

@@ -26,3 +26,7 @@ zeroize = { version = "1", default-features = false }
 [features]
 default = ["alloc"]
 alloc = ["aead/alloc"]
+heapless = ["aead/heapless"]
+
+[package.metadata.docs.rs]
+all-features = true

xsalsa20poly1305/src/lib.rs

@@ -43,22 +43,35 @@
 //! methods accept any type that impls the [`aead::Buffer`][5] trait which
 //! contains the plaintext for encryption or ciphertext for decryption.
 //!
-//! Note that if you enable the `heapless` feature of the `aead` crate,
-//! you will receive an impl of `aead::Buffer` for the [`heapless::Vec`][6]
-//! type, which can then be passed as the `buffer` parameter to the
-//! in-place encrypt and decrypt methods.
+//! Note that if you enable the `heapless` feature of this crate,
+//! 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:
 //!
-//! In `Cargo.toml`, add:
+//! ```
+//! use xsalsa20poly1305::XSalsa20Poly1305;
+//! use aead::{Aead, NewAead};
+//! use aead::generic_array::{GenericArray, typenum::U128};
+//! use aead::heapless::Vec;
+//!
+//! let key = GenericArray::clone_from_slice(b"an example very very secret key.");
+//! let aead = XSalsa20Poly1305::new(key);
+//!
+//! let nonce = GenericArray::from_slice(b"extra long unique nonce!"); // 24-bytes; unique
+//!
+//! let mut buffer: Vec<u8, U128> = Vec::new();
+//! buffer.extend_from_slice(b"plaintext message");
+//!
+//! // Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
+//! aead.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");
 //!
-//! ```toml
-//! [dependencies.aead]
-//! version = "0.2"
-//! default-features = false
-//! features = ["heapless"]
+//! // `buffer` now contains the message ciphertext
+//! assert_ne!(&buffer, b"plaintext message");
 //!
-//! [dependencies.xsalsa20poly1305]
-//! version = "0.2"
-//! default-features = false
+//! // Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
+//! aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
+//! assert_eq!(&buffer, b"plaintext message");
 //! ```
 //!
 //! [1]: https://nacl.cr.yp.to/secretbox.html