Documentation cleanup

aws-lc-rs/src/aead.rs

@@ -16,7 +16,7 @@
 //!
 //! [`RandomizedNonceKey`] provides a simplified API interface that doesn't
 //! require the caller to handle construction of a `NonceSequence` or `Nonce` values
-//! themselves. FIPS users should leverage the API provided by this type.
+//! themselves.
 //!
 //! ```rust
 //! # use std::error::Error;
@@ -49,8 +49,8 @@
 //!
 //! # TLS AEAD APIs
 //!
-//! Application developers developing TLS protocol implementations, with FIPS compliance requirements
-//! should use the [`TlsRecordSealingKey`] and [`TlsRecordOpeningKey`] respectively.
+//! Application developers developing TLS protocol implementations should use
+//! [`TlsRecordSealingKey`] and [`TlsRecordOpeningKey`] respectively for AEAD.
 //!
 //! # Nonce Sequence APIs
 //!
@@ -217,10 +217,10 @@ impl<N: NonceSequence> OpeningKey<N> {
     /// overwritten in an unspecified way.
     ///
     /// # FIPS
-    /// FIPS users should only utilize this method with `AES_128_GCM` or `AES_256_GCM` algorithms.
+    /// Use this method with `AES_128_GCM` or `AES_256_GCM` algorithms.
     ///
-    /// Prefer [`RandomizedNonceKey::open_in_place`] for FIPS usage, as it provides API symmetry with
-    /// sealing operations.
+    /// Prefer [`RandomizedNonceKey::open_in_place`], as it provides API symmetry
+    /// with sealing operations.
     #[inline]
     pub fn open_in_place<'in_out, A>(
         &mut self,
@@ -280,10 +280,10 @@ impl<N: NonceSequence> OpeningKey<N> {
     /// overwritten in an unspecified way.
     ///
     /// # FIPS
-    /// FIPS users should only utilize this method with `AES_128_GCM` or `AES_256_GCM` algorithms.
+    /// Use this method with `AES_128_GCM` or `AES_256_GCM` algorithms.
     ///
-    /// Prefer [`RandomizedNonceKey::open_in_place`] for FIPS usage, as it provides API symmetry with
-    /// sealing operations.
+    /// Prefer [`RandomizedNonceKey::open_within`], as it provides API symmetry
+    /// with sealing operations.
     #[inline]
     pub fn open_within<'in_out, A>(
         &mut self,
@@ -386,9 +386,9 @@ impl<N: NonceSequence> SealingKey<N> {
     /// See `seal_in_place_append_tag`
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     ///
-    /// See [`RandomizedNonceKey::seal_in_place_append_tag`] for FIPS usage.
+    /// See [`RandomizedNonceKey::seal_in_place_append_tag`].
     #[deprecated(note = "Renamed to `seal_in_place_append_tag`.")]
     #[inline]
     pub fn seal_in_place<A, InOut>(
@@ -416,9 +416,9 @@ impl<N: NonceSequence> SealingKey<N> {
     /// `error::Unspecified` when `nonce_sequence` cannot be advanced.
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     ///
-    /// See [`RandomizedNonceKey::seal_in_place_append_tag`] for FIPS usage.
+    /// See [`RandomizedNonceKey::seal_in_place_append_tag`].
     #[inline]
     #[allow(clippy::needless_pass_by_value)]
     pub fn seal_in_place_append_tag<A, InOut>(
@@ -456,9 +456,9 @@ impl<N: NonceSequence> SealingKey<N> {
     /// `error::Unspecified` when `nonce_sequence` cannot be advanced.
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     ///
-    /// See [`RandomizedNonceKey::seal_in_place_separate_tag`] for FIPS approved usage.
+    /// See [`RandomizedNonceKey::seal_in_place_separate_tag`].
     #[inline]
     #[allow(clippy::needless_pass_by_value)]
     pub fn seal_in_place_separate_tag<A>(
@@ -675,7 +675,7 @@ impl hkdf::KeyType for &'static Algorithm {
 /// Immutable keys for use in situations where `OpeningKey`/`SealingKey` and
 /// `NonceSequence` cannot reasonably be used.
 ///
-/// Prefer to use `OpeningKey`/`SealingKey` and `NonceSequence` when practical.
+/// Prefer `RandomizedNonceKey` or `OpeningKey`/`SealingKey` and `NonceSequence` when practical.
 pub struct LessSafeKey {
     key: UnboundKey,
 }
@@ -695,9 +695,9 @@ impl LessSafeKey {
     /// `error::Unspecified` when ciphertext is invalid.
     ///
     /// # FIPS
-    /// FIPS users should only utilize this method with `AES_128_GCM` or `AES_256_GCM` algorithms.
+    /// Use this method with `AES_128_GCM` or `AES_256_GCM` algorithms.
     ///
-    /// Prefer [`RandomizedNonceKey::open_in_place`] for FIPS usage, as it provides API symmetry with
+    /// Prefer [`RandomizedNonceKey::open_in_place`] as it provides API symmetry with
     /// sealing operations.
     #[inline]
     pub fn open_in_place<'in_out, A>(
@@ -720,10 +720,10 @@ impl LessSafeKey {
     /// `error::Unspecified` when ciphertext is invalid.
     ///
     /// # FIPS
-    /// FIPS users should only utilize this method with `AES_128_GCM` or `AES_256_GCM` algorithms.
+    /// Use this method with `AES_128_GCM` or `AES_256_GCM` algorithms.
     ///
-    /// Prefer [`RandomizedNonceKey::open_in_place`] for FIPS usage, as it provides API symmetry with
-    /// sealing operations.
+    /// Prefer [`RandomizedNonceKey::open_in_place`], as it provides API symmetry
+    /// with sealing operations.
     #[inline]
     pub fn open_within<'in_out, A>(
         &self,
@@ -748,9 +748,9 @@ impl LessSafeKey {
     /// Deprecated. Renamed to `seal_in_place_append_tag()`.
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     ///
-    /// See [`RandomizedNonceKey::seal_in_place_append_tag`] for FIPS usage.
+    /// See [`RandomizedNonceKey::seal_in_place_append_tag`].
     #[deprecated(note = "Renamed to `seal_in_place_append_tag`.")]
     #[inline]
     #[allow(clippy::missing_errors_doc)]
@@ -776,9 +776,9 @@ impl LessSafeKey {
     /// `error::Unspecified` if encryption operation fails.
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     ///
-    /// See [`RandomizedNonceKey::seal_in_place_append_tag`] for FIPS usage.
+    /// See [`RandomizedNonceKey::seal_in_place_append_tag`].
     #[inline]
     #[allow(clippy::needless_pass_by_value)]
     pub fn seal_in_place_append_tag<A, InOut>(
@@ -810,9 +810,9 @@ impl LessSafeKey {
     /// `error::Unspecified` if encryption operation fails.
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not use this method.
     ///
-    /// See [`RandomizedNonceKey::seal_in_place_separate_tag`] for FIPS usage.
+    /// See [`RandomizedNonceKey::seal_in_place_separate_tag`].
     #[inline]
     #[allow(clippy::needless_pass_by_value)]
     pub fn seal_in_place_separate_tag<A>(
@@ -851,6 +851,8 @@ impl LessSafeKey {
     /// # Errors
     /// `error::Unspecified` if encryption operation fails.
     ///
+    /// # FIPS
+    /// This function should not be used.
     #[inline]
     #[allow(clippy::needless_pass_by_value)]
     pub fn seal_in_place_scatter<A>(
@@ -894,8 +896,8 @@ impl Debug for LessSafeKey {
 /// AEAD Cipher key using a randomized nonce.
 ///
 /// # FIPS
-/// `RandomizedNonceKey` encapsulates APIs that follow FIPS guidance, handling
-/// generation of nonce values, and only supports the `AES_128_GCM` and `AES_256_GCM` algorithms.
+/// `RandomizedNonceKey` handles generation random nonce values, and only supports
+/// the `AES_128_GCM` and `AES_256_GCM` algorithms.
 pub struct RandomizedNonceKey {
     ctx: AeadCtx,
     algorithm: &'static Algorithm,
@@ -1068,8 +1070,8 @@ pub enum TlsProtocolId {
 /// AEAD Encryption key used for TLS protocol record encryption.
 ///
 /// # FIPS
-/// This type encapsulates encryption operations for TLS AEAD algorithms following FIPS implementation guidance.
-/// The API only supports `AES_128_GCM` and `AES_256_GCM`, and validates that the provides nonce values
+/// This type encapsulates encryption operations for TLS AEAD algorithms. The API only supports
+/// `AES_128_GCM` and `AES_256_GCM`, and validates that the provides nonce values
 /// are monotonically increasing for each invocation.
 pub struct TlsRecordSealingKey {
     // The TLS specific construction for TLS ciphers in AWS-LC are not thread-safe!
@@ -1201,7 +1203,9 @@ impl TlsRecordSealingKey {
 /// AEAD Encryption key used for TLS protocol record encryption.
 ///
 /// # FIPS
-/// This type encapsulates decryption operations for TLS AEAD algorithms following FIPS implementation guidance.
+/// This type encapsulates decryption operations for TLS AEAD algorithms. The API only supports
+/// `AES_128_GCM` and `AES_256_GCM`, and validates that the provides nonce values
+/// are monotonically increasing for each invocation.
 pub struct TlsRecordOpeningKey {
     // The TLS specific construction for TLS ciphers in AWS-LC are not thread-safe!
     // The choice here was either wrap the underlying EVP_AEAD_CTX in a Mutex as done here,

aws-lc-rs/src/aead/chacha20_poly1305_openssh.rs

@@ -21,7 +21,7 @@
 //! [RFC 4253]: https://tools.ietf.org/html/rfc4253
 //!
 //! # FIPS
-//! FIPS users should not use the APIs offered in this module.
+//! The APIs offered in this module should not be used.
 
 use super::{poly1305, Nonce, Tag};
 use crate::cipher::block::BLOCK_LEN;
@@ -53,7 +53,7 @@ impl SealingKey {
     /// is encrypted with `K_1` and `ciphertext` is encrypted by `K_2`.
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     #[inline]
     pub fn seal_in_place(
         &self,
@@ -100,7 +100,7 @@ impl OpeningKey {
     /// called.
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     #[inline]
     #[must_use]
     pub fn decrypt_packet_length(
@@ -130,7 +130,7 @@ impl OpeningKey {
     /// `error::Unspecified` when ciphertext is invalid
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     #[inline]
     pub fn open_in_place<'a>(
         &self,

aws-lc-rs/src/cipher.rs

@@ -423,7 +423,8 @@ impl PaddedBlockEncryptingKey {
     /// * [`Unspecified`]: Returned if there is an error cosntructing a `PaddedBlockEncryptingKey`.
     ///
     /// # FIPS
-    /// This mode utilizes cryptographic implementations that follow FIPS implementation guidance.
+    /// This constructor functiion should be used with an `UnboundCipherKey` constructed with either
+    /// `AES_128` or `AES_256` algorithms.
     pub fn cbc_pkcs7(key: UnboundCipherKey) -> Result<PaddedBlockEncryptingKey, Unspecified> {
         PaddedBlockEncryptingKey::new(key, OperatingMode::CBC, PaddingStrategy::PKCS7)
     }
@@ -512,6 +513,10 @@ impl PaddedBlockDecryptingKey {
     ///
     /// # Errors
     /// * [`Unspecified`]: Returned if there is an error constructing the `PaddedBlockDecryptingKey`.
+    ///
+    /// # FIPS
+    /// This constructor functiion should be used with an `UnboundCipherKey` constructed with either
+    /// `AES_128` or `AES_256` algorithms.
     pub fn cbc_pkcs7(key: UnboundCipherKey) -> Result<PaddedBlockDecryptingKey, Unspecified> {
         PaddedBlockDecryptingKey::new(key, OperatingMode::CBC, PaddingStrategy::PKCS7)
     }
@@ -584,6 +589,10 @@ impl EncryptingKey {
     ///
     /// # Errors
     /// * [`Unspecified`]: Returned if there is an error constructing the `EncryptingKey`.
+    ///
+    /// # FIPS
+    /// This constructor functiion should be used with an `UnboundCipherKey` constructed with either
+    /// `AES_128` or `AES_256` algorithms.
     pub fn ctr(key: UnboundCipherKey) -> Result<EncryptingKey, Unspecified> {
         EncryptingKey::new(key, OperatingMode::CTR)
     }
@@ -660,7 +669,8 @@ impl DecryptingKey {
     /// * [`Unspecified`]: Returned if there is an error during decryption.
     ///
     /// # FIPS
-    /// This mode utilizes cryptographic functions that follow FIPS implementation guidance.
+    /// This constructor functiion should be used with an `UnboundCipherKey` constructed with either
+    /// `AES_128` or `AES_256` algorithms.
     pub fn ctr(key: UnboundCipherKey) -> Result<DecryptingKey, Unspecified> {
         DecryptingKey::new(key, OperatingMode::CTR)
     }

aws-lc-rs/src/digest.rs

@@ -124,7 +124,7 @@ impl Context {
     /// Panics if the digest is unable to be finalized
     ///
     /// # FIPS
-    /// FIPS users should only utilize this method with the following algorithms:
+    /// This function should only be used with the following algorithms:
     /// * `SHA1_FOR_LEGACY_USE_ONLY`
     /// * `SHA224`
     /// * `SHA256`
@@ -169,7 +169,7 @@ impl Context {
 /// Returns the digest of `data` using the given digest algorithm.
 ///
 /// # FIPS
-/// FIPS users should only utilize this method with the following algorithms:
+/// This function should only be used with the following algorithms:
 /// * `SHA1_FOR_LEGACY_USE_ONLY`
 /// * `SHA224`
 /// * `SHA256`

aws-lc-rs/src/ed25519.rs

@@ -296,7 +296,7 @@ impl Ed25519KeyPair {
     /// Panics if the message is unable to be signed
     ///
     /// # FIPS
-    /// FIPS users should not use this method.
+    /// This function should not be used.
     #[inline]
     #[must_use]
     pub fn sign(&self, msg: &[u8]) -> Signature {

aws-lc-rs/src/hkdf.rs

@@ -121,6 +121,14 @@ impl Salt {
     ///
     /// # Panics
     /// `new` panics if the salt length exceeds the limit
+    ///
+    /// # FIPS
+    /// * The provided `Algorithm` should be one of these following:
+    ///   * `HKDF_SHA1_FOR_LEGACY_USE_ONLY`
+    ///   * `HKDF_SHA256`
+    ///   * `HKDF_SHA384`
+    ///   * `HKDF_SHA512`
+    /// * `value.len() > 0` is true
     #[must_use]
     pub fn new(algorithm: Algorithm, value: &[u8]) -> Self {
         Salt::try_new(algorithm, value).expect("Salt length limit exceeded.")
@@ -306,6 +314,11 @@ impl Prk {
     ///
     /// # Panics
     /// Panics if the given Prk length exceeds the limit
+    ///
+    /// # FIPS
+    /// This function should not be used.
+    ///
+    /// See [`Salt::extract`].
     #[must_use]
     pub fn new_less_safe(algorithm: Algorithm, value: &[u8]) -> Self {
         Prk::try_new_less_safe(algorithm, value).expect("Prk length limit exceeded.")
@@ -330,6 +343,11 @@ impl Prk {
     ///
     /// # Errors
     /// `error::Unspecified` if (and only if) `len` is too large.
+    ///
+    /// # FIPS
+    /// * `Prk` should be constructed using `Salt::extract` prior to calling
+    /// this method.
+    /// * After concatination of the `info` slices the resulting `[u8].len() > 0` is true.
     #[inline]
     pub fn expand<'a, L: KeyType>(
         &'a self,
@@ -411,13 +429,13 @@ impl<L: KeyType> Okm<'_, L> {
     /// `L: KeyType`.
     ///
     ///# FIPS
-    /// FIPS users should utilize this method when meeting the following conditions:
+    /// The following conditions should be met:
     /// * The HKDF algorithm is one of:
     ///    * `HKDF_SHA1_FOR_LEGACY_USE_ONLY`
     ///    * `HKDF_SHA256`
     ///    * `HKDF_SHA384`
     ///    * `HKDF_SHA512`
-    /// * If the [`Okm`] was constructed from a [`Prk`] created with [`Salt::extract`]:
+    /// * The [`Okm`] was constructed from a [`Prk`] created with [`Salt::extract`] and:
     ///    * The `value.len()` passed to [`Salt::new`] was non-zero.
     ///    * The `info_len` from [`Prk::expand`] was non-zero.
     #[inline]

aws-lc-rs/src/hmac.rs

@@ -387,6 +387,10 @@ impl Context {
     ///
     /// # Panics
     /// Panics if the HMAC calculation cannot be finalized
+    ///
+    /// # FIPS
+    /// Use this method with `HMAC_SHA1_FOR_LEGACY_USE_ONLY`, `HMAC_SHA224`, `HMAC_SHA256`,
+    /// `HMAC_SHA384`, or `HMAC_SHA512` algorithms.
     #[inline]
     #[must_use]
     pub fn sign(self) -> Tag {
@@ -420,7 +424,7 @@ impl Context {
 /// return value of `sign` to a tag. Use `verify` for verification instead.
 ///
 /// # FIPS
-/// FIPS users should only utilize this method with `HMAC_SHA1_FOR_LEGACY_USE_ONLY`, `HMAC_SHA224`, `HMAC_SHA256`,
+/// Use this method with `HMAC_SHA1_FOR_LEGACY_USE_ONLY`, `HMAC_SHA224`, `HMAC_SHA256`,
 /// `HMAC_SHA384`, or `HMAC_SHA512` algorithms.
 #[inline]
 #[must_use]
@@ -442,7 +446,7 @@ pub fn sign(key: &Key, data: &[u8]) -> Tag {
 /// `error::Unspecified` if the inputs are not verified.
 ///
 /// # FIPS
-/// FIPS users should only utilize this method with `HMAC_SHA1_FOR_LEGACY_USE_ONLY`, `HMAC_SHA224`, `HMAC_SHA256`,
+/// Use this method with `HMAC_SHA1_FOR_LEGACY_USE_ONLY`, `HMAC_SHA224`, `HMAC_SHA256`,
 /// `HMAC_SHA384`, or `HMAC_SHA512` algorithms.
 #[inline]
 pub fn verify(key: &Key, data: &[u8], tag: &[u8]) -> Result<(), Unspecified> {