Update per PR comments

aws-lc-rs/src/ec.rs

@@ -122,16 +122,16 @@ pub struct PublicKey {
     der: Box<[u8]>,
 }
 
-/// An elliptic curve public key as a DER-encoded `SubjectPublicKeyInfo` structure
+/// An elliptic curve public key as a DER-encoded (X509) `SubjectPublicKeyInfo` structure
 #[allow(clippy::module_name_repetitions)]
-pub struct EcPublicKeyDer {
+pub struct EcPublicKeyX509Der {
     _priv: (),
 }
 
 impl PublicKey {
-    /// Provides the public key as a DER-encoded `SubjectPublicKeyInfo` structure.
+    /// Provides the public key as a DER-encoded (X.509) `SubjectPublicKeyInfo` structure.
     #[must_use]
-    pub fn as_der(&self) -> Buffer<'_, EcPublicKeyDer> {
+    pub fn as_der(&self) -> Buffer<'_, EcPublicKeyX509Der> {
         Buffer::public_from_slice(&self.der)
     }
 }
@@ -147,6 +147,9 @@ impl Debug for PublicKey {
 
 impl AsRef<[u8]> for PublicKey {
     #[inline]
+    /// Serializes the public key in an uncompressed form (X9.62) using the
+    /// Octet-String-to-Elliptic-Curve-Point algorithm in
+    /// [SEC 1: Elliptic Curve Cryptography, Version 2.0].
     fn as_ref(&self) -> &[u8] {
         self.octets.as_ref()
     }
@@ -320,15 +323,15 @@ pub(crate) unsafe fn marshal_public_key_to_buffer(
 }
 
 pub(crate) fn marshal_public_key(
-    evp_key: &ConstPointer<EVP_PKEY>,
+    evp_pkey: &ConstPointer<EVP_PKEY>,
 ) -> Result<PublicKey, Unspecified> {
     let mut pub_key_bytes = [0u8; PUBLIC_KEY_MAX_LEN];
     unsafe {
-        let key_len = marshal_public_key_to_buffer(&mut pub_key_bytes, evp_key)?;
+        let key_len = marshal_public_key_to_buffer(&mut pub_key_bytes, evp_pkey)?;
 
         let der = {
             let mut buffer = std::ptr::null_mut::<u8>();
-            let ec_key = ConstPointer::new(EVP_PKEY_get0_EC_KEY(**evp_key))?;
+            let ec_key = ConstPointer::new(EVP_PKEY_get0_EC_KEY(**evp_pkey))?;
             let len = aws_lc::i2d_EC_PUBKEY(*ec_key, &mut buffer);
             if len < 0 {
                 return Err(Unspecified);

aws-lc-rs/src/ec/key_pair.rs

@@ -13,7 +13,7 @@ use crate::fips::indicator_check;
 use crate::pkcs8::{Document, Version};
 use crate::ptr::{ConstPointer, DetachableLcPtr, LcPtr};
 use crate::rand::SecureRandom;
-use crate::signature::{KeyPair, Signature};
+use crate::signature::{EcdsaPublicKey, KeyPair, Signature};
 use crate::{digest, ec};
 use aws_lc::{EVP_DigestSign, EVP_DigestSignInit, EVP_PKEY_get0_EC_KEY, EVP_PKEY, EVP_PKEY_EC};
 use std::fmt;
@@ -44,7 +44,8 @@ impl KeyPair for EcdsaKeyPair {
     type PublicKey = PublicKey;
 
     #[inline]
-    fn public_key(&self) -> &Self::PublicKey {
+    /// Provides the public key.
+    fn public_key(&self) -> &EcdsaPublicKey {
         &self.pubkey
     }
 }
@@ -161,11 +162,13 @@ impl EcdsaKeyPair {
         }
     }
 
-    /// Deserialize a DER private key and produce an ECDSA key.
+    /// Deserializes a DER-encoded private key structure to produce a `EcdsaKeyPair`.
     ///
-    /// This function will attempt to automatically detect the underlying key format, and
-    /// supports the unencrypted PKCS#8 `PrivateKeyInfo` structures as well as key type specific
-    /// formats.
+    /// This function is typically used to deserialize RFC 5915 encoded private keys, but it will
+    /// attempt to automatically detect other key formats. This function supports unencrypted
+    /// PKCS#8 `PrivateKeyInfo` structures as well as key type specific formats.
+    ///
+    /// See `EcdsaPrivateKey::to_der`.
     ///
     /// # Errors
     /// `error::KeyRejected` if parsing failed or key otherwise unacceptable.
@@ -301,12 +304,12 @@ impl Debug for PrivateKey<'_> {
 }
 
 /// Elliptic curve private key data encoded as a big-endian fixed-length integer.
-pub struct EcPrivateKeyBuffer {
+pub struct EcPrivateKeyBin {
     _priv: (),
 }
 
-/// Elliptic curve private key data encoded as DER.
-pub struct EcPrivateKeyDer {
+/// Elliptic curve private key as a DER-encoded `ECPrivateKey` (RFC 5915) structure.
+pub struct EcPrivateKeyRfc5915Der {
     _priv: (),
 }
 
@@ -317,21 +320,21 @@ impl PrivateKey<'_> {
     ///
     /// # Errors
     /// `error::Unspecified` if serialization failed.
-    pub fn to_buffer(&self) -> Result<Buffer<'static, EcPrivateKeyBuffer>, Unspecified> {
+    pub fn to_bin(&self) -> Result<Buffer<'static, EcPrivateKeyBin>, Unspecified> {
         unsafe {
             let buffer = ec::marshal_private_key_to_buffer(
                 self.0.algorithm.id,
                 &self.0.evp_pkey.as_const(),
             )?;
-            Ok(Buffer::<EcPrivateKeyBuffer>::new(buffer))
+            Ok(Buffer::<EcPrivateKeyBin>::new(buffer))
         }
     }
 
-    /// Encode the private key via DER into bytes.
+    /// Serializes the key as a DER-encoded `ECPrivateKey` (RFC 5915) structure.
     ///
     /// # Errors
     /// `error::Unspecified`  if serialization failed.
-    pub fn to_der(&self) -> Result<Buffer<'static, EcPrivateKeyDer>, Unspecified> {
+    pub fn to_der(&self) -> Result<Buffer<'static, EcPrivateKeyRfc5915Der>, Unspecified> {
         unsafe {
             let mut outp = std::ptr::null_mut::<u8>();
             let ec_key = ConstPointer::new(EVP_PKEY_get0_EC_KEY(*self.0.evp_pkey))?;

aws-lc-rs/src/signature.rs

@@ -250,17 +250,21 @@ use std::fmt::{Debug, Formatter};
 #[cfg(feature = "ring-sig-verify")]
 use untrusted::Input;
 
-pub use crate::ec::key_pair::{
-    EcPrivateKeyBuffer, EcPrivateKeyDer, EcdsaKeyPair, PrivateKey as EcdsaPrivateKey,
-};
+pub use crate::ec::key_pair::{EcdsaKeyPair, PrivateKey as EcdsaPrivateKey};
 use crate::ec::EcdsaSignatureFormat;
 pub use crate::ec::{
-    EcPublicKeyDer, EcdsaSigningAlgorithm, EcdsaVerificationAlgorithm, PublicKey as EcdsaPublicKey,
+    EcdsaSigningAlgorithm, EcdsaVerificationAlgorithm, PublicKey as EcdsaPublicKey,
 };
 pub use crate::ed25519::{
     Ed25519KeyPair, EdDSAParameters, Seed as Ed25519Seed, ED25519_PUBLIC_KEY_LEN,
 };
 
+/// A module containing types that indicate the encoding of a `buffer::Buffer`
+pub mod encoding {
+    pub use crate::ec::key_pair::{EcPrivateKeyBin, EcPrivateKeyRfc5915Der};
+    pub use crate::ec::EcPublicKeyX509Der;
+}
+
 /// The longest signature is an ASN.1 P-384 signature where *r* and *s* are of
 /// maximum length with the leading high bit set on each. Then each component
 /// will have a tag, a one-byte length, and a one-byte “I'm not negative”

aws-lc-rs/tests/ecdsa_tests.rs

@@ -460,24 +460,27 @@ fn test_private_key() {
         let key_pair_doc = EcdsaKeyPair::generate_pkcs8(signing_alg, &rnd).unwrap();
         let key_pair = EcdsaKeyPair::from_pkcs8(signing_alg, key_pair_doc.as_ref()).unwrap();
 
-        let private_key = key_pair.private_key().to_buffer().unwrap();
-        let public_key = key_pair.public_key();
-
-        let key_pair_copy = EcdsaKeyPair::from_private_key_and_public_key(
-            signing_alg,
-            private_key.as_ref(),
-            public_key.as_ref(),
-        )
-        .unwrap();
-        let key_pair_copy_doc = key_pair_copy.to_pkcs8v1().unwrap();
-        assert_eq!(key_pair_doc.as_ref(), key_pair_copy_doc.as_ref());
-
-        let key_pair_copy = EcdsaKeyPair::from_private_key_der(
-            signing_alg,
-            key_pair.private_key().to_der().unwrap().as_ref(),
-        )
-        .unwrap();
-        let key_pair_copy_doc = key_pair_copy.to_pkcs8v1().unwrap();
-        assert_eq!(key_pair_doc.as_ref(), key_pair_copy_doc.as_ref());
+        {
+            let private_key = key_pair.private_key().to_bin().unwrap();
+            let public_key = key_pair.public_key();
+            let key_pair_copy = EcdsaKeyPair::from_private_key_and_public_key(
+                signing_alg,
+                private_key.as_ref(),
+                public_key.as_ref(),
+            )
+            .unwrap();
+            let key_pair_copy_doc = key_pair_copy.to_pkcs8v1().unwrap();
+            assert_eq!(key_pair_doc.as_ref(), key_pair_copy_doc.as_ref());
+        }
+        {
+            let private_key_der = key_pair.private_key().to_der().unwrap();
+            assert_eq!("Buffer(...)", format!("{private_key_der:?}"));
+            assert!(EcdsaKeyPair::from_pkcs8(signing_alg, private_key_der.as_ref()).is_err());
+
+            let key_pair_copy =
+                EcdsaKeyPair::from_private_key_der(signing_alg, private_key_der.as_ref()).unwrap();
+            let key_pair_copy_doc = key_pair_copy.to_pkcs8v1().unwrap();
+            assert_eq!(key_pair_doc.as_ref(), key_pair_copy_doc.as_ref());
+        }
     }
 }