Merge branch 'master' into feat-padding

README.md

@@ -55,6 +55,24 @@ Documentation will be generated in target/doc/...
 Most documentation is taken from NaCl, with minor modification where the API
 differs between the C and Rust versions.
 
+### Support for the AES AEAD Variant
+
+The AES AEAD variant `crypto_aead_aes256gcm` requires hardware support for the
+`AES` and `CLMUL` instruction set extensions to x86; you can read why that's the
+case
+[here](https://doc.libsodium.org/secret-key_cryptography/aead/aes-256-gcm#limitations). These instruction set extensions were first made
+available in Intel Westmere (early 2010) and at the time of writing x86 hardware
+support for them is near universal.
+
+Libsodium exposes an API for runtime feature detection and doesn't prevent
+you from calling `crypto_aead_aes256gcm` on a machine lacking `AES` and
+`CMUL` expressions; doing so will result in a runtime `SIGILL` (illegal
+instruction). By contrast sodiumoxide exposes an API that precludes the use of
+the `crypto_aead_aes256gcm_*` family of functions without performing the runtime
+check. It's important to note that the use of `sodiumoxide::init()` is mandatory
+when using AES; unless you call `init` calls `aead::aes256gcm::Aes256Gcm::new()`
+will always return `Err(_)` even if your runtime hardware supports AES.
+
 ## Dependencies
 
 C compiler (`cc`, `clang`, ...) must be installed in order to build libsodium from source.

src/crypto/aead/aead_macros.rs

@@ -4,7 +4,8 @@ macro_rules! aead_module (($seal_name:ident,
                            $open_detached_name:ident,
                            $keybytes:expr,
                            $noncebytes:expr,
-                           $tagbytes:expr) => (
+                           $tagbytes:expr,
+                           $test_gate:expr) => (
 
 #[cfg(not(feature = "std"))] use prelude::*;
 use libc::c_ulonglong;
@@ -166,6 +167,9 @@ mod test_m {
     #[test]
     fn test_seal_open() {
         use randombytes::randombytes;
+        if !$test_gate {
+          return
+        }
         for i in 0..256usize {
             let k = gen_key();
             let n = gen_random_nonce();
@@ -180,6 +184,9 @@ mod test_m {
     #[test]
     fn test_seal_open_tamper() {
         use randombytes::randombytes;
+        if !$test_gate {
+          return
+        }
         for i in 0..32usize {
             let k = gen_key();
             let n = gen_random_nonce();
@@ -204,6 +211,9 @@ mod test_m {
     #[test]
     fn test_seal_open_detached() {
         use randombytes::randombytes;
+        if !$test_gate {
+          return
+        }
         for i in 0..256usize {
             let k = gen_key();
             let n = gen_random_nonce();
@@ -219,6 +229,9 @@ mod test_m {
     #[test]
     fn test_seal_open_detached_tamper() {
         use randombytes::randombytes;
+        if !$test_gate {
+          return
+        }
         for i in 0..32usize {
             let k = gen_key();
             let n = gen_random_nonce();
@@ -249,6 +262,9 @@ mod test_m {
     #[test]
     fn test_seal_open_detached_same() {
         use randombytes::randombytes;
+        if !$test_gate {
+          return
+        }
         for i in 0..256usize {
             let k = gen_key();
             let n = gen_random_nonce();

src/crypto/aead/aes256gcm.rs

@@ -0,0 +1,235 @@
+//! WARNING: Despite being the most popular AEAD construction due to its use in
+//! TLS, safely using AES-GCM in a different context is tricky. No more than
+//! ~ 350 GB of input data should be encrypted with a given key. This is for
+//! ~ 16 KB messages - actual figures vary according to message sizes.
+//! In addition, nonces are short and repeated nonces would totally destroy the
+//! security of this scheme. Nonces should thus come from atomic counters,
+//! which can be difficult to set up in a distributed environment.
+//! Unless you absolutely need AES-GCM, use the
+//! [default AEAD export](crate::crypto::aead)
+//! instead - it doesn't have any of these limitations. Or, if you don't need
+//! to authenticate additional data, just stick to [secretbox](crate::crypto::secretbox).
+//!
+//! AES primitives will not be made available unless your runtime CPU
+//! is x86/x86_64 with support for the AES-NI instruction set and the CLMUL
+//! instruction (Westmere and beyond).
+
+mod aes_impl {
+    use ffi::{
+        crypto_aead_aes256gcm_ABYTES, crypto_aead_aes256gcm_KEYBYTES,
+        crypto_aead_aes256gcm_NPUBBYTES, crypto_aead_aes256gcm_decrypt,
+        crypto_aead_aes256gcm_decrypt_detached, crypto_aead_aes256gcm_encrypt,
+        crypto_aead_aes256gcm_encrypt_detached,
+    };
+
+    /// `is_available` returns true if the current CPU supports aes256gcm and false otherwise.
+    ///
+    /// WARNING: You must call [init](crate::init) before calling this function; if you do not
+    /// `is_available` will always return false even if the runtime supports aes256gcm.
+    pub fn is_available() -> bool {
+        unsafe { ffi::crypto_aead_aes256gcm_is_available() == 1 }
+    }
+
+    aead_module!(
+        crypto_aead_aes256gcm_encrypt,
+        crypto_aead_aes256gcm_decrypt,
+        crypto_aead_aes256gcm_encrypt_detached,
+        crypto_aead_aes256gcm_decrypt_detached,
+        crypto_aead_aes256gcm_KEYBYTES as usize,
+        crypto_aead_aes256gcm_NPUBBYTES as usize,
+        crypto_aead_aes256gcm_ABYTES as usize,
+        crate::init().is_ok() && is_available()
+    );
+
+    #[cfg(test)]
+    mod test {
+        use super::*;
+
+        #[test]
+        fn test_vector_1() {
+            // Test vector from https://tools.ietf.org/html/rfc7714#section-16.2.2
+            let m = &[
+                0x47, 0x61, 0x6c, 0x6c, 0x69, 0x61, 0x20, 0x65, 0x73, 0x74, 0x20, 0x6f, 0x6d, 0x6e,
+                0x69, 0x73, 0x20, 0x64, 0x69, 0x76, 0x69, 0x73, 0x61, 0x20, 0x69, 0x6e, 0x20, 0x70,
+                0x61, 0x72, 0x74, 0x65, 0x73, 0x20, 0x74, 0x72, 0x65, 0x73,
+            ];
+            let ad = &[
+                0x80, 0x40, 0xf1, 0x7b, 0x80, 0x41, 0xf8, 0xd3, 0x55, 0x01, 0xa0, 0xb2,
+            ];
+            let k = Key([
+                0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d,
+                0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
+                0x1c, 0x1d, 0x1e, 0x1f,
+            ]);
+            let n = Nonce([
+                0x51, 0x75, 0x3c, 0x65, 0x80, 0xc2, 0x72, 0x6f, 0x20, 0x71, 0x84, 0x14,
+            ]);
+            let c_expected = &[
+                0x32, 0xb1, 0xde, 0x78, 0xa8, 0x22, 0xfe, 0x12, 0xef, 0x9f, 0x78, 0xfa, 0x33, 0x2e,
+                0x33, 0xaa, 0xb1, 0x80, 0x12, 0x38, 0x9a, 0x58, 0xe2, 0xf3, 0xb5, 0x0b, 0x2a, 0x02,
+                0x76, 0xff, 0xae, 0x0f, 0x1b, 0xa6, 0x37, 0x99, 0xb8, 0x7b, 0x7a, 0xa3, 0xdb, 0x36,
+                0xdf, 0xff, 0xd6, 0xb0, 0xf9, 0xbb, 0x78, 0x78, 0xd7, 0xa7, 0x6c, 0x13,
+            ];
+            let c = seal(m, Some(ad), &n, &k);
+            assert_eq!(&c[..].len(), &c_expected[..].len());
+            assert_eq!(&c[0..44], &c_expected[0..44]);
+        }
+    }
+}
+
+mod aes_api {
+    use super::aes_impl;
+    use crypto::nonce::gen_random_nonce;
+
+    /// The Aes256Gcm struct encapsulates the crypto_aead_aes256gcm_* family of
+    /// functions in a way that ensures safe usage of the API at runtime
+    /// without incurring a per function call cost.
+    #[derive(Debug, Clone, Copy)]
+    pub struct Aes256Gcm;
+
+    impl Aes256Gcm {
+        /// Returns an `Ok` of [Aes256Gcm](self::Aes256Gcm) if the runtime
+        /// supports AES and an `Err(_)` if it does not.
+        ///
+        /// You must call [init](crate::init) before calling this function. Failure
+        /// to do so will result in `Err(_)` being returned even if the runtime
+        /// hardware supports AES.
+        pub fn new() -> Result<Self, ()> {
+            if unsafe { ffi::crypto_aead_aes256gcm_is_available() } == 1 {
+                Ok(Self)
+            } else {
+                Err(())
+            }
+        }
+
+        /// `gen_initial_nonce` randomly generates an initial nonce
+        ///
+        /// WARNING: AES nonces are short enough that the probability of collision between two randomly
+        /// generated nonces is nonnegligible and repeated nonce use will totally destroy the security
+        /// of this scheme. Use [increment_le]( aes_impl::Nonce::increment_le) or
+        /// [increment_le_inplace]( aes_impl::Nonce::increment_le_inplace) to increment a local nonce.
+        /// If you are operating in a multi threaded or distributed environment you must use a shared
+        /// atomic counter protocol instead.
+        ///
+        /// THREAD SAFETY: `gen_initial_nonce` is thread-safe provided that you have called
+        /// [init](crate::init) once before using any other function from sodiumoxide.
+        pub fn gen_initial_nonce(&self) -> aes_impl::Nonce {
+            gen_random_nonce()
+        }
+
+        /// `gen_key()` randomly generates a secret key
+        ///
+        /// THREAD SAFETY: `gen_key()` is thread-safe provided that you have
+        /// called `sodiumoxide::init()` once before using any other function
+        /// from sodiumoxide.
+        pub fn gen_key(&self) -> aes_impl::Key {
+            aes_impl::gen_key()
+        }
+
+        /// `open()` verifies and decrypts a ciphertext `c` together with optional plaintext data `ad`
+        /// using a secret key `k` and a nonce `n`.
+        /// It returns a plaintext `Ok(m)`.
+        /// If the ciphertext fails verification, `open()` returns `Err(())`.
+        pub fn open(
+            &self,
+            c: &[u8],
+            ad: Option<&[u8]>,
+            n: &aes_impl::Nonce,
+            k: &aes_impl::Key,
+        ) -> Result<Vec<u8>, ()> {
+            aes_impl::open(c, ad, n, k)
+        }
+
+        /// `open_detached()` verifies and decrypts a ciphertext `c` toghether with optional plaintext data
+        /// `ad` and and authentication tag `tag`, using a secret key `k` and a nonce `n`.
+        /// `c` is decrypted in place, so if this function is successful it will contain the plaintext.
+        /// If the ciphertext fails verification, `open_detached()` returns `Err(())`,
+        /// and the ciphertext is not modified.
+        pub fn open_detached(
+            &self,
+            c: &mut [u8],
+            ad: Option<&[u8]>,
+            t: &aes_impl::Tag,
+            n: &aes_impl::Nonce,
+            k: &aes_impl::Key,
+        ) -> Result<(), ()> {
+            aes_impl::open_detached(c, ad, t, n, k)
+        }
+
+        /// `seal()` encrypts and authenticates a message `m` together with optional plaintext data `ad`
+        /// using a secret key `k` and a nonce `n`. It returns a ciphertext `c`.
+        pub fn seal(
+            &self,
+            m: &[u8],
+            ad: Option<&[u8]>,
+            n: &aes_impl::Nonce,
+            k: &aes_impl::Key,
+        ) -> Vec<u8> {
+            aes_impl::seal(m, ad, n, k)
+        }
+
+        /// `seal_detached()` encrypts and authenticates a message `m` together with optional plaintext data
+        /// `ad` using a secret key `k` and a nonce `n`.
+        /// `m` is encrypted in place, so after this function returns it will contain the ciphertext.
+        /// The detached authentication tag is returned by value.
+        pub fn seal_detached(
+            &self,
+            m: &mut [u8],
+            ad: Option<&[u8]>,
+            n: &aes_impl::Nonce,
+            k: &aes_impl::Key,
+        ) -> aes_impl::Tag {
+            aes_impl::seal_detached(m, ad, n, k)
+        }
+    }
+
+    #[cfg(test)]
+    mod test {
+        use super::*;
+        use crate::init;
+
+        #[test]
+        fn test_is_available() {
+            init().unwrap();
+            let is_available_feat_check =
+                is_x86_feature_detected!("aes") && is_x86_feature_detected!("pclmulqdq");
+            assert_eq!(aes_impl::is_available(), is_available_feat_check);
+        }
+
+        #[test]
+        fn test_seal_open() {
+            init().unwrap();
+            use randombytes::randombytes;
+            let aes = Aes256Gcm::new().unwrap();
+            for i in 0..256usize {
+                let k = aes.gen_key();
+                let n = gen_random_nonce();
+                let ad = randombytes(i);
+                let m = randombytes(i);
+                let c = aes.seal(&m, Some(&ad), &n, &k);
+                let m2 = aes.open(&c, Some(&ad), &n, &k).unwrap();
+                assert_eq!(m, m2);
+            }
+        }
+
+        #[test]
+        fn test_seal_open_detached() {
+            init().unwrap();
+            use randombytes::randombytes;
+            let aes = Aes256Gcm::new().unwrap();
+            for i in 0..256usize {
+                let k = aes.gen_key();
+                let n = gen_random_nonce();
+                let ad = randombytes(i);
+                let mut m = randombytes(i);
+                let m2 = m.clone();
+                let t = aes.seal_detached(&mut m, Some(&ad), &n, &k);
+                aes.open_detached(&mut m, Some(&ad), &t, &n, &k).unwrap();
+                assert_eq!(m, m2);
+            }
+        }
+    }
+}
+
+pub use self::aes_api::Aes256Gcm;
+pub use self::aes_impl::{is_available, Key, Nonce, Tag, KEYBYTES, NONCEBYTES, TAGBYTES};

src/crypto/aead/chacha20poly1305.rs

@@ -15,7 +15,8 @@ aead_module!(
     crypto_aead_chacha20poly1305_decrypt_detached,
     crypto_aead_chacha20poly1305_KEYBYTES as usize,
     crypto_aead_chacha20poly1305_NPUBBYTES as usize,
-    crypto_aead_chacha20poly1305_ABYTES as usize
+    crypto_aead_chacha20poly1305_ABYTES as usize,
+    true
 );
 
 #[cfg(test)]

src/crypto/aead/chacha20poly1305_ietf.rs

@@ -15,7 +15,8 @@ aead_module!(
     crypto_aead_chacha20poly1305_ietf_decrypt_detached,
     crypto_aead_chacha20poly1305_ietf_KEYBYTES as usize,
     crypto_aead_chacha20poly1305_ietf_NPUBBYTES as usize,
-    crypto_aead_chacha20poly1305_ietf_ABYTES as usize
+    crypto_aead_chacha20poly1305_ietf_ABYTES as usize,
+    true
 );
 
 #[cfg(test)]

src/crypto/aead/mod.rs

@@ -44,6 +44,7 @@
 pub use self::xchacha20poly1305_ietf::*;
 #[macro_use]
 mod aead_macros;
+pub mod aes256gcm;
 pub mod chacha20poly1305;
 pub mod chacha20poly1305_ietf;
 pub mod xchacha20poly1305_ietf;

src/crypto/aead/xchacha20poly1305_ietf.rs

@@ -24,7 +24,8 @@ aead_module!(
     crypto_aead_xchacha20poly1305_ietf_decrypt_detached,
     crypto_aead_xchacha20poly1305_ietf_KEYBYTES as usize,
     crypto_aead_xchacha20poly1305_ietf_NPUBBYTES as usize,
-    crypto_aead_xchacha20poly1305_ietf_ABYTES as usize
+    crypto_aead_xchacha20poly1305_ietf_ABYTES as usize,
+    true
 );
 
 /// `gen_nonce` randomly generates a nonce