ML-DSA support

[TaaviE]

Which crate or crates do you plan on using or would like people to use for implementing ML-DSA (and ML-KEM) support for pyca/cryptography?

I could just do it in a draft PR for people to be able to experiment, using a good library in Python (and Rust).

[alex]

Please see:

1. https://cryptography.io/en/latest/statements/state-of-openssl/
2. ML-KEM API Design #12824

Our plan is to expose ML-KEM and ML-DSA for users on AWS-LC, LibreSSL, and BoringSSL for the time being.

We have no intention of using ring, so I'm not sure why you're mentioning it?

Please note that working on ML-DSA/ML-KEM is as substantial undertaking.

[TaaviE]

We have no intention of using ring, so I'm not sure why you're mentioning it?

Ah, my bad, I confused x509_certificate with cryptography_x509 and its stuff. It's really easy to confuse things if two ecosystems have to be bridged. Let me scratch all that.

[TaaviE]

I did see that other issue, but it's more about ML-KEM (which is a bit more complex, especially when its uses are included) than ML-DSA? Latter being a bit less involved at least for verification parts.

So the plan is to deliver that support on top of those libraries (and their bindings)? My end-motivation is to have it working in a WASM environment, so native libraries and such make things rather difficult.

[Tarnum-tst]

What is the goal of this issue?

ML-DSA & ML-KEM are already supported in Abbra's cryptography branches, read the linked topic.

[TaaviE]

@Tarnum-tst To understand what's the current plan specifically in terms of underlying libraries chosen or going to be chosen.

What some external branches contain is not authoritative, especially as they might undergo significant changes before being merged. (Nor is anything relying on or somehow pulling in OSSL usable for me.)

[DarkaMaul]

Update 1: Following @reaperhulk comment, the new preferred recommended way is to have distinct classes.

---

I would like to work on this issue.

Right now, the branch from abbra adds the support for MLDSA{44,65,87} using OpenSSL as the backend. However, the maintainers have expressed¹² their preference for a more focused approach that targets another backend first.

My current working plan is to focus on adding MLDSA65 support for BoringSSL.

• First PR: adding the tests vectors from NIST ACPV
• Use this issue to discuss an API that will be used by all backends
• Follow up with the implementation

API Design

MLDSA Parameter Set

    class MLDSAParameterSet(metaclass=abc.ABCMeta):
        @property
        @abc.abstractmethod
        def name(self) -> str:
            """
            The name of the parameter
            """

    class MLDSA65(MLDSAParameterSet):
        name = "ML-DSA-65"

This matches the Elleptic curve implementation instead of the less generic Ed25519PrivateKey.

Private Key

class MLDSA65PrivateKey(metaclass=abc.ABCMeta):

    @classmethod
    def generate(cls) -> MLDSA65PrivateKey:
        """
        Generate a new ML-DSA-65 private key.
        """

    @classmethod
    def from_private_bytes(cls, data: Buffer) -> MLDSA65PrivateKey:
        """
        Load a private key from its raw byte representation.
        """

    @abc.abstractmethod
    def public_key(self) -> MLDSA65PublicKey:
        """
        The MLDSA65PublicKey derived from this private key.
        """

    @abc.abstractmethod
    def sign(self, data: Buffer) -> bytes:
        """
        Sign the data. Returns a signature as bytes.
        """

    @abc.abstractmethod
    def private_bytes(
        self,
        encoding: Encoding,
        format: PrivateFormat,
        encryption_algorithm: KeySerializationEncryption,
    ) -> bytes:
        """
        Serialize the key.
        """

    @abc.abstractmethod
    def private_bytes_raw(self) -> bytes:
        """
        The raw bytes of the private key.
        """

    @abc.abstractmethod
    def __copy__(self) -> MLDSA65PrivateKey: ...

    @abc.abstractmethod
    def __deepcopy__(self, memo: dict) -> MLDSA65PrivateKey: ...

Question here:

In EC, we have a standalone generate_private_key method that is outside of the EllipticCurvePrivateKey class. The design above uses a classmethod - but there is maybe a reason I'm not seing that prevents from doing it? Answered by having different classes.

Public Key

class MLDSA65PublicKey(metaclass=abc.ABCMeta):

    @classmethod
    def from_public_bytes(cls, data: bytes) -> MLDSA65PublicKey:
        """
        Load a public key from its raw byte representation.
        """

    @abc.abstractmethod
    def verify(self, signature: Buffer, data: Buffer) -> None:
        """
        Verify the signature. Raises InvalidSignature on failure.
        """

    @abc.abstractmethod
    def public_bytes(
        self,
        encoding: Encoding,
        format: PublicFormat,
    ) -> bytes:
        """
        Serialize the key
        """

    @abc.abstractmethod
    def public_bytes_raw(self) -> bytes:
        """
        The raw bytes of the public key.
        """

    @abc.abstractmethod
    def __eq__(self, other: object) -> bool: ...

    @abc.abstractmethod
    def __copy__(self) -> MLDSA65PublicKey: ...

    @abc.abstractmethod
    def __deepcopy__(self, memo: dict) -> MLDSA65PublicKey: ...

Do we really need the public_bytes_raw method here?

Usage

from cryptography.hazmat.primitives.asymmetric.ml_dsa import (
    MLDSA65PrivateKey, MLDSA65PublicKey,
)

# Generate
private_key = MLDSA65PrivateKey.generate()

# Sign
signature = private_key.sign(b"message")

# Verify
public_key = private_key.public_key()
public_key.verify(signature, b"message")

Other questions

1. FIPS 204 allows an optional context string passed to sign/verify. Should the initial API expose this?
2. FIPS 204 Section 5.4 ³ defines a pre-hash variant. I was planning to not support it initially, but maybe that's not a good choice?

Footnotes

1. https://cryptography.io/en/latest/statements/state-of-openssl/ ↩

2. https://github.com/pyca/cryptography/issues/12824#issuecomment-3443465341 ↩

3. https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.204.pdf ↩

[ronf]

Do we really need the public_bytes_raw method here?

I need these raw bytes methods for both the private and public keys in AsyncSSH. For EdDSA, I'm currently using the older version of these calls which takes Encoding, PrivateFormat, and Encryption arguments, but I only ever pass in "Raw" and "NoEncryption", so at some point I'll switch that over to the "_raw" version of the methods, now that they exist.

[abbra]

In my branch I have wycheproof integration which imports all ML-DSA vectors and adds tests for them.

[abbra]

Please look at https://github.com/abbra/cryptography/tree/abbra-add-ml-dsa-87 which has all ML-DSA features for OpenSSL and support for test vectors.

[abbra]

I have three branches which are built on top of each other, that add ML-DSA 44, 65, 87 correspondingly. These branches already implement API as discussed with @reaperhulk and @alex in the ML-KEM-related issue. A colleague of mine, @frasertweedale, is working on adding BoringSSL support but that has proved itself non-trivial.

OpenSSL backend works fine and actually has been tested already to bring experimental ML-DSA support to FreeIPA.