Merge pull request #243 from Yubico/dennisdyallo/keys-docs

refactor: Add consistent docs and proper naming for certain methods for creating keys

Author: DennisDyallo

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

@@ -15,13 +15,27 @@
 using System;
 using System.Formats.Asn1;
 using System.Globalization;
-using System.Linq;
 using System.Security.Cryptography;
 
 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);
@@ -67,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

@@ -17,13 +17,21 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// Represents a Curve25519 private key.
+/// </summary>
+/// <remarks>
+/// This sealed class encapsulates Curve25519 private key data and supports
+/// both Ed25519 and X25519 cryptographic operations.
+/// It also provides factory methods for creating instances from private key values or DER-encoded data.
+/// </remarks>
 public sealed class Curve25519PrivateKey : PrivateKey
 {
     private readonly Memory<byte> _privateKey;
 
     /// <inheritdoc />
     public override KeyType KeyType => KeyDefinition.KeyType;
-    
+
     /// <summary>
     /// Gets the key definition associated with this RSA private key.
     /// </summary>
@@ -37,7 +45,7 @@ public sealed class Curve25519PrivateKey : PrivateKey
     /// </summary>
     /// <returns>A <see cref="ReadOnlyMemory{T}"/> containing the private scalar value.</returns>
     public ReadOnlyMemory<byte> PrivateKey => _privateKey;
-    
+
     private Curve25519PrivateKey(
         ReadOnlyMemory<byte> privateKey,
         KeyType keyType)
@@ -53,9 +61,9 @@ private Curve25519PrivateKey(
 
         privateKey.CopyTo(_privateKey);
     }
-    
+
     /// <inheritdoc />
-    public override byte[] ExportPkcs8PrivateKey() 
+    public override byte[] ExportPkcs8PrivateKey()
     {
         ThrowIfDisposed();
         return AsnPrivateKeyEncoder.EncodeToPkcs8(_privateKey, KeyType);
@@ -70,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"/>.
@@ -88,7 +96,7 @@ public static Curve25519PrivateKey CreateFromPkcs8(ReadOnlyMemory<byte> pkcs8Enc
         using var privateKeyHandle = new ZeroingMemoryHandle(privateKey);
         return new Curve25519PrivateKey(privateKeyHandle.Data, keyType);
     }
-    
+
     /// <summary>
     /// Creates an instance of <see cref="Curve25519PrivateKey"/> from the given
     /// <paramref name="privateKey"/> and <paramref name="keyType"/>.

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

@@ -13,12 +13,19 @@
 // limitations under the License.
 
 using System;
-using System.Formats.Asn1;
 using System.Globalization;
 using System.Security.Cryptography;
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// Represents a Curve25519 public key.
+/// </summary>
+/// <remarks>
+/// This sealed class encapsulates Curve25519 public key data as a compressed point
+/// and supports both Ed25519 and X25519 key types.
+/// It also provides factory methods for creating instances from public point values or DER-encoded data.
+/// </remarks>
 public sealed class Curve25519PublicKey : PublicKey
 {
     private readonly Memory<byte> _publicPoint;
@@ -52,7 +59,7 @@ private Curve25519PublicKey(
 
         publicPoint.CopyTo(_publicPoint);
     }
-    
+
     /// <summary>
     /// Converts this public key to an ASN.1 DER encoded format (X.509 SubjectPublicKeyInfo).
     /// </summary>
@@ -63,33 +70,21 @@ 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="encodedKey">
-    /// The DER-encoded public key.
+    /// <param name="subjectPublicKeyInfo">
+    /// 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 CreateFromPkcs8(ReadOnlyMemory<byte> encodedKey)
-    {
-        var reader = new AsnReader(encodedKey, AsnEncodingRules.DER);
-        var seqSubjectPublicKeyInfo = reader.ReadSequence();
-        var seqAlgorithmIdentifier = seqSubjectPublicKeyInfo.ReadSequence();
-
-        string oidAlgorithm = seqAlgorithmIdentifier.ReadObjectIdentifier();
-        byte[] subjectPublicKey = seqSubjectPublicKeyInfo.ReadBitString(out int unusedBitCount);
-        if (unusedBitCount != 0)
-        {
-            throw new CryptographicException("Invalid public key encoding");
-        }
-
-        var keyType = KeyDefinitions.GetKeyTypeByOid(oidAlgorithm);
-        return CreateFromValue(subjectPublicKey, keyType);
-    }
+    public static Curve25519PublicKey CreateFromSubjectPublicKeyInfo(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
+        AsnPublicKeyDecoder
+            .CreatePublicKey(subjectPublicKeyInfo)
+            .Cast<Curve25519PublicKey>();
 
     /// <summary>
     /// Creates an instance of <see cref="Curve25519PublicKey"/> from the given
@@ -114,4 +109,8 @@ public static Curve25519PublicKey CreateFromValue(ReadOnlyMemory<byte> publicPoi
 
         return new Curve25519PublicKey(publicPoint, keyDefinition);
     }
+
+    [Obsolete("Use CreateFromSubjectPublicKeyInfo instead", false)]
+    public static Curve25519PublicKey CreateFromPkcs8(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
+        CreateFromSubjectPublicKeyInfo(subjectPublicKeyInfo);
 }

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/ECPrivateKey.cs

@@ -21,8 +21,9 @@ namespace Yubico.YubiKey.Cryptography
     /// Represents the parameters for an Elliptic Curve (EC) private key.
     /// </summary>
     /// <remarks>
-    /// This class encapsulates the parameters specific to EC private keys and
-    /// contains the necessary private key data.
+    /// This class encapsulates the parameters specific to EC private keys
+    /// and provides factory methods for creating instances from EC parameters
+    /// or DER-encoded data.
     /// </remarks>
     public class ECPrivateKey : PrivateKey
     {
@@ -33,7 +34,7 @@ public class ECPrivateKey : PrivateKey
         /// An <see cref="ECParameters"/> structure containing the curve parameters, key, and other
         /// cryptographic elements needed for EC operations.
         /// </value>
-        public ECParameters Parameters { get;}
+        public ECParameters Parameters { get; }
 
         /// <summary>
         /// Gets the key definition associated with this RSA private key.
@@ -84,7 +85,7 @@ protected ECPrivateKey(ECDsa ecdsaObject)
             Parameters = ecdsaObject.ExportParameters(true);
             KeyDefinition = KeyDefinitions.GetByOid(Parameters.Curve.Oid);
         }
-        
+
         /// <inheritdoc/>
         public override byte[] ExportPkcs8PrivateKey()
         {
@@ -115,12 +116,16 @@ public override void Clear()
         public static ECPrivateKey CreateFromPkcs8(ReadOnlyMemory<byte> encodedKey)
         {
             var parameters = AsnPrivateKeyDecoder.CreateECParameters(encodedKey);
+
             return CreateFromParameters(parameters);
         }
-        
-        #pragma warning disable CS0618 // Type or member is obsolete.
+
+        /// <summary>
+        /// Creates an instance of <see cref="ECPrivateKey"/> from the given <paramref name="parameters"/>.
+        /// </summary>
+        /// <param name="parameters">The parameters to create the key from.</param>
+        /// <returns>An instance of <see cref="ECPrivateKey"/>.</returns>
         public static ECPrivateKey CreateFromParameters(ECParameters parameters) => new(parameters);
-        #pragma warning restore CS0618 // Type or member is obsolete
 
         /// <summary>
         /// Creates a new instance of <see cref="ECPrivateKey"/> from the given

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

@@ -18,11 +18,11 @@
 namespace Yubico.YubiKey.Cryptography;
 
 /// <summary>
-/// Represents the parameters for an Elliptic Curve (EC) public key.
+/// Represents an Elliptic Curve (EC) public key.
 /// </summary>
 /// <remarks>
-/// This class encapsulates the parameters specific to EC public keys,
-/// ensuring that the key only contains necessary public key components.
+/// This class encapsulates EC public key parameters and provides cryptographic operations
+/// for NIST elliptic curves and provides factory methods for creating instances from EC parameters or DER-encoded data.
 /// </remarks>
 public class ECPublicKey : PublicKey
 {
@@ -99,7 +99,7 @@ protected ECPublicKey(ECDsa ecdsa)
 
     /// <inheritdoc />
     public override byte[] ExportSubjectPublicKeyInfo() => AsnPublicKeyEncoder.EncodeToSubjectPublicKeyInfo(Parameters);
-    
+
     /// <summary>
     /// Creates an instance of <see cref="ECPublicKey"/> from the given <paramref name="parameters"/>.
     /// </summary>
@@ -141,13 +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 CreateFromPkcs8(ReadOnlyMemory<byte> encodedKey) =>
-        (ECPublicKey)AsnPublicKeyDecoder.CreatePublicKey(encodedKey);
+    public static ECPublicKey CreateFromSubjectPublicKeyInfo(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
+        AsnPublicKeyDecoder
+            .CreatePublicKey(subjectPublicKeyInfo)
+            .Cast<ECPublicKey>();
+
+    [Obsolete("Use CreateFromSubjectPublicKeyInfo instead", false)]
+    public static ECPublicKey CreateFromPkcs8(ReadOnlyMemory<byte> subjectPublicKeyInfo) =>
+    CreateFromSubjectPublicKeyInfo(subjectPublicKeyInfo);
 }

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/IKeyBase.cs

@@ -14,6 +14,13 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// Defines the base contract for all cryptographic keys, providing key type identification.
+/// </summary>
+/// <remarks>
+/// This interface serves as the foundation for both public and private key abstractions,
+/// enabling polymorphic key type handling across different cryptographic algorithms.
+/// </remarks>
 public interface IKeyBase
 {
     /// <summary>

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/IPrivateKey.cs

@@ -14,6 +14,14 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// Defines the contract for cryptographic private keys.
+/// </summary>
+/// <remarks>
+/// This interface extends <see cref="IKeyBase"/> to include private key-specific operations
+/// for PKCS#8 export and secure memory cleanup.
+/// Known implementations include <see cref="ECPrivateKey"/>, <see cref="RSAPrivateKey"/> and <see cref="Curve25519PrivateKey"/>,.
+/// </remarks>
 public interface IPrivateKey : IKeyBase
 {
     /// <summary>

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/IPrivateKeyExtensions.cs

@@ -16,15 +16,33 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+
+/// <summary>
+/// Extension methods for <see cref="IPrivateKey"/> to provide type-safe casting operations.
+/// </summary>
 public static class IPrivateKeyExtensions
 {
     /// <summary>
-    /// Casts the key to the specified type.
+    /// Safely casts an <see cref="IPrivateKey"/> instance to a specific derived type.
     /// </summary>
-    /// <param name="key"></param>
-    /// <typeparam name="T"></typeparam>
-    /// <returns></returns>
-    /// <exception cref="InvalidCastException"></exception>
+    /// <typeparam name="T">The target type that implements <see cref="IPrivateKey"/>.</typeparam>
+    /// <param name="key">The private key instance to cast.</param>
+    /// <returns>The private key cast to the specified type <typeparamref name="T"/>.</returns>
+    /// <exception cref="InvalidCastException">
+    /// Thrown when the <paramref name="key"/> cannot be cast to type <typeparamref name="T"/>.
+    /// The exception message includes both the source and target type names for debugging.
+    /// </exception>
+    /// <example>
+    /// <code>
+    /// IPrivateKey genericKey = GetPrivateKey();
+    /// RsaPrivateKey rsaKey = genericKey.Cast&lt;RsaPrivateKey&gt;();
+    /// // throws InvalidCastException if genericKey is not an RsaPrivateKey
+    /// </code>
+    /// </example>
+    /// <remarks>
+    /// This method provides a more explicit alternative to direct casting with clearer error messages.
+    /// Prefer this over unsafe casting operations when type safety is critical for cryptographic operations.
+    /// </remarks>
     public static T Cast<T>(this IPrivateKey key) where T : class, IPrivateKey =>
         key as T ?? throw new InvalidCastException($"Cannot cast {key.GetType()} to {typeof(T)}");
 }