Danger

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.

ML-DSA signing

ML-DSA is a post-quantum digital signature algorithm based on module lattices, standardized in FIPS 204.

Signing & Verification

>>> from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA65PrivateKey
>>> private_key = MLDSA65PrivateKey.generate()
>>> signature = private_key.sign(b"my authenticated message")
>>> public_key = private_key.public_key()
>>> public_key.verify(signature, b"my authenticated message")

Context-based Signing & Verification

ML-DSA supports context strings to bind additional information to signatures. The context can be up to 255 bytes and is used to differentiate signatures in different contexts or protocols.

>>> from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA65PrivateKey
>>> private_key = MLDSA65PrivateKey.generate()
>>> context = b"email-signature-v1"
>>> signature = private_key.sign(b"my authenticated message", context)
>>> public_key = private_key.public_key()
>>> # Verification requires the same context
>>> public_key.verify(signature, b"my authenticated message", context)

Key interfaces

class cryptography.hazmat.primitives.asymmetric.mldsa.MLDSA44PrivateKey

Added in version 47.0.

classmethod generate()

Generate an ML-DSA-44 private key.

Returns:

MLDSA44PrivateKey

Raises:

cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-44 is not supported by the backend cryptography is using.

classmethod from_seed_bytes(data)

Load an ML-DSA-44 private key from seed bytes.

Parameters:

data (bytes-like) – 32 byte seed.

Returns:

MLDSA44PrivateKey

Raises:

• ValueError – If the seed is not 32 bytes.

• cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-44 is not supported by the backend cryptography is using.

>>> from cryptography.hazmat.primitives.asymmetric import mldsa
>>> private_key = mldsa.MLDSA44PrivateKey.generate()
>>> seed = private_key.private_bytes_raw()
>>> same_key = mldsa.MLDSA44PrivateKey.from_seed_bytes(seed)

public_key()

Returns:

MLDSA44PublicKey

sign(data, context=None)

Sign the data using ML-DSA-44. An optional context string can be provided.

Parameters:

• data (bytes-like) – The data to sign.

• context (bytes-like or None) – An optional context string (up to 255 bytes).

Returns bytes:

The signature (2420 bytes).

Raises:

ValueError – If the context is longer than 255 bytes.

private_bytes(encoding, format, encryption_algorithm)

Allows serialization of the key to bytes. Encoding ( PEM, DER, or Raw) and format ( PKCS8 or Raw ) are chosen to define the exact serialization.

This method only returns the serialization of the seed form of the private key, never the expanded one.

Parameters:

• encoding – A value from the Encoding enum.

• format – A value from the PrivateFormat enum. If the encoding is Raw then format must be Raw , otherwise it must be PKCS8.

• encryption_algorithm – An instance of an object conforming to the KeySerializationEncryption interface.

Return bytes:

Serialized key.

private_bytes_raw()

Allows serialization of the key to raw bytes. This method is a convenience shortcut for calling private_bytes() with Raw encoding, Raw format, and NoEncryption.

This method only returns the seed form of the private key (32 bytes).

Return bytes:

Raw key (32-byte seed).

class cryptography.hazmat.primitives.asymmetric.mldsa.MLDSA44PublicKey

Added in version 47.0.

classmethod from_public_bytes(data)

Parameters:

data (bytes) – 1312 byte public key.

Returns:

MLDSA44PublicKey

Raises:

• ValueError – If the public key is not 1312 bytes.

• cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-44 is not supported by the backend cryptography is using.

>>> from cryptography.hazmat.primitives import serialization
>>> from cryptography.hazmat.primitives.asymmetric import mldsa
>>> private_key = mldsa.MLDSA44PrivateKey.generate()
>>> public_key = private_key.public_key()
>>> public_bytes = public_key.public_bytes(
...     encoding=serialization.Encoding.Raw,
...     format=serialization.PublicFormat.Raw
... )
>>> loaded_public_key = mldsa.MLDSA44PublicKey.from_public_bytes(public_bytes)

public_bytes(encoding, format)

Allows serialization of the key to bytes. Encoding ( PEM, DER, or Raw) and format ( SubjectPublicKeyInfo or Raw ) are chosen to define the exact serialization.

Parameters:

• encoding – A value from the Encoding enum.

• format – A value from the PublicFormat enum. If the encoding is Raw then format must be Raw , otherwise it must be SubjectPublicKeyInfo.

Returns bytes:

The public key bytes.

public_bytes_raw()

Allows serialization of the key to raw bytes. This method is a convenience shortcut for calling public_bytes() with Raw encoding and Raw format.

Return bytes:

1312-byte raw public key.

verify(signature, data, context=None)

Verify a signature using ML-DSA-44. If a context string was used during signing, the same context must be provided for verification to succeed.

Parameters:

• signature (bytes-like) – The signature to verify.

• data (bytes-like) – The data to verify.

• context (bytes-like or None) – An optional context string (up to 255 bytes) that was used during signing.

Returns:

None

Raises:

• cryptography.exceptions.InvalidSignature – Raised when the signature cannot be verified.

• ValueError – If the context is longer than 255 bytes.

class cryptography.hazmat.primitives.asymmetric.mldsa.MLDSA65PrivateKey

Added in version 47.0.

classmethod generate()

Generate an ML-DSA-65 private key.

Returns:

MLDSA65PrivateKey

Raises:

cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-65 is not supported by the backend cryptography is using.

classmethod from_seed_bytes(data)

Load an ML-DSA-65 private key from seed bytes.

Parameters:

data (bytes-like) – 32 byte seed.

Returns:

MLDSA65PrivateKey

Raises:

• ValueError – If the seed is not 32 bytes.

• cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-65 is not supported by the backend cryptography is using.

>>> from cryptography.hazmat.primitives.asymmetric import mldsa
>>> private_key = mldsa.MLDSA65PrivateKey.generate()
>>> seed = private_key.private_bytes_raw()
>>> same_key = mldsa.MLDSA65PrivateKey.from_seed_bytes(seed)

public_key()

Returns:

MLDSA65PublicKey

sign(data, context=None)

Sign the data using ML-DSA-65. An optional context string can be provided.

Parameters:

• data (bytes-like) – The data to sign.

• context (bytes-like or None) – An optional context string (up to 255 bytes).

Returns bytes:

The signature (3309 bytes).

Raises:

ValueError – If the context is longer than 255 bytes.

private_bytes(encoding, format, encryption_algorithm)

Allows serialization of the key to bytes. Encoding ( PEM, DER, or Raw) and format ( PKCS8 or Raw ) are chosen to define the exact serialization.

This method only returns the serialization of the seed form of the private key, never the expanded one.

Parameters:

• encoding – A value from the Encoding enum.

• format – A value from the PrivateFormat enum. If the encoding is Raw then format must be Raw , otherwise it must be PKCS8.

• encryption_algorithm – An instance of an object conforming to the KeySerializationEncryption interface.

Return bytes:

Serialized key.

private_bytes_raw()

Allows serialization of the key to raw bytes. This method is a convenience shortcut for calling private_bytes() with Raw encoding, Raw format, and NoEncryption.

This method only returns the seed form of the private key (32 bytes).

Return bytes:

Raw key (32-byte seed).

class cryptography.hazmat.primitives.asymmetric.mldsa.MLDSA65PublicKey

Added in version 47.0.

classmethod from_public_bytes(data)

Parameters:

data (bytes) – 1952 byte public key.

Returns:

MLDSA65PublicKey

Raises:

• ValueError – If the public key is not 1952 bytes.

• cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-65 is not supported by the backend cryptography is using.

>>> from cryptography.hazmat.primitives import serialization
>>> from cryptography.hazmat.primitives.asymmetric import mldsa
>>> private_key = mldsa.MLDSA65PrivateKey.generate()
>>> public_key = private_key.public_key()
>>> public_bytes = public_key.public_bytes(
...     encoding=serialization.Encoding.Raw,
...     format=serialization.PublicFormat.Raw
... )
>>> loaded_public_key = mldsa.MLDSA65PublicKey.from_public_bytes(public_bytes)

public_bytes(encoding, format)

Allows serialization of the key to bytes. Encoding ( PEM, DER, or Raw) and format ( SubjectPublicKeyInfo or Raw ) are chosen to define the exact serialization.

Parameters:

• encoding – A value from the Encoding enum.

• format – A value from the PublicFormat enum. If the encoding is Raw then format must be Raw , otherwise it must be SubjectPublicKeyInfo.

Returns bytes:

The public key bytes.

public_bytes_raw()

Allows serialization of the key to raw bytes. This method is a convenience shortcut for calling public_bytes() with Raw encoding and Raw format.

Return bytes:

1952-byte raw public key.

verify(signature, data, context=None)

Verify a signature using ML-DSA-65. If a context string was used during signing, the same context must be provided for verification to succeed.

Parameters:

• signature (bytes-like) – The signature to verify.

• data (bytes-like) – The data to verify.

• context (bytes-like or None) – An optional context string (up to 255 bytes) that was used during signing.

Returns:

None

Raises:

• cryptography.exceptions.InvalidSignature – Raised when the signature cannot be verified.

• ValueError – If the context is longer than 255 bytes.

class cryptography.hazmat.primitives.asymmetric.mldsa.MLDSA87PrivateKey

Added in version 47.0.

classmethod generate()

Generate an ML-DSA-87 private key.

Returns:

MLDSA87PrivateKey

Raises:

cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-87 is not supported by the backend cryptography is using.

classmethod from_seed_bytes(data)

Load an ML-DSA-87 private key from seed bytes.

Parameters:

data (bytes-like) – 32 byte seed.

Returns:

MLDSA87PrivateKey

Raises:

• ValueError – If the seed is not 32 bytes.

• cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-87 is not supported by the backend cryptography is using.

>>> from cryptography.hazmat.primitives.asymmetric import mldsa
>>> private_key = mldsa.MLDSA87PrivateKey.generate()
>>> seed = private_key.private_bytes_raw()
>>> same_key = mldsa.MLDSA87PrivateKey.from_seed_bytes(seed)

public_key()

Returns:

MLDSA87PublicKey

sign(data, context=None)

Sign the data using ML-DSA-87. An optional context string can be provided.

Parameters:

• data (bytes-like) – The data to sign.

• context (bytes-like or None) – An optional context string (up to 255 bytes).

Returns bytes:

The signature (4627 bytes).

Raises:

ValueError – If the context is longer than 255 bytes.

private_bytes(encoding, format, encryption_algorithm)

Allows serialization of the key to bytes. Encoding ( PEM, DER, or Raw) and format ( PKCS8 or Raw ) are chosen to define the exact serialization.

This method only returns the serialization of the seed form of the private key, never the expanded one.

Parameters:

• encoding – A value from the Encoding enum.

• format – A value from the PrivateFormat enum. If the encoding is Raw then format must be Raw , otherwise it must be PKCS8.

• encryption_algorithm – An instance of an object conforming to the KeySerializationEncryption interface.

Return bytes:

Serialized key.

private_bytes_raw()

Allows serialization of the key to raw bytes. This method is a convenience shortcut for calling private_bytes() with Raw encoding, Raw format, and NoEncryption.

This method only returns the seed form of the private key (32 bytes).

Return bytes:

Raw key (32-byte seed).

class cryptography.hazmat.primitives.asymmetric.mldsa.MLDSA87PublicKey

Added in version 47.0.

classmethod from_public_bytes(data)

Parameters:

data (bytes) – 2592 byte public key.

Returns:

MLDSA87PublicKey

Raises:

• ValueError – If the public key is not 2592 bytes.

• cryptography.exceptions.UnsupportedAlgorithm – If ML-DSA-87 is not supported by the backend cryptography is using.

>>> from cryptography.hazmat.primitives import serialization
>>> from cryptography.hazmat.primitives.asymmetric import mldsa
>>> private_key = mldsa.MLDSA87PrivateKey.generate()
>>> public_key = private_key.public_key()
>>> public_bytes = public_key.public_bytes(
...     encoding=serialization.Encoding.Raw,
...     format=serialization.PublicFormat.Raw
... )
>>> loaded_public_key = mldsa.MLDSA87PublicKey.from_public_bytes(public_bytes)

public_bytes(encoding, format)

Allows serialization of the key to bytes. Encoding ( PEM, DER, or Raw) and format ( SubjectPublicKeyInfo or Raw ) are chosen to define the exact serialization.

Parameters:

• encoding – A value from the Encoding enum.

• format – A value from the PublicFormat enum. If the encoding is Raw then format must be Raw , otherwise it must be SubjectPublicKeyInfo.

Returns bytes:

The public key bytes.

public_bytes_raw()

Allows serialization of the key to raw bytes. This method is a convenience shortcut for calling public_bytes() with Raw encoding and Raw format.

Return bytes:

2592-byte raw public key.

verify(signature, data, context=None)

Verify a signature using ML-DSA-87. If a context string was used during signing, the same context must be provided for verification to succeed.

Parameters:

• signature (bytes-like) – The signature to verify.

• data (bytes-like) – The data to verify.

• context (bytes-like or None) – An optional context string (up to 255 bytes) that was used during signing.

Returns:

None

Raises:

• cryptography.exceptions.InvalidSignature – Raised when the signature cannot be verified.

• ValueError – If the context is longer than 255 bytes.