RSA KeyPair improvements, TlsProtocolId fix, and API documentation improvements

aws-lc-rs/Cargo.toml

@@ -22,6 +22,10 @@ exclude = [
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[package.metadata.docs.rs]
+features = ["fips"]
+rustc-args = ["--cfg", "docsrs"]
+
 [features]
 alloc = []
 default = ["aws-lc-sys", "alloc", "ring-io", "ring-sig-verify"]

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

@@ -11,6 +11,7 @@ use core::fmt::Debug;
 /// The Transport Layer Security (TLS) protocol version.
 #[allow(clippy::module_name_repetitions)]
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
+#[non_exhaustive]
 pub enum TlsProtocolId {
     /// TLS 1.2 (RFC 5246)
     TLS12,

aws-lc-rs/src/ec.rs

@@ -141,6 +141,7 @@ unsafe impl Sync for PublicKey {}
 
 impl VerificationAlgorithm for EcdsaVerificationAlgorithm {
     #[inline]
+    #[cfg_attr(docsrs, doc(cfg(feature = "ring-sig-verify")))]
     #[cfg(feature = "ring-sig-verify")]
     fn verify(
         &self,

aws-lc-rs/src/ed25519.rs

@@ -39,6 +39,7 @@ impl sealed::Sealed for EdDSAParameters {}
 
 impl VerificationAlgorithm for EdDSAParameters {
     #[inline]
+    #[cfg_attr(docsrs, doc(cfg(feature = "ring-sig-verify")))]
     #[cfg(feature = "ring-sig-verify")]
     fn verify(
         &self,

aws-lc-rs/src/error.rs

@@ -218,6 +218,10 @@ impl From<()> for KeyRejected {
     }
 }
 
+#[cfg_attr(
+    docsrs,
+    doc(cfg(any(feature = "ring-sig-verify", feature = "ring-io")))
+)]
 #[cfg(any(feature = "ring-sig-verify", feature = "ring-io"))]
 impl From<untrusted::EndOfInput> for Unspecified {
     fn from(_: untrusted::EndOfInput) -> Self {

aws-lc-rs/src/lib.rs

@@ -91,6 +91,7 @@
 //! and deploy them into AWS Regions.
 
 #![warn(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 #[cfg(feature = "fips")]
 extern crate aws_lc_fips_sys as aws_lc;
@@ -106,6 +107,7 @@ pub mod digest;
 pub mod error;
 pub mod hkdf;
 pub mod hmac;
+#[cfg_attr(docsrs, doc(cfg(feature = "ring-io")))]
 #[cfg(feature = "ring-io")]
 pub mod io;
 pub mod pbkdf2;
@@ -148,6 +150,7 @@ pub fn init() {
     });
 }
 
+#[cfg_attr(docsrs, doc(cfg(feature = "fips")))]
 #[cfg(feature = "fips")]
 /// Panics if the underlying implementation is not FIPS, otherwise it returns.
 ///

aws-lc-rs/src/rsa.rs

@@ -19,8 +19,6 @@ use crate::signature::{KeyPair, VerificationAlgorithm};
 use crate::{cbs, digest, rand, test};
 #[cfg(feature = "fips")]
 use aws_lc::RSA_check_fips;
-#[cfg(not(feature = "fips"))]
-use aws_lc::RSA_check_key;
 use aws_lc::{
     EVP_DigestSign, EVP_DigestSignInit, EVP_DigestVerify, EVP_DigestVerifyInit,
     EVP_PKEY_CTX_set_rsa_padding, EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_assign_RSA,
@@ -140,6 +138,10 @@ impl RsaKeyPair {
     const MIN_RSA_PRIME_BITS: u32 = 1024;
     const MAX_RSA_PRIME_BITS: u32 = 4096;
 
+    /// ⚠️ Function assumes that `aws_lc::RSA_check_key` / `aws_lc::RSA_validate_key` has already been invoked beforehand.
+    /// `aws_lc::RSA_validate_key` is already invoked by `aws_lc::EVP_parse_private_key` / `aws_lc::RSA_parse_private_key`.
+    /// If the `EVP_PKEY` was constructed through another mechanism, then the key should be validated through the use of
+    /// one those verifier functions first.
     unsafe fn validate_rsa_pkey(rsa: &LcPtr<EVP_PKEY>) -> Result<(), KeyRejected> {
         let rsa = rsa.get_rsa()?.as_const();
 
@@ -170,11 +172,10 @@ impl RsaKeyPair {
             Ordering::Equal | Ordering::Greater => Ok(()),
         }?;
 
-        #[cfg(not(feature = "fips"))]
-        if 1 != RSA_check_key(*rsa) {
-            return Err(KeyRejected::inconsistent_components());
-        }
-
+        // For the FIPS feature this will perform the necessary public-key validaiton steps and pairwise consistency tests.
+        // TODO: This also result in another call to `aws_lc::RSA_validate_key`, meaning duplicate effort is performed
+        // even after having already performing this operation during key parsing. Ideally the FIPS specific checks
+        // could be pulled out and invoked seperatly from the standard checks.
         #[cfg(feature = "fips")]
         if 1 != RSA_check_fips(*rsa as *mut RSA) {
             return Err(KeyRejected::inconsistent_components());
@@ -185,6 +186,7 @@ impl RsaKeyPair {
 }
 
 impl VerificationAlgorithm for RsaParameters {
+    #[cfg_attr(docsrs, doc(cfg(feature = "ring-sig-verify")))]
     #[cfg(feature = "ring-sig-verify")]
     fn verify(
         &self,
@@ -435,6 +437,7 @@ impl AsRef<[u8]> for RsaSubjectPublicKey {
     }
 }
 
+#[cfg_attr(docsrs, doc(cfg(feature = "ring-io")))]
 #[cfg(feature = "ring-io")]
 impl RsaSubjectPublicKey {
     /// The public modulus (n).

aws-lc-rs/src/signature.rs

@@ -313,6 +313,7 @@ pub trait VerificationAlgorithm: Debug + Sync + sealed::Sealed {
     //
     /// # Errors
     /// `error::Unspecified` if inputs not verified.
+    #[cfg_attr(docsrs, doc(cfg(feature = "ring-sig-verify")))]
     #[cfg(feature = "ring-sig-verify")]
     #[deprecated(note = "please use `VerificationAlgorithm::verify_sig` instead")]
     fn verify(