diff --git a/src/libraries/Common/src/System/Security/Cryptography/MLDsa.cs b/src/libraries/Common/src/System/Security/Cryptography/MLDsa.cs index e6f6f0bbdab0ea..f5d299825228a0 100644 --- a/src/libraries/Common/src/System/Security/Cryptography/MLDsa.cs +++ b/src/libraries/Common/src/System/Security/Cryptography/MLDsa.cs @@ -14,10 +14,15 @@ namespace System.Security.Cryptography /// Represents an ML-DSA key. /// /// - /// Developers are encouraged to program against the base class, - /// rather than any specific derived class. - /// The derived classes are intended for interop with the underlying system - /// cryptographic libraries. + /// + /// This algorithm is specified by FIPS-204. + /// + /// + /// Developers are encouraged to program against the base class, + /// rather than any specific derived class. + /// The derived classes are intended for interop with the underlying system + /// cryptographic libraries. + /// /// [Experimental(Experimentals.PostQuantumCryptographyDiagId, UrlFormat = Experimentals.SharedUrlFormat)] public abstract partial class MLDsa : IDisposable @@ -39,6 +44,9 @@ public abstract partial class MLDsa : IDisposable /// /// Gets the specific ML-DSA algorithm for this key. /// + /// + /// The specific ML-DSA algorithm for this key. + /// public MLDsaAlgorithm Algorithm { get; } private bool _disposed; @@ -48,6 +56,9 @@ public abstract partial class MLDsa : IDisposable /// /// The specific ML-DSA algorithm for this key. /// + /// + /// is . + /// protected MLDsa(MLDsaAlgorithm algorithm) { ArgumentNullException.ThrowIfNull(algorithm); @@ -79,7 +90,7 @@ public void Dispose() } /// - /// Sign the specified data, writing the signature into the provided buffer. + /// Signs the specified data, writing the signature into the provided buffer. /// /// /// The data to sign. diff --git a/src/libraries/Common/src/System/Security/Cryptography/MLKem.cs b/src/libraries/Common/src/System/Security/Cryptography/MLKem.cs index 478d8be5a6d072..6230f02f81241b 100644 --- a/src/libraries/Common/src/System/Security/Cryptography/MLKem.cs +++ b/src/libraries/Common/src/System/Security/Cryptography/MLKem.cs @@ -40,10 +40,10 @@ public abstract partial class MLKem : IDisposable public static bool IsSupported => MLKemImplementation.IsSupported; /// - /// Gets the algorithm of the current instance. + /// Gets the specific ML-KEM algorithm for this key. /// /// - /// A value representing the ML-KEM algorithm. + /// The specific ML-KEM algorithm for this key. /// public MLKemAlgorithm Algorithm { get; } @@ -183,6 +183,14 @@ public void Encapsulate(out byte[] ciphertext, out byte[] sharedSecret) /// /// The buffer to receive the shared secret. /// + /// + /// Decapsulation can only decapsulate a shared secret created with the the decapsulation key's + /// corresponding encapsulation key. If a different key is used, ML-KEM performs implicit rejection. + /// Implicit rejection means an error will not be returned. Instead, the shared secret will be a + /// deterministic but incorrect result. + /// Detecting incorrect key use is a concern for consumers of the ML-KEM algorithm. + /// For more information, see FIPS 203, Section 6.3. + /// /// /// An error occurred during decapsulation. /// @@ -219,6 +227,14 @@ public void Decapsulate(ReadOnlySpan ciphertext, Span sharedSecret) /// /// The shared secret. /// + /// + /// Decapsulation can only decapsulate a shared secret created with the the decapsulation key's + /// corresponding encapsulation key. If a different key is used, ML-KEM performs implicit rejection. + /// Implicit rejection means an error will not be returned. Instead, the shared secret will be a + /// deterministic but incorrect result. + /// Detecting incorrect key use is a concern for consumers of the ML-KEM algorithm. + /// For more information, see FIPS 203, Section 6.3. + /// /// /// An error occurred during decapsulation. /// diff --git a/src/libraries/Common/src/System/Security/Cryptography/SlhDsa.cs b/src/libraries/Common/src/System/Security/Cryptography/SlhDsa.cs index 40f3057e88bb7f..004447d5db5d79 100644 --- a/src/libraries/Common/src/System/Security/Cryptography/SlhDsa.cs +++ b/src/libraries/Common/src/System/Security/Cryptography/SlhDsa.cs @@ -14,10 +14,15 @@ namespace System.Security.Cryptography /// Represents an SLH-DSA key. /// /// - /// Developers are encouraged to program against the SlhDsa base class, - /// rather than any specific derived class. - /// The derived classes are intended for interop with the underlying system - /// cryptographic libraries. + /// + /// This algorithm is specified by FIPS-205. + /// + /// + /// Developers are encouraged to program against the base class, + /// rather than any specific derived class. + /// The derived classes are intended for interop with the underlying system + /// cryptographic libraries. + /// /// [Experimental(Experimentals.PostQuantumCryptographyDiagId, UrlFormat = Experimentals.SharedUrlFormat)] public abstract partial class SlhDsa : IDisposable @@ -62,9 +67,6 @@ protected SlhDsa(SlhDsaAlgorithm algorithm) Algorithm = algorithm; } - /// - /// Throws if the current instance is disposed. - /// private protected void ThrowIfDisposed() => ObjectDisposedException.ThrowIf(_disposed, typeof(SlhDsa)); ///