Add external mu support to ML-DSA

This adds SignMu and VerifyMu to MLDsa, but does not provide an easy way for someone to obtain the mu value.

Like with OpenSSL version 3.5, that is, as we say, "an exercise left to the reader."  Although, a working example is present in the tests.

Author: bartonjs

src/libraries/Common/src/Interop/Unix/System.Security.Cryptography.Native/Interop.EvpPkey.MLDsa.cs

@@ -184,6 +184,65 @@ internal static bool MLDsaVerifyPreEncoded(
             }
         }
 
+        [LibraryImport(Libraries.CryptoNative)]
+        private static partial int CryptoNative_MLDsaSignExternalMu(
+            SafeEvpPKeyHandle pkey, IntPtr extraHandle,
+            ReadOnlySpan<byte> mu, int muLength,
+            Span<byte> destination, int destinationLength);
+
+        internal static void MLDsaSignExternalMu(
+            SafeEvpPKeyHandle pkey,
+            ReadOnlySpan<byte> mu,
+            Span<byte> destination)
+        {
+            const int Success = 1;
+            const int SigningFailure = 0;
+
+            int ret = CryptoNative_MLDsaSignExternalMu(
+                pkey, GetExtraHandle(pkey),
+                mu, mu.Length,
+                destination, destination.Length);
+
+            if (ret != Success)
+            {
+                Debug.Assert(ret == SigningFailure, $"Unexpected return value {ret} from {nameof(CryptoNative_MLDsaSignExternalMu)}.");
+                throw Interop.Crypto.CreateOpenSslCryptographicException();
+            }
+        }
+
+        [LibraryImport(Libraries.CryptoNative)]
+        private static partial int CryptoNative_MLDsaVerifyExternalMu(
+            SafeEvpPKeyHandle pkey, IntPtr extraHandle,
+            ReadOnlySpan<byte> mu, int muLength,
+            ReadOnlySpan<byte> signature, int signatureLength);
+
+        internal static bool MLDsaVerifyExternalMu(
+            SafeEvpPKeyHandle pkey,
+            ReadOnlySpan<byte> mu,
+            ReadOnlySpan<byte> signature)
+        {
+            const int ValidSignature = 1;
+            const int InvalidSignature = 0;
+
+            int ret = CryptoNative_MLDsaVerifyExternalMu(
+                pkey, GetExtraHandle(pkey),
+                mu, mu.Length,
+                signature, signature.Length);
+
+            if (ret == ValidSignature)
+            {
+                return true;
+            }
+            else if (ret == InvalidSignature)
+            {
+                return false;
+            }
+            else
+            {
+                throw Interop.Crypto.CreateOpenSslCryptographicException();
+            }
+        }
+
         [LibraryImport(Libraries.CryptoNative)]
         private static partial int CryptoNative_MLDsaExportSecretKey(SafeEvpPKeyHandle pkey, Span<byte> destination, int destinationLength);
 

src/libraries/Common/src/System/Security/Cryptography/Helpers.cs

@@ -264,5 +264,18 @@ internal static void ThrowIfAsnInvalidLength(ReadOnlySpan<byte> data)
                 throw new CryptographicException(SR.Cryptography_Der_Invalid_Encoding);
             }
         }
+
+#if !BUILDING_PKCS
+        internal static void ThrowIfDestinationWrongLength(
+            Span<byte> destination,
+            int expectedLength,
+            [System.Runtime.CompilerServices.CallerArgumentExpression(nameof(destination))] string? paramName = null)
+        {
+            if (destination.Length != expectedLength)
+            {
+                throw new ArgumentException(SR.Format(SR.Argument_DestinationImprecise, expectedLength), paramName);
+            }
+        }
+#endif
     }
 }

src/libraries/Common/src/System/Security/Cryptography/MLDsa.cs

@@ -120,14 +120,7 @@ public void Dispose()
         /// </exception>
         public void SignData(ReadOnlySpan<byte> data, Span<byte> destination, ReadOnlySpan<byte> context = default)
         {
-            int signatureSizeInBytes = Algorithm.SignatureSizeInBytes;
-
-            if (destination.Length != signatureSizeInBytes)
-            {
-                throw new ArgumentException(
-                    SR.Format(SR.Argument_DestinationImprecise, signatureSizeInBytes),
-                    nameof(destination));
-            }
+            Helpers.ThrowIfDestinationWrongLength(destination, Algorithm.SignatureSizeInBytes);
 
             if (context.Length > MaxContextLength)
             {
@@ -309,13 +302,7 @@ public bool VerifyData(byte[] data, byte[] signature, byte[]? context = default)
         public void SignPreHash(ReadOnlySpan<byte> hash, Span<byte> destination, string hashAlgorithmOid, ReadOnlySpan<byte> context = default)
         {
             ArgumentNullException.ThrowIfNull(hashAlgorithmOid);
-
-            if (destination.Length != Algorithm.SignatureSizeInBytes)
-            {
-                throw new ArgumentException(
-                    SR.Format(SR.Argument_DestinationImprecise, Algorithm.SignatureSizeInBytes),
-                    nameof(destination));
-            }
+            Helpers.ThrowIfDestinationWrongLength(destination, Algorithm.SignatureSizeInBytes);
 
             if (context.Length > MaxContextLength)
             {
@@ -507,6 +494,155 @@ public bool VerifyPreHash(byte[] hash, byte[] signature, string hashAlgorithmOid
                 new ReadOnlySpan<byte>(context));
         }
 
+        /// <inheritdoc cref="SignMu(ReadOnlySpan{byte})"/>
+        /// <exception cref="ArgumentNullException"><paramref name="externalMu"/> is <see langword="null"/>.</exception>
+        public byte[] SignMu(byte[] externalMu)
+        {
+            ArgumentNullException.ThrowIfNull(externalMu);
+
+            return SignMu(new ReadOnlySpan<byte>(externalMu));
+        }
+
+        /// <summary>
+        ///   Signs the specified externally computed signature mu (&#x3BC;) value.
+        /// </summary>
+        /// <param name="externalMu">
+        ///   The signature mu value to sign.
+        /// </param>
+        /// <returns>
+        ///   ML-DSA signature for the specified mu value.
+        /// </returns>
+        /// <exception cref="ArgumentException">
+        ///   The buffer in <paramref name="externalMu"/> is the incorrect length for the signature mu value.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   This instance has been disposed.
+        /// </exception>
+        /// <exception cref="CryptographicException">
+        ///   <para>The instance represents only a public key.</para>
+        ///   <para>-or-</para>
+        ///   <para>An error occurred while signing the hash.</para>
+        /// </exception>
+        /// <exception cref="PlatformNotSupportedException">
+        ///   The current platform does not support signing with an externally computed mu value.
+        /// </exception>
+        /// <seealso cref="VerifyMu(byte[], byte[])"/>
+        public byte[] SignMu(ReadOnlySpan<byte> externalMu)
+        {
+            byte[] destination = new byte[Algorithm.SignatureSizeInBytes];
+            SignMu(externalMu, destination.AsSpan());
+            return destination;
+        }
+
+        /// <summary>
+        ///   Signs the specified externally computed signature mu (&#x3BC;) value,
+        ///   writing the signature into the provided buffer.
+        /// </summary>
+        /// <param name="externalMu">
+        ///   The signature mu value to sign.
+        /// </param>
+        /// <param name="destination">
+        ///   The buffer to receive the signature. Its length must be exactly
+        ///   <see cref="MLDsaAlgorithm.SignatureSizeInBytes"/>.
+        /// </param>
+        /// <exception cref="ArgumentException">
+        ///   <para>
+        ///     The buffer in <paramref name="externalMu"/> is the incorrect length for the signature mu value.
+        ///   </para>
+        ///   <para>-or-</para>
+        ///   <para>
+        ///     The buffer in <paramref name="destination"/> is the incorrect length to receive the signature.
+        ///   </para>
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   This instance has been disposed.
+        /// </exception>
+        /// <exception cref="CryptographicException">
+        ///   <para>The instance represents only a public key.</para>
+        ///   <para>-or-</para>
+        ///   <para>An error occurred while signing the hash.</para>
+        /// </exception>
+        /// <exception cref="PlatformNotSupportedException">
+        ///   The current platform does not support signing with an externally computed mu value.
+        /// </exception>
+        /// <seealso cref="VerifyMu(ReadOnlySpan{byte}, ReadOnlySpan{byte})"/>
+        public void SignMu(ReadOnlySpan<byte> externalMu, Span<byte> destination)
+        {
+            if (externalMu.Length != Algorithm.MuSizeInBytes)
+                throw new ArgumentException(SR.Argument_MLDsaMuInvalidLength, nameof(externalMu));
+
+            Helpers.ThrowIfDestinationWrongLength(destination, Algorithm.SignatureSizeInBytes);
+            ThrowIfDisposed();
+
+            SignMuCore(externalMu, destination);
+        }
+
+        /// <summary>
+        ///   When overridden in a derived class, computes the remainder of the signature from the
+        ///   precomputed mu (&#x3BC;) value, writing it into the provided buffer.
+        /// </summary>
+        /// <param name="externalMu">
+        ///   The signature mu value to sign.
+        /// </param>
+        /// <param name="destination">
+        ///   The buffer to receive the signature, which will always be the exactly correct size for the algorithm.
+        /// </param>
+        /// <exception cref="CryptographicException">
+        ///   An error occurred while computing the signature.
+        /// </exception>
+        protected abstract void SignMuCore(ReadOnlySpan<byte> externalMu, Span<byte> destination);
+
+        /// <inheritdoc cref="VerifyMu(ReadOnlySpan{byte}, ReadOnlySpan{byte})"/>
+        /// <exception cref="ArgumentNullException">
+        ///   <paramref name="externalMu"/> or <paramref name="signature"/> is <see langword="null"/>.
+        /// </exception>
+        public bool VerifyMu(byte[] externalMu, byte[] signature)
+        {
+            ArgumentNullException.ThrowIfNull(externalMu);
+            ArgumentNullException.ThrowIfNull(signature);
+
+            return VerifyMu(new ReadOnlySpan<byte>(externalMu), new ReadOnlySpan<byte>(signature));
+        }
+
+        /// <summary>
+        ///   Verifies that a digital signature is valid for the provided externally computed signature mu (&#x3BC;) value.
+        /// </summary>
+        /// <param name="externalMu">The signature mu value.</param>
+        /// <param name="signature">The signature to verify.</param>
+        /// <returns>
+        ///   <see langword="true"/> if the digital signature is valid for the provided mu value;
+        ///   otherwise, <see langword="false"/>.
+        /// </returns>
+        /// <exception cref="ObjectDisposedException">
+        ///   This instance has been disposed.
+        /// </exception>
+        /// <exception cref="CryptographicException">An error occurred while verifying the mu value.</exception>
+        /// <exception cref="PlatformNotSupportedException">
+        ///   The current platform does not support verification with an externally computed mu value.
+        /// </exception>
+        public bool VerifyMu(ReadOnlySpan<byte> externalMu, ReadOnlySpan<byte> signature)
+        {
+            if (externalMu.Length != Algorithm.MuSizeInBytes || signature.Length != Algorithm.SignatureSizeInBytes)
+            {
+                return false;
+            }
+
+            ThrowIfDisposed();
+
+            return VerifyMuCore(externalMu, signature);
+        }
+
+        /// <summary>
+        ///   When overridden in a derived class,
+        ///   verifies that a digital signature is valid for the provided externally computed signature mu (&#x3BC;) value.
+        /// </summary>
+        /// <param name="externalMu">The signature mu value.</param>
+        /// <param name="signature">The signature to verify.</param>
+        /// <returns>
+        ///   <see langword="true"/> if the mu value is valid; otherwise, <see langword="false"/>.
+        /// </returns>
+        protected abstract bool VerifyMuCore(ReadOnlySpan<byte> externalMu, ReadOnlySpan<byte> signature);
+
         /// <summary>
         ///   Exports the public-key portion of the current key in the X.509 SubjectPublicKeyInfo format.
         /// </summary>
@@ -1063,15 +1199,7 @@ public byte[] ExportMLDsaPublicKey()
         /// </remarks>
         public void ExportMLDsaPublicKey(Span<byte> destination)
         {
-            int publicKeySizeInBytes = Algorithm.PublicKeySizeInBytes;
-
-            if (destination.Length != publicKeySizeInBytes)
-            {
-                throw new ArgumentException(
-                    SR.Format(SR.Argument_DestinationImprecise, publicKeySizeInBytes),
-                    nameof(destination));
-            }
-
+            Helpers.ThrowIfDestinationWrongLength(destination, Algorithm.PublicKeySizeInBytes);
             ThrowIfDisposed();
 
             ExportMLDsaPublicKeyCore(destination);
@@ -1113,15 +1241,7 @@ public byte[] ExportMLDsaSecretKey()
         /// </exception>
         public void ExportMLDsaSecretKey(Span<byte> destination)
         {
-            int secretKeySizeInBytes = Algorithm.SecretKeySizeInBytes;
-
-            if (destination.Length != secretKeySizeInBytes)
-            {
-                throw new ArgumentException(
-                    SR.Format(SR.Argument_DestinationImprecise, secretKeySizeInBytes),
-                    nameof(destination));
-            }
-
+            Helpers.ThrowIfDestinationWrongLength(destination, Algorithm.SecretKeySizeInBytes);
             ThrowIfDisposed();
 
             ExportMLDsaSecretKeyCore(destination);
@@ -1161,14 +1281,7 @@ public byte[] ExportMLDsaPrivateSeed()
         /// </exception>
         public void ExportMLDsaPrivateSeed(Span<byte> destination)
         {
-            int privateSeedSizeInBytes = Algorithm.PrivateSeedSizeInBytes;
-            if (destination.Length != privateSeedSizeInBytes)
-            {
-                throw new ArgumentException(
-                    SR.Format(SR.Argument_DestinationImprecise, privateSeedSizeInBytes),
-                    nameof(destination));
-            }
-
+            Helpers.ThrowIfDestinationWrongLength(destination, Algorithm.PrivateSeedSizeInBytes);
             ThrowIfDisposed();
 
             ExportMLDsaPrivateSeedCore(destination);

src/libraries/Common/src/System/Security/Cryptography/MLDsaAlgorithm.cs

@@ -53,6 +53,14 @@ public sealed class MLDsaAlgorithm : IEquatable<MLDsaAlgorithm>
         /// </value>
         public int SignatureSizeInBytes { get; }
 
+        /// <summary>
+        ///   Gets the size, in bytes, of the mu (&#x3BC;) value for the current ML-DSA algorithm.
+        /// </summary>
+        /// <value>
+        ///   The size, in bytes, of the mu (&#x3BC;) value for the current ML-DSA algorithm.
+        /// </value>
+        public int MuSizeInBytes => 64;
+
         internal string Oid { get; }
         internal int LambdaCollisionStrength { get; }
 

src/libraries/Common/src/System/Security/Cryptography/MLDsaCng.cs

@@ -48,6 +48,14 @@ public MLDsaCng(CngKey key)
             _key = duplicateKey;
         }
 
+        /// <inheritdoc />
+        protected override void SignMuCore(ReadOnlySpan<byte> mu, Span<byte> destination) =>
+            throw new PlatformNotSupportedException();
+
+        /// <inheritdoc />
+        protected override bool VerifyMuCore(ReadOnlySpan<byte> mu, ReadOnlySpan<byte> signature) =>
+            throw new PlatformNotSupportedException();
+
         private static MLDsaAlgorithm AlgorithmFromHandleWithPlatformCheck(CngKey key, out CngKey duplicateKey)
         {
             if (!Helpers.IsOSPlatformWindows)

src/libraries/Common/src/System/Security/Cryptography/MLDsaImplementation.NotSupported.cs

@@ -31,6 +31,12 @@ protected override void SignPreHashCore(ReadOnlySpan<byte> hash, ReadOnlySpan<by
         protected override bool VerifyPreHashCore(ReadOnlySpan<byte> hash, ReadOnlySpan<byte> context, string hashAlgorithmOid, ReadOnlySpan<byte> signature) =>
             throw new PlatformNotSupportedException();
 
+        protected override void SignMuCore(ReadOnlySpan<byte> mu, Span<byte> destination) =>
+            throw new PlatformNotSupportedException();
+
+        protected override bool VerifyMuCore(ReadOnlySpan<byte> mu, ReadOnlySpan<byte> signature) =>
+            throw new PlatformNotSupportedException();
+
         protected override void ExportMLDsaPublicKeyCore(Span<byte> destination) =>
             throw new PlatformNotSupportedException();
 

src/libraries/Common/src/System/Security/Cryptography/MLDsaImplementation.Windows.cs

@@ -91,6 +91,12 @@ protected override bool VerifyPreHashCore(
             return Interop.BCrypt.BCryptVerifySignaturePqcPreHash(_key, hash, hashAlgorithmIdentifier, context, signature);
         }
 
+        protected override void SignMuCore(ReadOnlySpan<byte> externalMu, Span<byte> destination) =>
+            throw new PlatformNotSupportedException();
+
+        protected override bool VerifyMuCore(ReadOnlySpan<byte> externalMu, ReadOnlySpan<byte> signature) =>
+            throw new PlatformNotSupportedException();
+
         internal static partial MLDsaImplementation GenerateKeyImpl(MLDsaAlgorithm algorithm)
         {
             Debug.Assert(SupportsAny());