Add reference to spec and TV source. (fmt)

Author: SalusaSecondus

gmac/README.md

@@ -9,6 +9,10 @@
 
 Generic implementation of the [Galois Message Authentication Code (GMAC)][GMAC].
 
+GMAC is defined by NIST [SP 800-38D] as an authentication-only specialization of
+GCM (Galois Counter Mode). It is equivalent to GCM encryption with an empty plaintext
+and data only provided in the AAD.
+
 **WARNING!** This is a nonce-based MAC and must have a unique nonce for each generation.
 This is identical to the issues with nonce-reuse and AES-GCM (which uses GMAC internally).
 This also means that it is dangerous to clone an instance of GMAC when generating a MAC.
@@ -94,3 +98,4 @@ dual licensed as above, without any additional terms or conditions.
 [RustCrypto]: https://github.com/RustCrypto
 [GMAC]: https://en.wikipedia.org/wiki/Galois/Counter_Mode
 [`aes`]: https://docs.rs/aes
+[SP 800-38D]: https://doi.org/10.6028/NIST.SP.800-38D

gmac/src/lib.rs

@@ -6,8 +6,8 @@
 )]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 
-pub use digest::{self, Mac};
 pub use aes::cipher::KeyIvInit;
+pub use digest::{self, Mac};
 
 use aes::{
     Aes128Enc, Aes192Enc, Aes256Enc,
@@ -64,7 +64,6 @@ where
     buffer_len: usize,
 }
 
-
 impl<Aes, NonceSize> Gmac<Aes, NonceSize>
 where
     Aes: GmacCipher,
@@ -115,26 +114,30 @@ where
     }
 
     /// Generate a random nonce for use with GMAC.
-    /// 
+    ///
     /// GMAC accepts a parameter to encryption/decryption called a "nonce"
     /// which must be unique every time a MAC is generated and never repeated for the same key.
     /// The nonce is often prepended to the tag. The nonce used to produce a given tag must be
     /// passed to the verification MAC calculation.
-    /// 
+    ///
     /// Nonces don’t necessarily have to be random, but it is one strategy which is implemented by this function.
-    /// 
+    ///
     /// # ⚠️Security Warning
-    /// 
+    ///
     /// GMAC fails catastrophically if the nonce is ever repeated.
-    /// 
+    ///
     /// Using random nonces runs the risk of repeating them. The best case for GMAC is with a 12 byte nonce.
     /// With a 12-byte (96-bit) nonce, you can safely generate 2^32 (4,294,967,296) random nonces before the risk
     /// of repeating one becomes too high.
     #[cfg(feature = "rand_core")]
     #[cfg_attr(docsrs, doc(cfg(feature = "rand_core")))]
     #[inline]
-    pub fn generate_nonce<Rng>(mut rng: Rng) -> Result<GenericArray<u8, NonceSize>, <Rng as TryRng>::Error>
-    where Rng: TryCryptoRng {
+    pub fn generate_nonce<Rng>(
+        mut rng: Rng,
+    ) -> Result<GenericArray<u8, NonceSize>, <Rng as TryRng>::Error>
+    where
+        Rng: TryCryptoRng,
+    {
         let mut nonce = GenericArray::<u8, NonceSize>::default();
         rng.try_fill_bytes(&mut nonce)?;
         Ok(nonce)
@@ -283,4 +286,4 @@ where
     Aes: GmacCipher,
     NonceSize: generic_array::ArrayLength<u8>,
 {
-}
+}

gmac/tests/mod.rs

@@ -18,15 +18,20 @@ struct GmacTestVector {
     pub tag: &'static [u8],
 }
 
+// Source for CAVP test vectors: https://csrc.nist.gov/Projects/Cryptographic-Algorithm-Validation-Program/CAVP-TESTING-BLOCK-CIPHER-MODES
+
 blobby::parse_into_structs!(
+    // All CAVP SP 800-38D test vectors for 128 bit keys and empty plaintexts
     include_bytes!("data/gmac_aes128.blb");
     static GMAC_128_KATS: &[GmacTestVector { key, iv, data, tag}];
 );
 blobby::parse_into_structs!(
+    // All CAVP SP 800-38D test vectors for 192 bit keys and empty plaintexts
     include_bytes!("data/gmac_aes192.blb");
     static GMAC_192_KATS: &[GmacTestVector { key, iv, data, tag}];
 );
 blobby::parse_into_structs!(
+    // All CAVP SP 800-38D test vectors for 256 bit keys and empty plaintexts
     include_bytes!("data/gmac_aes256.blb");
     static GMAC_256_KATS: &[GmacTestVector { key, iv, data, tag}];
 );
@@ -56,8 +61,8 @@ fn nonce_generation() {
 #[cfg(feature = "rand_core")]
 #[test]
 fn nonce_generation_16() {
-    use rand::rngs::SysRng;
     use cipher::consts::U16;
+    use rand::rngs::SysRng;
 
     let fake_key = [0u8; 16];
     let nonce = Gmac::<Aes128Enc, U16>::generate_nonce(SysRng).expect("SysRng failed");
@@ -140,7 +145,9 @@ where
                 )
             }
         }
-        if let Err(reason) = initialized_mac_test(mac, tv.data, tv.tag, digest::dev::MacTruncSide::Left) {
+        if let Err(reason) =
+            initialized_mac_test(mac, tv.data, tv.tag, digest::dev::MacTruncSide::Left)
+        {
             panic!(
                 "\n\
                         Failed test (truncated) {name}#{idx}\n\