Skip to content

Commit fa74cd8

Browse files
reaperhulkclaude
andauthored
Add external mu (message representative) support for ML-DSA (#14979)
* Add external mu (message representative) support to ML-DSA Adds sign_mu()/verify_mu() to the ML-DSA private/public key classes for signing and verifying a precomputed 64-byte external mu, as defined in FIPS 204. mu already incorporates the public key and any context string, so these methods take no context. Per-backend mechanism: - OpenSSL 3.5+: set the integer "mu" signature parameter (OSSL_SIGNATURE_PARAM_MU) and pass mu through EVP_DigestSign. - AWS-LC: EVP_PKEY_sign/EVP_PKEY_verify, which use the "ExternalMu" format for ML-DSA keys. - BoringSSL: the EVP layer has no external-mu support, so use the low-level MLDSA*_{sign,verify}_message_representative functions. * Add external-mu known-answer tests for ML-DSA Derive mu from the existing deterministic pure KAT vectors (whose signatures come from an independent reference implementation) and check that verify_mu accepts each reference signature for its derived mu and rejects it for a tampered mu, across ML-DSA-44/65/87. https://claude.ai/code/session_01MmjphxZ6ookRpjUhQouKjf * Add ML-DSA external-mu Wycheproof tests The Wycheproof ML-DSA sign vectors carry a precomputed mu ('External Mu') for every case with a valid signature, including the mu-only 'Internal' cases NIST provides without an accompanying message or context. The signing tests skip those, so add external-mu tests that exercise verify_mu against the vector mu/signature pairs, confirm a perturbed mu fails, and (when msg/ctx are present) check the derived mu matches the vector. https://claude.ai/code/session_01MmjphxZ6ookRpjUhQouKjf * Build the ML-DSA mu OSSL_PARAM on the stack Replace the allocating OSSL_PARAM_BLD in set_mu with a fixed two-element OSSL_PARAM array constructed via OSSL_PARAM_construct_uint. The provider reads the 'mu' flag back with OSSL_PARAM_get_int, which accepts an unsigned integer param. This removes the builder's allocation-failure branch, which was unreachable in practice and left uncovered. https://claude.ai/code/session_01MmjphxZ6ookRpjUhQouKjf * Address ML-DSA external-mu review feedback - docs: describe how mu is computed and note there is no API to compute it yet, replacing the lower-value note about context. - backend: drop the redundant pyo3 signature attribute on verify_mu (no optional arguments, matching sign_mu). - openssl: note that the OpenSSL external-mu path must use digest-sign because ML-DSA does not implement EVP_PKEY_sign_init. - tests: clarify why the wycheproof external-mu helper filters on both the presence of mu and a valid result. https://claude.ai/code/session_01MmjphxZ6ookRpjUhQouKjf * Infer ML-DSA variant from the key in sign_mu/verify_mu sign_mu and verify_mu took the ML-DSA variant as a caller-supplied argument, which is unsound: nothing tied it to the key. Infer it from the pkey via MlDsaVariant::from_pkey instead, matching how sign/verify work, and drop the argument from both functions and their callers. Only the BoringSSL low-level path actually needs the variant. Also trim the sign_mu/verify_mu docs back to a concise note that there is no API to compute mu. https://claude.ai/code/session_01MmjphxZ6ookRpjUhQouKjf * Propagate ML-DSA public key parse errors in verify_mu The BoringSSL verify_mu path re-parses the raw public key, which was already validated when the key was constructed, so the parse cannot fail in practice. Returning Ok(false) on that impossible failure left three unreachable lines uncovered. Propagate the error with ? instead (as sign_mu already does), which keeps coverage at 100%. https://claude.ai/code/session_01MmjphxZ6ookRpjUhQouKjf * Address ML-DSA external-mu review feedback - Assert mu.len() == MLDSA_MU_BYTES in sign_mu/verify_mu. The BoringSSL path hands mu to the low-level API as a bare pointer read for a fixed length, so enforce it for soundness instead of trusting callers. - Use CBS_init to build the CBS in verify_mu rather than constructing the struct by hand, so we don't depend on its field layout. - Use std::ffi::c_uint for the mu OSSL_PARAM value. - Consolidate the wycheproof external-mu tests into a single test over all three vector files, resolving the key type from the vector's algorithm field. https://claude.ai/code/session_01MmjphxZ6ookRpjUhQouKjf * Fix mypy type for ML-DSA external-mu key class lookup mypy inferred the _MLDSA_PUBLIC_KEYS dict value as type[object] (the classes share no base), so public_key_class.from_public_bytes failed to type check. Annotate the dict with the union of the three public key types; add a __future__ annotations import so the annotation stays lazy on Python 3.9. https://claude.ai/code/session_01MmjphxZ6ookRpjUhQouKjf --------- Co-authored-by: Claude <[email protected]>
1 parent f594db3 commit fa74cd8

7 files changed

Lines changed: 646 additions & 3 deletions

File tree

‎CHANGELOG.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,10 @@ Changelog
6767
(not an instance) encodes an RSA subject public key in the certificate's
6868
``subjectPublicKeyInfo`` with the ``id-RSASSA-PSS`` OID and no
6969
parameters.
70+
* Added external mu (message representative) support to
71+
:doc:`/hazmat/primitives/asymmetric/mldsa` via the
72+
``sign_mu`` and ``verify_mu`` methods, which sign and verify a precomputed
73+
64-byte ``mu`` as defined in FIPS 204.
7074

7175
.. _v48-0-1:
7276

‎docs/hazmat/primitives/asymmetric/mldsa.rst‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,21 @@ Key interfaces
9595

9696
:raises ValueError: If the context is longer than 255 bytes.
9797

98+
.. method:: sign_mu(mu)
99+
100+
.. versionadded:: 49.0.0
101+
102+
Sign a precomputed ``mu`` (message representative) using ML-DSA-44,
103+
the "external mu" variant from FIPS 204. There is currently no API to
104+
compute ``mu``, so you must compute it yourself.
105+
106+
:param mu: The 64-byte message representative.
107+
:type mu: :term:`bytes-like`
108+
109+
:returns bytes: The signature (2420 bytes).
110+
111+
:raises ValueError: If ``mu`` is not 64 bytes.
112+
98113
.. method:: private_bytes(encoding, format, encryption_algorithm)
99114

100115
Allows serialization of the key to bytes. Encoding (
@@ -227,6 +242,25 @@ Key interfaces
227242
signature cannot be verified.
228243
:raises ValueError: If the context is longer than 255 bytes.
229244

245+
.. method:: verify_mu(signature, mu)
246+
247+
.. versionadded:: 49.0.0
248+
249+
Verify a signature over a precomputed ``mu`` (message representative),
250+
the "external mu" variant from FIPS 204. There is currently no API to
251+
compute ``mu``, so you must compute it yourself.
252+
253+
:param signature: The signature to verify.
254+
:type signature: :term:`bytes-like`
255+
256+
:param mu: The 64-byte message representative.
257+
:type mu: :term:`bytes-like`
258+
259+
:returns: None
260+
:raises cryptography.exceptions.InvalidSignature: Raised when the
261+
signature cannot be verified.
262+
:raises ValueError: If ``mu`` is not 64 bytes.
263+
230264
.. class:: MLDSA65PrivateKey
231265

232266
.. versionadded:: 47.0.0
@@ -281,6 +315,21 @@ Key interfaces
281315

282316
:raises ValueError: If the context is longer than 255 bytes.
283317

318+
.. method:: sign_mu(mu)
319+
320+
.. versionadded:: 49.0.0
321+
322+
Sign a precomputed ``mu`` (message representative) using ML-DSA-65,
323+
the "external mu" variant from FIPS 204. There is currently no API to
324+
compute ``mu``, so you must compute it yourself.
325+
326+
:param mu: The 64-byte message representative.
327+
:type mu: :term:`bytes-like`
328+
329+
:returns bytes: The signature (3309 bytes).
330+
331+
:raises ValueError: If ``mu`` is not 64 bytes.
332+
284333
.. method:: private_bytes(encoding, format, encryption_algorithm)
285334

286335
Allows serialization of the key to bytes. Encoding (
@@ -413,6 +462,25 @@ Key interfaces
413462
signature cannot be verified.
414463
:raises ValueError: If the context is longer than 255 bytes.
415464

465+
.. method:: verify_mu(signature, mu)
466+
467+
.. versionadded:: 49.0.0
468+
469+
Verify a signature over a precomputed ``mu`` (message representative),
470+
the "external mu" variant from FIPS 204. There is currently no API to
471+
compute ``mu``, so you must compute it yourself.
472+
473+
:param signature: The signature to verify.
474+
:type signature: :term:`bytes-like`
475+
476+
:param mu: The 64-byte message representative.
477+
:type mu: :term:`bytes-like`
478+
479+
:returns: None
480+
:raises cryptography.exceptions.InvalidSignature: Raised when the
481+
signature cannot be verified.
482+
:raises ValueError: If ``mu`` is not 64 bytes.
483+
416484
.. class:: MLDSA87PrivateKey
417485

418486
.. versionadded:: 47.0.0
@@ -467,6 +535,21 @@ Key interfaces
467535

468536
:raises ValueError: If the context is longer than 255 bytes.
469537

538+
.. method:: sign_mu(mu)
539+
540+
.. versionadded:: 49.0.0
541+
542+
Sign a precomputed ``mu`` (message representative) using ML-DSA-87,
543+
the "external mu" variant from FIPS 204. There is currently no API to
544+
compute ``mu``, so you must compute it yourself.
545+
546+
:param mu: The 64-byte message representative.
547+
:type mu: :term:`bytes-like`
548+
549+
:returns bytes: The signature (4627 bytes).
550+
551+
:raises ValueError: If ``mu`` is not 64 bytes.
552+
470553
.. method:: private_bytes(encoding, format, encryption_algorithm)
471554

472555
Allows serialization of the key to bytes. Encoding (
@@ -599,5 +682,24 @@ Key interfaces
599682
signature cannot be verified.
600683
:raises ValueError: If the context is longer than 255 bytes.
601684

685+
.. method:: verify_mu(signature, mu)
686+
687+
.. versionadded:: 49.0.0
688+
689+
Verify a signature over a precomputed ``mu`` (message representative),
690+
the "external mu" variant from FIPS 204. There is currently no API to
691+
compute ``mu``, so you must compute it yourself.
692+
693+
:param signature: The signature to verify.
694+
:type signature: :term:`bytes-like`
695+
696+
:param mu: The 64-byte message representative.
697+
:type mu: :term:`bytes-like`
698+
699+
:returns: None
700+
:raises cryptography.exceptions.InvalidSignature: Raised when the
701+
signature cannot be verified.
702+
:raises ValueError: If ``mu`` is not 64 bytes.
703+
602704

603705
.. _`FIPS 204`: https://csrc.nist.gov/pubs/fips/204/final

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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,18 @@ def verify(
5555
Verify the signature.
5656
"""
5757

58+
@abc.abstractmethod
59+
def verify_mu(
60+
self,
61+
signature: Buffer,
62+
mu: Buffer,
63+
) -> None:
64+
"""
65+
Verify the signature over a precomputed mu (message representative).
66+
67+
mu must be 64 bytes.
68+
"""
69+
5870
@abc.abstractmethod
5971
def __eq__(self, other: object) -> bool:
6072
"""
@@ -138,6 +150,15 @@ def sign(self, data: Buffer, context: Buffer | None = None) -> bytes:
138150
Signs the data.
139151
"""
140152

153+
@abc.abstractmethod
154+
def sign_mu(self, mu: Buffer) -> bytes:
155+
"""
156+
Signs a precomputed mu (message representative).
157+
158+
mu must be 64 bytes and already incorporates the context, so no
159+
context is accepted here.
160+
"""
161+
141162
@abc.abstractmethod
142163
def __copy__(self) -> MLDSA44PrivateKey:
143164
"""
@@ -198,6 +219,18 @@ def verify(
198219
Verify the signature.
199220
"""
200221

222+
@abc.abstractmethod
223+
def verify_mu(
224+
self,
225+
signature: Buffer,
226+
mu: Buffer,
227+
) -> None:
228+
"""
229+
Verify the signature over a precomputed mu (message representative).
230+
231+
mu must be 64 bytes.
232+
"""
233+
201234
@abc.abstractmethod
202235
def __eq__(self, other: object) -> bool:
203236
"""
@@ -281,6 +314,15 @@ def sign(self, data: Buffer, context: Buffer | None = None) -> bytes:
281314
Signs the data.
282315
"""
283316

317+
@abc.abstractmethod
318+
def sign_mu(self, mu: Buffer) -> bytes:
319+
"""
320+
Signs a precomputed mu (message representative).
321+
322+
mu must be 64 bytes and already incorporates the context, so no
323+
context is accepted here.
324+
"""
325+
284326
@abc.abstractmethod
285327
def __copy__(self) -> MLDSA65PrivateKey:
286328
"""
@@ -341,6 +383,18 @@ def verify(
341383
Verify the signature.
342384
"""
343385

386+
@abc.abstractmethod
387+
def verify_mu(
388+
self,
389+
signature: Buffer,
390+
mu: Buffer,
391+
) -> None:
392+
"""
393+
Verify the signature over a precomputed mu (message representative).
394+
395+
mu must be 64 bytes.
396+
"""
397+
344398
@abc.abstractmethod
345399
def __eq__(self, other: object) -> bool:
346400
"""
@@ -424,6 +478,15 @@ def sign(self, data: Buffer, context: Buffer | None = None) -> bytes:
424478
Signs the data.
425479
"""
426480

481+
@abc.abstractmethod
482+
def sign_mu(self, mu: Buffer) -> bytes:
483+
"""
484+
Signs a precomputed mu (message representative).
485+
486+
mu must be 64 bytes and already incorporates the context, so no
487+
context is accepted here.
488+
"""
489+
427490
@abc.abstractmethod
428491
def __copy__(self) -> MLDSA87PrivateKey:
429492
"""

0 commit comments

Comments
 (0)