diff --git a/aes-gcm-siv/src/lib.rs b/aes-gcm-siv/src/lib.rs index 97d47052..f23e7a65 100644 --- a/aes-gcm-siv/src/lib.rs +++ b/aes-gcm-siv/src/lib.rs @@ -88,40 +88,40 @@ use cipher::{ use polyval::{universal_hash::UniversalHash, Polyval}; use zeroize::Zeroize; -/// AES is optional to allow swapping in hardware-specific backends +/// AES is optional to allow swapping in hardware-specific backends. #[cfg(feature = "aes")] use aes::{Aes128, Aes256}; -/// Maximum length of associated data (from RFC 8452 Section 6) +/// Maximum length of associated data (from RFC8452 § 6). pub const A_MAX: u64 = 1 << 36; -/// Maximum length of plaintext (from RFC 8452 Section 6) +/// Maximum length of plaintext (from RFC8452 § 6). pub const P_MAX: u64 = 1 << 36; -/// Maximum length of ciphertext (from RFC 8452 Section 6) +/// Maximum length of ciphertext (from RFC8452 § 6). pub const C_MAX: u64 = (1 << 36) + 16; -/// AES-auth tag-SIV nonces +/// AES-GCM-SIV nonces. pub type Nonce = GenericArray; -/// AES-auth tag-SIV tags +/// AES-GCM-SIV tags. pub type Tag = GenericArray; -/// AES-auth tag-SIV with a 128-bit key +/// AES-GCM-SIV with a 128-bit key. #[cfg(feature = "aes")] pub type Aes128GcmSiv = AesGcmSiv; -/// AES-auth tag-SIV with a 256-bit key +/// AES-GCM-SIV with a 256-bit key. #[cfg(feature = "aes")] pub type Aes256GcmSiv = AesGcmSiv; /// Counter mode with a 32-bit little endian counter. type Ctr32LE = ctr::CtrCore; -/// AES-auth tag-SIV: Misuse-Resistant Authenticated Encryption Cipher (RFC 8452) +/// AES-GCM-SIV: Misuse-Resistant Authenticated Encryption Cipher (RFC 8452). #[derive(Clone)] pub struct AesGcmSiv { - /// Key generating key used to derive AES-auth tag-SIV subkeys + /// Key generating key used to derive AES-GCM-SIV subkeys. key_generating_key: Aes, } @@ -190,18 +190,18 @@ where } } -/// AES-auth tag-SIV: Misuse-Resistant Authenticated Encryption Cipher (RFC 8452) +/// AES-GCM-SIV: Misuse-Resistant Authenticated Encryption Cipher (RFC8452). struct Cipher where Aes: BlockCipher + BlockEncrypt, { - /// Encryption cipher + /// Encryption cipher. enc_cipher: Aes, - /// POLYVAL universal hash + /// POLYVAL universal hash. polyval: Polyval, - /// Nonce + /// Nonce. nonce: Nonce, } @@ -209,7 +209,7 @@ impl Cipher where Aes: BlockCipher + BlockEncrypt + KeyInit, { - /// Initialize AES-auth tag-SIV, deriving per-nonce message-authentication and + /// Initialize AES-GCM-SIV, deriving per-nonce message-authentication and /// message-encryption keys. pub(crate) fn new(key_generating_key: &Aes, nonce: &Nonce) -> Self { let mut mac_key = polyval::Key::default(); @@ -219,8 +219,7 @@ where // Derive subkeys from the master key-generating-key in counter mode. // - // From RFC 8452 Section 4: - // + // From RFC8452 § 4: // // > The message-authentication key is 128 bit, and the message-encryption // > key is either 128 (for AES-128) or 256 bit (for AES-256). @@ -260,7 +259,7 @@ where result } - /// Encrypt the given message in-place, returning the authentication tag + /// Encrypt the given message in-place, returning the authentication tag. pub(crate) fn encrypt_in_place_detached( mut self, associated_data: &[u8], @@ -310,7 +309,7 @@ where } } - /// Finish computing POLYVAL tag for AAD and buffer of the given length + /// Finish computing POLYVAL tag for AAD and buffer of the given length. fn finish_tag(&mut self, associated_data_len: usize, buffer_len: usize) -> Tag { let associated_data_bits = (associated_data_len as u64) * 8; let buffer_bits = (buffer_len as u64) * 8; @@ -337,8 +336,7 @@ where /// Initialize counter mode. /// -/// From RFC 8452 Section 4: -/// +/// From RFC8452 § 4: /// /// > The initial counter block is the tag with the most significant bit /// > of the last byte set to one. diff --git a/aes-gcm/src/lib.rs b/aes-gcm/src/lib.rs index c8595e05..86f733ee 100644 --- a/aes-gcm/src/lib.rs +++ b/aes-gcm/src/lib.rs @@ -98,27 +98,27 @@ use zeroize::Zeroize; #[cfg(feature = "aes")] use aes::{cipher::consts::U12, Aes128, Aes256}; -/// Maximum length of associated data +/// Maximum length of associated data. pub const A_MAX: u64 = 1 << 36; -/// Maximum length of plaintext +/// Maximum length of plaintext. pub const P_MAX: u64 = 1 << 36; -/// Maximum length of ciphertext +/// Maximum length of ciphertext. pub const C_MAX: u64 = (1 << 36) + 16; -/// AES-auth tag nonces +/// AES-GCM nonces. pub type Nonce = GenericArray; -/// AES-auth tag tags +/// AES-GCM tags. pub type Tag = GenericArray; -/// AES-auth tag with a 128-bit key and 96-bit nonce +/// AES-GCM with a 128-bit key and 96-bit nonce. #[cfg(feature = "aes")] #[cfg_attr(docsrs, doc(cfg(feature = "aes")))] pub type Aes128Gcm = AesGcm; -/// AES-auth tag with a 256-bit key and 96-bit nonce +/// AES-GCM with a 256-bit key and 96-bit nonce. #[cfg(feature = "aes")] #[cfg_attr(docsrs, doc(cfg(feature = "aes")))] pub type Aes256Gcm = AesGcm; @@ -129,7 +129,7 @@ type Block = GenericArray; /// Counter mode with a 32-bit big endian counter. type Ctr32BE = ctr::CtrCore; -/// AES-auth tag: generic over an underlying AES implementation and nonce size. +/// AES-GCM: generic over an underlying AES implementation and nonce size. /// /// This type is generic to support substituting alternative AES implementations /// (e.g. embedded hardware implementations) @@ -137,20 +137,20 @@ type Ctr32BE = ctr::CtrCore; /// It is NOT intended to be instantiated with any block cipher besides AES! /// Doing so runs the risk of unintended cryptographic properties! /// -/// The `N` generic parameter can be used to instantiate AES-auth tag with other +/// The `N` generic parameter can be used to instantiate AES-GCM with other /// nonce sizes, however it's recommended to use it with `typenum::U12`, /// the default of 96-bits. /// /// If in doubt, use the built-in [`Aes128Gcm`] and [`Aes256Gcm`] type aliases. #[derive(Clone)] pub struct AesGcm { - /// Encryption cipher + /// Encryption cipher. cipher: Aes, - /// GHASH authenticator + /// GHASH authenticator. ghash: GHash, - /// Length of the nonce + /// Length of the nonce. nonce_size: PhantomData, } @@ -287,7 +287,7 @@ where (ctr, tag_mask) } - /// Authenticate the given plaintext and associated data using GHASH + /// Authenticate the given plaintext and associated data using GHASH. fn compute_tag(&self, mask: Block, associated_data: &[u8], buffer: &[u8]) -> Tag { let mut ghash = self.ghash.clone(); ghash.update_padded(associated_data); diff --git a/aes-gcm/tests/other_ivlen.rs b/aes-gcm/tests/other_ivlen.rs index 66b14d03..71d3c770 100644 --- a/aes-gcm/tests/other_ivlen.rs +++ b/aes-gcm/tests/other_ivlen.rs @@ -1,4 +1,4 @@ -//! Tests for AES-auth tag when used with non-96-bit IVs. +//! Tests for AES-GCM when used with non-96-bit nonces. //! //! Vectors taken from NIST CAVS vectors' `gcmEncryptExtIV128.rsp` file: //!