docs(keys): improved docs surrounding IPublicKey, IPrivateKeys and their encoders/docers

Author: DennisDyallo

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/AsnPrivateKeyDecoder.cs

@@ -19,8 +19,23 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// A class that converts ASN.1 DER encoded private keys to parameters and values.
+/// </summary>
 internal class AsnPrivateKeyDecoder
 {
+    /// <summary>
+    /// Creates an instance of <see cref="IPrivateKey"/> from a PKCS#8
+    /// ASN.1 DER-encoded private key.
+    /// </summary>
+    /// <param name="pkcs8EncodedKey">
+    /// The ASN.1 DER-encoded private key.
+    /// </param>
+    /// <returns>
+    /// A new instance of <see cref="IPrivateKey"/>.
+    /// </returns>
+    /// <exception cref="CryptographicException">Thrown if privateKey does not match expected format.</exception>
+    /// <exception cref="InvalidOperationException">Thrown if the algorithm is not supported</exception>
     public static IPrivateKey CreatePrivateKey(ReadOnlyMemory<byte> pkcs8EncodedKey)
     {
         var reader = new AsnReader(pkcs8EncodedKey, AsnEncodingRules.DER);
@@ -66,8 +81,25 @@ public static IPrivateKey CreatePrivateKey(ReadOnlyMemory<byte> pkcs8EncodedKey)
                 ExceptionMessages.UnsupportedAlgorithm));
     }
 
-    public static Curve25519PrivateKey CreateCurve25519Key(ReadOnlyMemory<byte> pkcs8EncodedKey) =>
-        Curve25519PrivateKey.CreateFromPkcs8(pkcs8EncodedKey);
+    /// <summary>
+    /// Creates an instance of <see cref="Curve25519PrivateKey"/> from a PKCS#8
+    /// ASN.1 DER-encoded private key.
+    /// </summary>
+    /// <param name="pkcs8EncodedKey">
+    /// The ASN.1 DER-encoded private key.
+    /// </param>
+    /// <returns>
+    /// A new instance of <see cref="Curve25519PrivateKey"/>.
+    /// </returns>
+    /// <exception cref="CryptographicException">Thrown if privateKey does not match expected format.</exception>
+    /// <exception cref="ArgumentException">Thrown if the algorithm is not <see cref="Oids.X25519"/> or 
+    /// <see cref="Oids.Ed25519"/></exception>
+    public static Curve25519PrivateKey CreateCurve25519Key(ReadOnlyMemory<byte> pkcs8EncodedKey)
+    {
+        (byte[] privateKey, var keyType) = GetCurve25519PrivateKeyData(pkcs8EncodedKey);
+        using var privateKeyHandle = new ZeroingMemoryHandle(privateKey);
+        return Curve25519PrivateKey.CreateFromValue(privateKeyHandle.Data, keyType);
+    }
 
     public static (byte[] privateKey, KeyType keyType) GetCurve25519PrivateKeyData(ReadOnlyMemory<byte> pkcs8EncodedKey)
     {

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/AsnPublicKeyDecoder.cs

@@ -19,11 +19,26 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// A class that converts ASN.1 DER encoded X.509 SubjectPublicKeyInfo to instances of IPublicKey.
+/// </summary>
 internal class AsnPublicKeyDecoder
 {
-    public static IPublicKey CreatePublicKey(ReadOnlyMemory<byte> pkcs8EncodedKey)
+    /// <summary>
+    /// Creates an instance of <see cref="IPublicKey"/> from a
+    /// ASN.1 DER-encoded SubjectPublicKeyInfo.
+    /// </summary>
+    /// <param name="subjectPublicKeyInfo">
+    /// The ASN.1 DER-encoded SubjectPublicKeyInfo.
+    /// </param>
+    /// <returns>
+    /// A new instance of <see cref="IPublicKey"/>.
+    /// </returns>
+    /// <exception cref="CryptographicException">Thrown if public key does not match expected format.</exception>
+    /// <exception cref="InvalidOperationException">Thrown if the algorithm is not supported</exception>
+    public static IPublicKey CreatePublicKey(ReadOnlyMemory<byte> subjectPublicKeyInfo)
     {
-        var reader = new AsnReader(pkcs8EncodedKey, AsnEncodingRules.DER);
+        var reader = new AsnReader(subjectPublicKeyInfo, AsnEncodingRules.DER);
         var seqSubjectPublicKeyInfo = reader.ReadSequence();
         var seqAlgorithmIdentifier = seqSubjectPublicKeyInfo.ReadSequence();
 

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/Curve25519PrivateKey.cs

@@ -78,10 +78,10 @@ public override byte[] ExportPkcs8PrivateKey()
 
     /// <summary>
     /// Creates an instance of <see cref="Curve25519PrivateKey"/> from a PKCS#8
-    /// DER-encoded private key.
+    /// ASN.1 DER-encoded private key.
     /// </summary>
     /// <param name="pkcs8EncodedKey">
-    /// The DER-encoded private key.
+    /// The ASN.1 DER-encoded private key.
     /// </param>
     /// <returns>
     /// A new instance of <see cref="Curve25519PrivateKey"/>.

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/Curve25519PublicKey.cs

@@ -70,16 +70,16 @@ public override byte[] ExportSubjectPublicKeyInfo() =>
         AsnPublicKeyEncoder.EncodeToSubjectPublicKeyInfo(_publicPoint, KeyDefinition.KeyType);
 
     /// <summary>
-    /// Creates a new instance of <see cref="Curve25519PublicKey"/> from a DER-encoded public key.
+    /// Creates a new instance of <see cref="Curve25519PublicKey"/> from a DER-encoded SubjectPublicKeyInfo.
     /// </summary>
     /// <param name="subjectPublicKeyInfo">
-    /// The DER-encoded public key.
+    /// The DER-encoded SubjectPublicKeyInfo.
     /// </param>
     /// <returns>
     /// A new instance of <see cref="Curve25519PublicKey"/>.
     /// </returns>
     /// <exception cref="CryptographicException">
-    /// Thrown if the public key is invalid.
+    /// Thrown if the subjectPublicKeyInfo is invalid.
     /// </exception>
     public static Curve25519PublicKey CreateFromSubjectPublicKeyInfo(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
         AsnPublicKeyDecoder
@@ -111,6 +111,6 @@ public static Curve25519PublicKey CreateFromValue(ReadOnlyMemory<byte> publicPoi
     }
 
     [Obsolete("Use CreateFromSubjectPublicKeyInfo instead", false)]
-    public static Curve25519PublicKey CreateFromPkcs8(ReadOnlyMemory<byte> encodedKey) =>
-        CreateFromSubjectPublicKeyInfo(encodedKey);
+    public static Curve25519PublicKey CreateFromPkcs8(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
+        CreateFromSubjectPublicKeyInfo(subjectPublicKeyInfo);
 }

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/ECPublicKey.cs

@@ -141,19 +141,19 @@ public static ECPublicKey CreateFromValue(ReadOnlyMemory<byte> publicPoint, KeyT
     }
 
     /// <summary>
-    /// Creates an instance of <see cref="ECPublicKey"/> from a DER-encoded public key.
+    /// Creates an instance of <see cref="ECPublicKey"/> from a DER-encoded SubjectPublicKeyInfo.
     /// </summary>
-    /// <param name="encodedKey">The DER-encoded public key.</param>
+    /// <param name="subjectPublicKeyInfo">The DER-encoded SubjectPublicKeyInfo.</param>
     /// <returns>An instance of <see cref="IPublicKey"/>.</returns>
     /// <exception cref="CryptographicException">
-    /// Thrown if the public key is invalid.
+    /// Thrown if the subjectPublicKeyInfo is invalid.
     /// </exception>
-    public static ECPublicKey CreateFromSubjectPublicKeyInfo(ReadOnlyMemory<byte> encodedKey) =>
+    public static ECPublicKey CreateFromSubjectPublicKeyInfo(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
         AsnPublicKeyDecoder
-            .CreatePublicKey(encodedKey)
+            .CreatePublicKey(subjectPublicKeyInfo)
             .Cast<ECPublicKey>();
 
     [Obsolete("Use CreateFromSubjectPublicKeyInfo instead", false)]
-    public static ECPublicKey CreateFromPkcs8(ReadOnlyMemory<byte> encodedKey) =>
-    CreateFromSubjectPublicKeyInfo(encodedKey);
+    public static ECPublicKey CreateFromPkcs8(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
+    CreateFromSubjectPublicKeyInfo(subjectPublicKeyInfo);
 }

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/RSAPublicKey.cs

@@ -97,20 +97,20 @@ public static RSAPublicKey CreateFromParameters(RSAParameters parameters)
     }
 
     /// <summary>
-    /// Creates a new instance of <see cref="IPublicKey"/> from a DER-encoded public key.
+    /// Creates a new instance of <see cref="IPublicKey"/> from ASN.1 DER-encoded SubjectPublicKeyInfo.
     /// </summary>
-    /// <param name="encodedKey">The DER-encoded public key.</param>
+    /// <param name="subjectPublicKeyInfo">The DER-encoded SubjectPublicKeyInfo.</param>
     /// <returns>A new instance of <see cref="IPublicKey"/>.</returns>
     /// <exception cref="CryptographicException">
     /// Thrown if the public key is invalid.
     /// </exception>
-    public static RSAPublicKey CreateFromSubjectPublicKeyInfo(ReadOnlyMemory<byte> encodedKey) =>
+    public static RSAPublicKey CreateFromSubjectPublicKeyInfo(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
         AsnPublicKeyDecoder
-            .CreatePublicKey(encodedKey)
+            .CreatePublicKey(subjectPublicKeyInfo)
             .Cast<RSAPublicKey>();
 
 
     [Obsolete("Use CreateFromSubjectPublicKeyInfo instead", false)]
-    public static RSAPublicKey CreateFromPkcs8(ReadOnlyMemory<byte> encodedKey) =>
-        CreateFromSubjectPublicKeyInfo(encodedKey);
+    public static RSAPublicKey CreateFromPkcs8(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
+        CreateFromSubjectPublicKeyInfo(subjectPublicKeyInfo);
 }