Add external mu (message representative) support for ML-DSA

CHANGELOG.rst

@@ -34,6 +34,10 @@ Changelog
   registers an :class:`enum.Enum` subclass as an ASN.1 value set: members
   are encoded as their underlying value, and decoding fails if the decoded
   value does not match one of the declared members.
+* Added external mu (message representative) support to
+  :doc:`/hazmat/primitives/asymmetric/mldsa` via the
+  ``sign_mu`` and ``verify_mu`` methods, which sign and verify a precomputed
+  64-byte ``mu`` as defined in FIPS 204.
 
 .. _v48-0-0:
 

Cargo.toml

@@ -36,3 +36,9 @@ self_cell = "1"
 
 [profile.release]
 overflow-checks = true
+
+[patch.crates-io]
+# Temporarily track rust-openssl master for the BoringSSL ML-DSA bindgen
+# additions (mldsa.h) until a release including them is published.
+openssl = { git = "https://github.com/sfackler/rust-openssl", branch = "master" }
+openssl-sys = { git = "https://github.com/sfackler/rust-openssl", branch = "master" }

docs/hazmat/primitives/asymmetric/mldsa.rst

@@ -95,6 +95,21 @@ Key interfaces
 
         :raises ValueError: If the context is longer than 255 bytes.
 
+    .. method:: sign_mu(mu)
+
+        .. versionadded:: 49.0.0
+
+        Sign a precomputed ``mu`` (message representative) using ML-DSA-44,
+        the "external mu" variant from FIPS 204. ``mu`` already incorporates
+        the public key and any context string, so no context is accepted here.
+
+        :param mu: The 64-byte message representative.
+        :type mu: :term:`bytes-like`
+
+        :returns bytes: The signature (2420 bytes).
+
+        :raises ValueError: If ``mu`` is not 64 bytes.
+
     .. method:: private_bytes(encoding, format, encryption_algorithm)
 
         Allows serialization of the key to bytes. Encoding (
@@ -227,6 +242,25 @@ Key interfaces
             signature cannot be verified.
         :raises ValueError: If the context is longer than 255 bytes.
 
+    .. method:: verify_mu(signature, mu)
+
+        .. versionadded:: 49.0.0
+
+        Verify a signature over a precomputed ``mu`` (message representative),
+        the "external mu" variant from FIPS 204. ``mu`` already incorporates
+        the public key and any context string.
+
+        :param signature: The signature to verify.
+        :type signature: :term:`bytes-like`
+
+        :param mu: The 64-byte message representative.
+        :type mu: :term:`bytes-like`
+
+        :returns: None
+        :raises cryptography.exceptions.InvalidSignature: Raised when the
+            signature cannot be verified.
+        :raises ValueError: If ``mu`` is not 64 bytes.
+
 .. class:: MLDSA65PrivateKey
 
     .. versionadded:: 47.0.0
@@ -281,6 +315,21 @@ Key interfaces
 
         :raises ValueError: If the context is longer than 255 bytes.
 
+    .. method:: sign_mu(mu)
+
+        .. versionadded:: 49.0.0
+
+        Sign a precomputed ``mu`` (message representative) using ML-DSA-65,
+        the "external mu" variant from FIPS 204. ``mu`` already incorporates
+        the public key and any context string, so no context is accepted here.
+
+        :param mu: The 64-byte message representative.
+        :type mu: :term:`bytes-like`
+
+        :returns bytes: The signature (3309 bytes).
+
+        :raises ValueError: If ``mu`` is not 64 bytes.
+
     .. method:: private_bytes(encoding, format, encryption_algorithm)
 
         Allows serialization of the key to bytes. Encoding (
@@ -413,6 +462,25 @@ Key interfaces
             signature cannot be verified.
         :raises ValueError: If the context is longer than 255 bytes.
 
+    .. method:: verify_mu(signature, mu)
+
+        .. versionadded:: 49.0.0
+
+        Verify a signature over a precomputed ``mu`` (message representative),
+        the "external mu" variant from FIPS 204. ``mu`` already incorporates
+        the public key and any context string.
+
+        :param signature: The signature to verify.
+        :type signature: :term:`bytes-like`
+
+        :param mu: The 64-byte message representative.
+        :type mu: :term:`bytes-like`
+
+        :returns: None
+        :raises cryptography.exceptions.InvalidSignature: Raised when the
+            signature cannot be verified.
+        :raises ValueError: If ``mu`` is not 64 bytes.
+
 .. class:: MLDSA87PrivateKey
 
     .. versionadded:: 47.0.0
@@ -467,6 +535,21 @@ Key interfaces
 
         :raises ValueError: If the context is longer than 255 bytes.
 
+    .. method:: sign_mu(mu)
+
+        .. versionadded:: 49.0.0
+
+        Sign a precomputed ``mu`` (message representative) using ML-DSA-87,
+        the "external mu" variant from FIPS 204. ``mu`` already incorporates
+        the public key and any context string, so no context is accepted here.
+
+        :param mu: The 64-byte message representative.
+        :type mu: :term:`bytes-like`
+
+        :returns bytes: The signature (4627 bytes).
+
+        :raises ValueError: If ``mu`` is not 64 bytes.
+
     .. method:: private_bytes(encoding, format, encryption_algorithm)
 
         Allows serialization of the key to bytes. Encoding (
@@ -599,5 +682,24 @@ Key interfaces
             signature cannot be verified.
         :raises ValueError: If the context is longer than 255 bytes.
 
+    .. method:: verify_mu(signature, mu)
+
+        .. versionadded:: 49.0.0
+
+        Verify a signature over a precomputed ``mu`` (message representative),
+        the "external mu" variant from FIPS 204. ``mu`` already incorporates
+        the public key and any context string.
+
+        :param signature: The signature to verify.
+        :type signature: :term:`bytes-like`
+
+        :param mu: The 64-byte message representative.
+        :type mu: :term:`bytes-like`
+
+        :returns: None
+        :raises cryptography.exceptions.InvalidSignature: Raised when the
+            signature cannot be verified.
+        :raises ValueError: If ``mu`` is not 64 bytes.
+
 
 .. _`FIPS 204`: https://csrc.nist.gov/pubs/fips/204/final

src/cryptography/hazmat/primitives/asymmetric/mldsa.py

@@ -55,6 +55,18 @@ def verify(
         Verify the signature.
         """
 
+    @abc.abstractmethod
+    def verify_mu(
+        self,
+        signature: Buffer,
+        mu: Buffer,
+    ) -> None:
+        """
+        Verify the signature over a precomputed mu (message representative).
+
+        mu must be 64 bytes.
+        """
+
     @abc.abstractmethod
     def __eq__(self, other: object) -> bool:
         """
@@ -138,6 +150,15 @@ def sign(self, data: Buffer, context: Buffer | None = None) -> bytes:
         Signs the data.
         """
 
+    @abc.abstractmethod
+    def sign_mu(self, mu: Buffer) -> bytes:
+        """
+        Signs a precomputed mu (message representative).
+
+        mu must be 64 bytes and already incorporates the context, so no
+        context is accepted here.
+        """
+
     @abc.abstractmethod
     def __copy__(self) -> MLDSA44PrivateKey:
         """
@@ -198,6 +219,18 @@ def verify(
         Verify the signature.
         """
 
+    @abc.abstractmethod
+    def verify_mu(
+        self,
+        signature: Buffer,
+        mu: Buffer,
+    ) -> None:
+        """
+        Verify the signature over a precomputed mu (message representative).
+
+        mu must be 64 bytes.
+        """
+
     @abc.abstractmethod
     def __eq__(self, other: object) -> bool:
         """
@@ -281,6 +314,15 @@ def sign(self, data: Buffer, context: Buffer | None = None) -> bytes:
         Signs the data.
         """
 
+    @abc.abstractmethod
+    def sign_mu(self, mu: Buffer) -> bytes:
+        """
+        Signs a precomputed mu (message representative).
+
+        mu must be 64 bytes and already incorporates the context, so no
+        context is accepted here.
+        """
+
     @abc.abstractmethod
     def __copy__(self) -> MLDSA65PrivateKey:
         """
@@ -341,6 +383,18 @@ def verify(
         Verify the signature.
         """
 
+    @abc.abstractmethod
+    def verify_mu(
+        self,
+        signature: Buffer,
+        mu: Buffer,
+    ) -> None:
+        """
+        Verify the signature over a precomputed mu (message representative).
+
+        mu must be 64 bytes.
+        """
+
     @abc.abstractmethod
     def __eq__(self, other: object) -> bool:
         """
@@ -424,6 +478,15 @@ def sign(self, data: Buffer, context: Buffer | None = None) -> bytes:
         Signs the data.
         """
 
+    @abc.abstractmethod
+    def sign_mu(self, mu: Buffer) -> bytes:
+        """
+        Signs a precomputed mu (message representative).
+
+        mu must be 64 bytes and already incorporates the context, so no
+        context is accepted here.
+        """
+
     @abc.abstractmethod
     def __copy__(self) -> MLDSA87PrivateKey:
         """