docs(keys): add consistent docs for instances and bases of IPrivateKey and IPublicKey

Author: DennisDyallo

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>

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

@@ -19,6 +19,14 @@
 
 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;

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
     {
@@ -119,6 +120,12 @@ public static ECPrivateKey CreateFromPkcs8(ReadOnlyMemory<byte> encodedKey)
         }
 
         #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
 

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
 {

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)}");
 }

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/IPublicKey.cs

@@ -14,6 +14,17 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// Defines the contract for cryptographic public keys.
+/// </summary>
+/// <remarks>
+/// This interface extends <see cref="IKeyBase"/> to include public key-specific operations
+/// for X.509 SubjectPublicKeyInfo export.
+/// <para>
+/// Concrete implementations include <see cref="ECPublicKey"/>, <see cref="RSAPublicKey"/> and <see cref="Curve25519PublicKey"/>, each providing
+/// algorithm-specific public key handling and export mechanisms.
+/// </para>
+/// </remarks>
 public interface IPublicKey : IKeyBase
 {
     /// <summary>

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/PrivateKey.cs

@@ -16,6 +16,17 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// Abstract base class for private key implementations.
+/// </summary>
+/// <remarks>
+/// This class implements the standard .NET disposal pattern to ensure secure cleanup
+/// of sensitive cryptographic material and provides disposal state checking for derived classes.
+/// <para>
+/// Concrete implementations include <see cref="ECPrivateKey"/>, <see cref="RSAPrivateKey"/> and <see cref="Curve25519PrivateKey"/>,
+/// each providing algorithm-specific key handling and cryptographic operations.
+/// </para>
+/// </remarks>
 public abstract class PrivateKey : IPrivateKey, IDisposable
 {
     private bool _disposed;
@@ -43,6 +54,17 @@ public void Dispose()
         GC.SuppressFinalize(this);
     }
 
+    /// <summary>
+    /// Throws an <see cref="ObjectDisposedException"/> if this instance has been disposed.
+    /// </summary>
+    /// <exception cref="ObjectDisposedException">
+    /// Thrown when this method is called after the object has been disposed.
+    /// </exception>
+    /// <remarks>
+    /// This method should be called at the beginning of all public methods and properties
+    /// in derived classes to prevent operations on disposed cryptographic key material.
+    /// The exception message includes the concrete type name for debugging purposes.
+    /// </remarks>
     protected void ThrowIfDisposed()
     {
         if (_disposed)

Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/PublicKey.cs

@@ -14,11 +14,22 @@
 
 namespace Yubico.YubiKey.Cryptography;
 
+/// <summary>
+/// Abstract base class for public key implementations.
+/// </summary>
+/// <remarks>
+/// This class provides common structure for public key types, requiring derived classes
+/// to implement key type identification and X.509 export operations.
+/// <para>
+/// Concrete implementations include <see cref="ECPublicKey"/>, <see cref="RSAPublicKey"/> and <see cref="Curve25519PublicKey"/>, each providing
+/// algorithm-specific public key handling and export mechanisms.
+/// </para>
+/// </remarks>
 public abstract class PublicKey : IPublicKey
 {
     /// <inheritdoc />
     public abstract KeyType KeyType { get; }
-    
+
     /// <inheritdoc />
     public abstract byte[] ExportSubjectPublicKeyInfo();
 }