Class MLDsa

Namespace: CryptoHives.Foundation.Security.Cryptography.Dsa

Assembly: CryptoHives.Foundation.Security.Cryptography.dll

Represents an ML-DSA key (FIPS 204) and provides signing and verification.

public sealed class MLDsa : IDisposable

Inheritance: object

MLDsa

Implements: IDisposable

Inherited Members: object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Remarks

The API shape mirrors System.Security.Cryptography.MLDsa from .NET 10 so code written against the in-box type ports directly to older target frameworks, including .NET Framework and .NET Standard 2.0.

An instance holds either a full key pair (created via GenerateKey(MLDsaAlgorithm), ImportMLDsaPrivateSeed(MLDsaAlgorithm, ReadOnlySpan<byte>), or ImportMLDsaPrivateKey(MLDsaAlgorithm, ReadOnlySpan<byte>)) or only a public key (via ImportMLDsaPublicKey(MLDsaAlgorithm, ReadOnlySpan<byte>)). Keys generated from a seed retain the 32-byte seed ξ, the compact storage form; keys imported from an expanded private key cannot export a seed. Private key material is zeroed when the instance is disposed.

External-μ signing (SignMu/VerifyMu) is not implemented.

Example usage:

using var signer = MLDsa.GenerateKey(MLDsaAlgorithm.MLDsa65);
byte[] publicKey = signer.ExportMLDsaPublicKey();
byte[] signature = signer.SignData(message);

using var verifier = MLDsa.ImportMLDsaPublicKey(MLDsaAlgorithm.MLDsa65, publicKey);
bool valid = verifier.VerifyData(message, signature);

Properties

Algorithm

Gets the ML-DSA parameter set of this key.

public MLDsaAlgorithm Algorithm { get; }

Property Value

MLDsaAlgorithm

IsSupported

Gets a value indicating whether ML-DSA is supported on the current platform.

public static bool IsSupported { get; }

Property Value

bool

Remarks

Always true. This is a fully managed implementation, so unlike System.Security.Cryptography.MLDsa.IsSupported it never depends on the operating system providing ML-DSA.

Methods

Dispose()

Zeroizes the private seed and private key and releases the instance.

public void Dispose()

ExportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte>, PbeOptions)

Exports this key in the PKCS#8 EncryptedPrivateKeyInfo format.

public byte[] ExportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte> password, PbeOptions pbeOptions)

Parameters

password ReadOnlySpan<byte>: The password, used verbatim as the key derivation input.
pbeOptions PbeOptions: Selects the cipher, pseudorandom function and iteration count.

Returns

byte[]: The DER encoding.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

ExportEncryptedPkcs8PrivateKey(ReadOnlySpan<char>, PbeOptions)

Exports this key in the PKCS#8 EncryptedPrivateKeyInfo format.

public byte[] ExportEncryptedPkcs8PrivateKey(ReadOnlySpan<char> password, PbeOptions pbeOptions)

Parameters

password ReadOnlySpan<char>: The password.
pbeOptions PbeOptions: Selects the cipher, pseudorandom function and iteration count.

Returns

byte[]: The DER encoding.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<byte>, PbeOptions)

Exports this key in a PEM-encoded PKCS#8 EncryptedPrivateKeyInfo.

public string ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<byte> password, PbeOptions pbeOptions)

Parameters

password ReadOnlySpan<byte>: The password, used verbatim as the key derivation input.
pbeOptions PbeOptions: Selects the cipher, pseudorandom function and iteration count.

Returns

string: The PEM text, labelled ENCRYPTED PRIVATE KEY.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<char>, PbeOptions)

Exports this key in a PEM-encoded PKCS#8 EncryptedPrivateKeyInfo.

public string ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<char> password, PbeOptions pbeOptions)

Parameters

password ReadOnlySpan<char>: The password.
pbeOptions PbeOptions: Selects the cipher, pseudorandom function and iteration count.

Returns

string: The PEM text, labelled ENCRYPTED PRIVATE KEY.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

ExportMLDsaPrivateKey()

Exports the expanded private key.

public byte[] ExportMLDsaPrivateKey()

Returns

byte[]

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

ExportMLDsaPrivateKey(Span<byte>)

Exports the expanded private key into a buffer.

public void ExportMLDsaPrivateKey(Span<byte> destination)

Parameters

destination Span<byte>: The buffer to receive the key; must be exactly PrivateKeySizeInBytes bytes.

Exceptions

ArgumentException: destination has an incorrect length.
ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

ExportMLDsaPrivateSeed()

Exports the 32-byte private seed ξ.

public byte[] ExportMLDsaPrivateSeed()

Returns

byte[]: The private seed.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The key was not created from a seed.

ExportMLDsaPrivateSeed(Span<byte>)

Exports the 32-byte private seed ξ into a buffer.

public void ExportMLDsaPrivateSeed(Span<byte> destination)

Parameters

destination Span<byte>: The buffer to receive the seed; must be exactly PrivateSeedSizeInBytes bytes.

Exceptions

ArgumentException: destination has an incorrect length.
ObjectDisposedException: The instance has been disposed.
CryptographicException: The key was not created from a seed.

ExportMLDsaPublicKey()

Exports the public key.

public byte[] ExportMLDsaPublicKey()

Returns

byte[]

Exceptions

ObjectDisposedException: The instance has been disposed.

ExportMLDsaPublicKey(Span<byte>)

Exports the public key into a buffer.

public void ExportMLDsaPublicKey(Span<byte> destination)

Parameters

destination Span<byte>: The buffer to receive the key; must be exactly PublicKeySizeInBytes bytes.

Exceptions

ArgumentException: destination has an incorrect length.
ObjectDisposedException: The instance has been disposed.

ExportPkcs8PrivateKey()

Exports this key in the PKCS#8 PrivateKeyInfo format.

public byte[] ExportPkcs8PrivateKey()

Returns

byte[]: The DER encoding.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

ExportSubjectPublicKeyInfo()

Exports the public-key portion of this key in the X.509 SubjectPublicKeyInfo format.

public byte[] ExportSubjectPublicKeyInfo()

Returns

byte[]: The DER encoding.

Exceptions

ObjectDisposedException: The instance has been disposed.

ExportSubjectPublicKeyInfoPem()

Exports the public-key portion of this key in a PEM-encoded SubjectPublicKeyInfo.

public string ExportSubjectPublicKeyInfoPem()

Returns

string: The PEM text, labelled PUBLIC KEY.

Exceptions

ObjectDisposedException: The instance has been disposed.

GenerateKey(MLDsaAlgorithm)

Generates a new ML-DSA key pair.

public static MLDsa GenerateKey(MLDsaAlgorithm algorithm)

Parameters

algorithm MLDsaAlgorithm: The parameter set to generate a key for.

Returns

MLDsa: A new instance holding the generated key pair and its private seed.

Exceptions

ArgumentNullException: algorithm is null.
CryptographicException: The key pair failed the consistency test.

GenerateKey(MLDsaAlgorithm, bool)

Generates a new ML-DSA key pair, optionally skipping the pairwise consistency test.

public static MLDsa GenerateKey(MLDsaAlgorithm algorithm, bool pairwiseConsistencyTest)

Parameters

algorithm MLDsaAlgorithm: The parameter set to generate a key for.
pairwiseConsistencyTest bool: true to verify the generated key pair with a sign/verify round trip; false to skip it.

Returns

MLDsa: A new instance holding the generated key pair and its private seed.

Remarks

The pairwise consistency test verifies a freshly expanded key pair by signing and verifying one message, as FIPS 140-3 IG 10.3.A expects of a validated module. It is the dominant cost of key generation, because a sign is itself a rejection loop that runs several iterations on average.

It guards against a fault — bad memory, a bit flip, a miscompiled build — producing a key pair that does not round-trip. It cannot catch an implementation bug, since both halves of the test would be wrong in the same way. Disable it only where that trade is understood and key generation throughput actually matters; the default on the BCL-shaped overloads keeps it enabled.

Exceptions

ArgumentNullException: algorithm is null.
CryptographicException: The key pair failed the consistency test.

GetPkcs8PrivateKeyPemSize()

Gets the exact number of characters TryExportPkcs8PrivateKeyPem(Span<char>, out int) writes for this key.

public int GetPkcs8PrivateKeyPemSize()

Returns

int: The required buffer length, in characters.

Remarks

The counterpart of System.Security.Cryptography.PemEncoding.GetEncodedSize, which is not available on every target framework this library supports. Rent a buffer of this size, call TryExportPkcs8PrivateKeyPem(Span<char>, out int), and clear the buffer when finished.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

GetSubjectPublicKeyInfoPemSize()

Gets the exact number of characters TryExportSubjectPublicKeyInfoPem(Span<char>, out int) writes.

public int GetSubjectPublicKeyInfoPemSize()

Returns

int: The required buffer length, in characters.

Exceptions

ObjectDisposedException: The instance has been disposed.

ImportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Imports an ML-DSA private key from a PKCS#8 EncryptedPrivateKeyInfo structure.

public static MLDsa ImportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte> password, ReadOnlySpan<byte> source)

Parameters

password ReadOnlySpan<byte>: The password, used verbatim as the key derivation input.
source ReadOnlySpan<byte>: The DER-encoded EncryptedPrivateKeyInfo.

Returns

MLDsa: The imported key.

Exceptions

CryptographicException: The password is wrong, or the structure is malformed or is not ML-DSA.

ImportEncryptedPkcs8PrivateKey(ReadOnlySpan<char>, ReadOnlySpan<byte>)

Imports an ML-DSA private key from a PKCS#8 EncryptedPrivateKeyInfo structure.

public static MLDsa ImportEncryptedPkcs8PrivateKey(ReadOnlySpan<char> password, ReadOnlySpan<byte> source)

Parameters

password ReadOnlySpan<char>: The password, encoded per the scheme in the structure.
source ReadOnlySpan<byte>: The DER-encoded EncryptedPrivateKeyInfo.

Returns

MLDsa: The imported key.

Exceptions

CryptographicException: The password is wrong, or the structure is malformed or is not ML-DSA.

ImportFromEncryptedPem(ReadOnlySpan<char>, ReadOnlySpan<byte>)

Imports an ML-DSA key from an encrypted RFC 7468 PEM-encoded string.

public static MLDsa ImportFromEncryptedPem(ReadOnlySpan<char> source, ReadOnlySpan<byte> passwordBytes)

Parameters

source ReadOnlySpan<char>: The PEM text.
passwordBytes ReadOnlySpan<byte>: The password, used verbatim as the key derivation input.

Returns

MLDsa: The imported key.

Exceptions

ArgumentException: source contains no encrypted private key, or more than one.

ImportFromEncryptedPem(ReadOnlySpan<char>, ReadOnlySpan<char>)

Imports an ML-DSA key from an encrypted RFC 7468 PEM-encoded string.

public static MLDsa ImportFromEncryptedPem(ReadOnlySpan<char> source, ReadOnlySpan<char> password)

Parameters

source ReadOnlySpan<char>: The PEM text.
password ReadOnlySpan<char>: The password.

Returns

MLDsa: The imported key.

Exceptions

ArgumentException: source contains no encrypted private key, or more than one.

ImportFromEncryptedPem(string, byte[])

Imports an ML-DSA key from an encrypted RFC 7468 PEM-encoded string.

public static MLDsa ImportFromEncryptedPem(string source, byte[] passwordBytes)

Parameters

source string: The PEM text.
passwordBytes byte[]: The password, used verbatim as the key derivation input.

Returns

MLDsa: The imported key.

Exceptions

ArgumentNullException: An argument is null.
ArgumentException: source contains no encrypted private key, or more than one.

ImportFromPem(ReadOnlySpan<char>)

Imports an ML-DSA key from an RFC 7468 PEM-encoded string.

public static MLDsa ImportFromPem(ReadOnlySpan<char> source)

Parameters

source ReadOnlySpan<char>: The PEM text.

Returns

MLDsa: The imported key.

Exceptions

ArgumentException: source contains no PEM block with a recognized label, or more than one.

ImportMLDsaPrivateKey(MLDsaAlgorithm, byte[])

Imports an expanded ML-DSA private key.

public static MLDsa ImportMLDsaPrivateKey(MLDsaAlgorithm algorithm, byte[] source)

Parameters

algorithm MLDsaAlgorithm: The parameter set of the key.
source byte[]: The expanded private key.

Returns

MLDsa: A new instance holding the key pair.

Remarks

A key imported this way holds no private seed, so ExportMLDsaPrivateSeed() is unavailable. The public key is reconstructed from the private key and validated against the embedded hash tr = H(pk); a mismatch rejects the import.

Exceptions

ArgumentNullException: algorithm or source is null.
ArgumentException: source has an invalid length.
CryptographicException: The embedded public key hash does not match the reconstructed public key.

ImportMLDsaPrivateKey(MLDsaAlgorithm, ReadOnlySpan<byte>)

Imports an expanded ML-DSA private key.

public static MLDsa ImportMLDsaPrivateKey(MLDsaAlgorithm algorithm, ReadOnlySpan<byte> source)

Parameters

algorithm MLDsaAlgorithm: The parameter set of the key.
source ReadOnlySpan<byte>: The expanded private key.

Returns

MLDsa: A new instance holding the key pair.

Remarks

Exceptions

CryptographicException: The embedded public key hash does not match the reconstructed public key.
ArgumentNullException: algorithm is null.
ArgumentException: source has an invalid length.

ImportMLDsaPrivateSeed(MLDsaAlgorithm, byte[])

Imports an ML-DSA private seed ξ and expands it into a key pair.

public static MLDsa ImportMLDsaPrivateSeed(MLDsaAlgorithm algorithm, byte[] source)

Parameters

algorithm MLDsaAlgorithm: The parameter set of the key.
source byte[]: The 32-byte private seed.

Returns

MLDsa: A new instance holding the key pair and the seed.

Exceptions

ArgumentNullException: algorithm or source is null.
ArgumentException: source has an invalid length.
CryptographicException: The key pair failed the consistency test.

ImportMLDsaPrivateSeed(MLDsaAlgorithm, ReadOnlySpan<byte>)

Imports an ML-DSA private seed ξ and expands it into a key pair.

public static MLDsa ImportMLDsaPrivateSeed(MLDsaAlgorithm algorithm, ReadOnlySpan<byte> source)

Parameters

algorithm MLDsaAlgorithm: The parameter set of the key.
source ReadOnlySpan<byte>: The 32-byte private seed.

Returns

MLDsa: A new instance holding the key pair and the seed.

Exceptions

ArgumentNullException: algorithm is null.
ArgumentException: source has an invalid length.
CryptographicException: The key pair failed the consistency test.

ImportMLDsaPrivateSeed(MLDsaAlgorithm, ReadOnlySpan<byte>, bool)

Imports an ML-DSA private seed ξ and expands it into a key pair, optionally skipping the pairwise consistency test.

public static MLDsa ImportMLDsaPrivateSeed(MLDsaAlgorithm algorithm, ReadOnlySpan<byte> source, bool pairwiseConsistencyTest)

Parameters

algorithm MLDsaAlgorithm: The parameter set of the key.
source ReadOnlySpan<byte>: The 32-byte private seed.
pairwiseConsistencyTest bool: true to verify the expanded key pair; false to skip it.

Returns

MLDsa: A new instance holding the key pair and the seed.

Remarks

Exceptions

ArgumentNullException: algorithm is null.
ArgumentException: source has an invalid length.
CryptographicException: The key pair failed the consistency test.

ImportMLDsaPublicKey(MLDsaAlgorithm, byte[])

Imports an ML-DSA public key.

public static MLDsa ImportMLDsaPublicKey(MLDsaAlgorithm algorithm, byte[] source)

Parameters

algorithm MLDsaAlgorithm: The parameter set of the key.
source byte[]: The public key.

Returns

MLDsa: A new instance holding only the public key; it can verify but not sign.

Exceptions

ArgumentNullException: algorithm or source is null.
ArgumentException: source has an invalid length.

ImportMLDsaPublicKey(MLDsaAlgorithm, ReadOnlySpan<byte>)

Imports an ML-DSA public key.

public static MLDsa ImportMLDsaPublicKey(MLDsaAlgorithm algorithm, ReadOnlySpan<byte> source)

Parameters

algorithm MLDsaAlgorithm: The parameter set of the key.
source ReadOnlySpan<byte>: The public key.

Returns

MLDsa: A new instance holding only the public key; it can verify but not sign.

Exceptions

ArgumentNullException: algorithm is null.
ArgumentException: source has an invalid length.

ImportPkcs8PrivateKey(byte[])

Imports an ML-DSA private key from a PKCS#8 PrivateKeyInfo structure.

public static MLDsa ImportPkcs8PrivateKey(byte[] source)

Parameters

source byte[]: The DER-encoded PrivateKeyInfo.

Returns

MLDsa: The imported key.

Exceptions

ArgumentNullException: source is null.
CryptographicException: The structure is malformed or is not ML-DSA.

ImportPkcs8PrivateKey(ReadOnlySpan<byte>)

Imports an ML-DSA private key from a PKCS#8 PrivateKeyInfo structure.

public static MLDsa ImportPkcs8PrivateKey(ReadOnlySpan<byte> source)

Parameters

source ReadOnlySpan<byte>: The DER-encoded PrivateKeyInfo.

Returns

MLDsa: The imported key.

Exceptions

CryptographicException: The structure is malformed or is not ML-DSA.

ImportSubjectPublicKeyInfo(byte[])

Imports an ML-DSA public key from an X.509 SubjectPublicKeyInfo structure.

public static MLDsa ImportSubjectPublicKeyInfo(byte[] source)

Parameters

source byte[]: The DER-encoded SubjectPublicKeyInfo.

Returns

MLDsa: A verify-only instance.

Exceptions

ArgumentNullException: source is null.
CryptographicException: The structure is malformed or is not ML-DSA.

ImportSubjectPublicKeyInfo(ReadOnlySpan<byte>)

Imports an ML-DSA public key from an X.509 SubjectPublicKeyInfo structure.

public static MLDsa ImportSubjectPublicKeyInfo(ReadOnlySpan<byte> source)

Parameters

source ReadOnlySpan<byte>: The DER-encoded SubjectPublicKeyInfo.

Returns

MLDsa: A verify-only instance.

Exceptions

CryptographicException: The structure is malformed or is not ML-DSA.

SignData(byte[], byte[]?)

Signs data using the hedged (randomized) variant of ML-DSA.

public byte[] SignData(byte[] data, byte[]? context = null)

Parameters

data byte[]: The data to sign.
context byte[]: The optional context string (at most 255 bytes), or null.

Returns

byte[]: The signature.

Exceptions

ArgumentNullException: data is null.
ArgumentException: context is longer than 255 bytes.
ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

SignData(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Signs data using the hedged (randomized) variant of ML-DSA.

public byte[] SignData(ReadOnlySpan<byte> data, ReadOnlySpan<byte> context = default)

Parameters

data ReadOnlySpan<byte>: The data to sign.
context ReadOnlySpan<byte>: The optional context string (at most 255 bytes).

Returns

byte[]: The signature.

Exceptions

ArgumentException: context is longer than 255 bytes.
ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

SignData(ReadOnlySpan<byte>, Span<byte>, ReadOnlySpan<byte>)

Signs data into a caller-provided buffer using the hedged (randomized) variant of ML-DSA.

public void SignData(ReadOnlySpan<byte> data, Span<byte> destination, ReadOnlySpan<byte> context = default)

Parameters

data ReadOnlySpan<byte>: The data to sign.
destination Span<byte>: The buffer to receive the signature; must be exactly SignatureSizeInBytes bytes.
context ReadOnlySpan<byte>: The optional context string (at most 255 bytes).

Exceptions

ArgumentException: A parameter has an invalid size.
ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

SignPreHash(byte[], string, byte[]?)

Signs a pre-computed message digest using HashML-DSA (FIPS 204 §5.4).

public byte[] SignPreHash(byte[] hash, string hashAlgorithmOid, byte[]? context = null)

Parameters

hash byte[]: The pre-computed digest PH(M).
hashAlgorithmOid string: The dotted-decimal OID of the pre-hash function, e.g. 2.16.840.1.101.3.4.2.3 for SHA-512.
context byte[]: The optional context string (at most 255 bytes), or null.

Returns

byte[]: The signature.

Remarks

The caller computes PH(M) with an approved hash or XOF and passes the digest with its OID; the signature binds the pre-hash function via M′ = 0x01 ‖ |ctx| ‖ ctx ‖ OID ‖ PH(M). Pre-hash signatures are never interchangeable with pure ML-DSA signatures over the same message.

Exceptions

ArgumentNullException: hash or hashAlgorithmOid is null.
ArgumentException: The OID is not approved, the digest length does not match it, or context is longer than 255 bytes.
ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

SignPreHash(ReadOnlySpan<byte>, Span<byte>, string, ReadOnlySpan<byte>)

Signs a pre-computed message digest into a caller-provided buffer using HashML-DSA (FIPS 204 §5.4).

public void SignPreHash(ReadOnlySpan<byte> hash, Span<byte> destination, string hashAlgorithmOid, ReadOnlySpan<byte> context = default)

Parameters

hash ReadOnlySpan<byte>: The pre-computed digest PH(M).
destination Span<byte>: The buffer to receive the signature; must be exactly SignatureSizeInBytes bytes.
hashAlgorithmOid string: The dotted-decimal OID of the pre-hash function.
context ReadOnlySpan<byte>: The optional context string (at most 255 bytes).

Remarks

Note the parameter order, which this type inherits from the in-box MLDsa: the second parameter is the destination buffer, whereas on SignData(byte[], byte[]?) the second parameter is the context. Call sites that pass arrays should spell out new ReadOnlySpan<byte>(…) and new Span<byte>(…) so the intended overload is unambiguous.

Exceptions

ArgumentNullException: hashAlgorithmOid is null.
ArgumentException: A parameter has an invalid size, or the OID is not an approved pre-hash function.
ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

TryExportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte>, PbeOptions, Span<byte>, out int)

Attempts to export this key in the PKCS#8 EncryptedPrivateKeyInfo format.

public bool TryExportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte> password, PbeOptions pbeOptions, Span<byte> destination, out int bytesWritten)

Parameters

password ReadOnlySpan<byte>: The password, used verbatim as the key derivation input.
pbeOptions PbeOptions: Selects the cipher, pseudorandom function and iteration count.
destination Span<byte>: The buffer to receive the encoding.
bytesWritten int: The number of bytes written.

Returns

bool: false when destination is too small.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

TryExportEncryptedPkcs8PrivateKey(ReadOnlySpan<char>, PbeOptions, Span<byte>, out int)

Attempts to export this key in the PKCS#8 EncryptedPrivateKeyInfo format.

public bool TryExportEncryptedPkcs8PrivateKey(ReadOnlySpan<char> password, PbeOptions pbeOptions, Span<byte> destination, out int bytesWritten)

Parameters

password ReadOnlySpan<char>: The password.
pbeOptions PbeOptions: Selects the cipher, pseudorandom function and iteration count.
destination Span<byte>: The buffer to receive the encoding.
bytesWritten int: The number of bytes written.

Returns

bool: false when destination is too small.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

TryExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<byte>, PbeOptions, Span<char>, out int)

Attempts to export this key as a PEM-encoded PKCS#8 EncryptedPrivateKeyInfo.

public bool TryExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<byte> password, PbeOptions pbeOptions, Span<char> destination, out int charsWritten)

Parameters

password ReadOnlySpan<byte>: The password, used verbatim as the key derivation input.
pbeOptions PbeOptions: Selects the cipher, pseudorandom function and iteration count.
destination Span<char>: The buffer to receive the text.
charsWritten int: The number of characters written.

Returns

bool: false when destination is too small.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

TryExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<char>, PbeOptions, Span<char>, out int)

Attempts to export this key as a PEM-encoded PKCS#8 EncryptedPrivateKeyInfo.

public bool TryExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<char> password, PbeOptions pbeOptions, Span<char> destination, out int charsWritten)

Parameters

password ReadOnlySpan<char>: The password, encoded per the scheme being written.
pbeOptions PbeOptions: Selects the cipher, pseudorandom function and iteration count.
destination Span<char>: The buffer to receive the text.
charsWritten int: The number of characters written.

Returns

bool: false when destination is too small.

Remarks

There is no size helper for this member: measuring the output means running the key derivation function, which at a realistic iteration count is the whole cost of the export. Use ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<char>, PbeOptions) - safe, because the payload is ciphertext - or grow a buffer until this succeeds.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

TryExportPkcs8PrivateKey(Span<byte>, out int)

Attempts to export this key in the PKCS#8 PrivateKeyInfo format.

public bool TryExportPkcs8PrivateKey(Span<byte> destination, out int bytesWritten)

Parameters

destination Span<byte>: The buffer to receive the encoding.
bytesWritten int: The number of bytes written.

Returns

bool: false when destination is too small.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

TryExportPkcs8PrivateKeyPem(Span<char>, out int)

Attempts to export this key as a PEM-encoded PKCS#8 PrivateKeyInfo, writing into a buffer the caller owns and can erase.

public bool TryExportPkcs8PrivateKeyPem(Span<char> destination, out int charsWritten)

Parameters

destination Span<char>: The buffer to receive the text, labelled PRIVATE KEY.
charsWritten int: The number of characters written.

Returns

bool: false when destination is too small.

Remarks

There is no allocating ExportPkcs8PrivateKeyPem(). The text this produces is the private key, and a string holding it could never be erased - so the only export this type offers is one that writes where the caller can clear it afterwards. Size the buffer with GetPkcs8PrivateKeyPemSize().

When the buffer is too small nothing is written and charsWritten is zero.

Exceptions

ObjectDisposedException: The instance has been disposed.
CryptographicException: The instance holds no private key.

TryExportSubjectPublicKeyInfo(Span<byte>, out int)

Attempts to export the public-key portion of this key as a SubjectPublicKeyInfo.

public bool TryExportSubjectPublicKeyInfo(Span<byte> destination, out int bytesWritten)

Parameters

destination Span<byte>: The buffer to receive the encoding.
bytesWritten int: The number of bytes written.

Returns

bool: false when destination is too small.

Exceptions

ObjectDisposedException: The instance has been disposed.

TryExportSubjectPublicKeyInfoPem(Span<char>, out int)

Attempts to export this key as a PEM-encoded SubjectPublicKeyInfo.

public bool TryExportSubjectPublicKeyInfoPem(Span<char> destination, out int charsWritten)

Parameters

destination Span<char>: The buffer to receive the text, labelled PUBLIC KEY.
charsWritten int: The number of characters written.

Returns

bool: false when destination is too small.

Remarks

A public key is not secret, so ExportSubjectPublicKeyInfoPem() remains available and is usually the simpler call. This overload exists for parity with AsymmetricAlgorithm, which offers the same pair, and for callers avoiding allocation.

Exceptions

ObjectDisposedException: The instance has been disposed.

VerifyData(byte[], byte[], byte[]?)

Verifies a signature over data.

public bool VerifyData(byte[] data, byte[] signature, byte[]? context = null)

Parameters

data byte[]: The signed data.
signature byte[]: The signature to verify.
context byte[]: The context string used when signing (at most 255 bytes), or null.

Returns

bool: True when the signature is valid; false for invalid signatures, including malformed lengths.

Exceptions

ArgumentNullException: data or signature is null.
ArgumentException: context is longer than 255 bytes.
ObjectDisposedException: The instance has been disposed.

VerifyData(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Verifies a signature over data.

public bool VerifyData(ReadOnlySpan<byte> data, ReadOnlySpan<byte> signature, ReadOnlySpan<byte> context = default)

Parameters

data ReadOnlySpan<byte>: The signed data.
signature ReadOnlySpan<byte>: The signature to verify.
context ReadOnlySpan<byte>: The context string used when signing (at most 255 bytes).

Returns

bool: True when the signature is valid; false for invalid signatures, including malformed lengths.

Exceptions

ArgumentException: context is longer than 255 bytes.
ObjectDisposedException: The instance has been disposed.

VerifyPreHash(byte[], byte[], string, byte[]?)

Verifies a HashML-DSA signature over a pre-computed message digest (FIPS 204 §5.4).

public bool VerifyPreHash(byte[] hash, byte[] signature, string hashAlgorithmOid, byte[]? context = null)

Parameters

hash byte[]: The pre-computed digest PH(M).
signature byte[]: The signature to verify.
hashAlgorithmOid string: The dotted-decimal OID of the pre-hash function used when signing.
context byte[]: The context string used when signing (at most 255 bytes), or null.

Returns

bool: True when the signature is valid; false for invalid signatures, including malformed lengths.

Exceptions

ArgumentNullException: hash, signature or hashAlgorithmOid is null.
ArgumentException: The OID is not approved, the digest length does not match it, or context is longer than 255 bytes.
ObjectDisposedException: The instance has been disposed.

VerifyPreHash(ReadOnlySpan<byte>, ReadOnlySpan<byte>, string, ReadOnlySpan<byte>)

Verifies a HashML-DSA signature over a pre-computed message digest (FIPS 204 §5.4).

public bool VerifyPreHash(ReadOnlySpan<byte> hash, ReadOnlySpan<byte> signature, string hashAlgorithmOid, ReadOnlySpan<byte> context = default)

Parameters

hash ReadOnlySpan<byte>: The pre-computed digest PH(M).
signature ReadOnlySpan<byte>: The signature to verify.
hashAlgorithmOid string: The dotted-decimal OID of the pre-hash function used when signing.
context ReadOnlySpan<byte>: The context string used when signing (at most 255 bytes).

Returns

bool: True when the signature is valid; false for invalid signatures, including malformed lengths.

Exceptions

ArgumentNullException: hashAlgorithmOid is null.
ArgumentException: The OID is not approved, the digest length does not match it, or context is longer than 255 bytes.
ObjectDisposedException: The instance has been disposed.

Table of Contents

Class MLDsa

Remarks

Properties

Algorithm

Property Value

IsSupported

Property Value

Remarks

Methods

Dispose()

ExportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte>, PbeOptions)

Parameters

Returns

Exceptions

ExportEncryptedPkcs8PrivateKey(ReadOnlySpan<char>, PbeOptions)

Parameters

Returns

Exceptions

ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<byte>, PbeOptions)

Parameters

Returns

Exceptions

ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<char>, PbeOptions)

Parameters

Returns

Exceptions

ExportMLDsaPrivateKey()

Returns

Exceptions

ExportMLDsaPrivateKey(Span<byte>)

Parameters

Exceptions

ExportMLDsaPrivateSeed()

Returns

Exceptions

ExportMLDsaPrivateSeed(Span<byte>)

Parameters

Exceptions

ExportMLDsaPublicKey()

Returns

Exceptions

ExportMLDsaPublicKey(Span<byte>)

Parameters

Exceptions

ExportPkcs8PrivateKey()

Returns

Exceptions

ExportSubjectPublicKeyInfo()

Returns

Exceptions

ExportSubjectPublicKeyInfoPem()

Returns

Exceptions

GenerateKey(MLDsaAlgorithm)

Parameters

Returns

Exceptions

GenerateKey(MLDsaAlgorithm, bool)

Parameters

Returns

Remarks

Exceptions

GetPkcs8PrivateKeyPemSize()

Returns

Remarks

Exceptions

GetSubjectPublicKeyInfoPemSize()

Returns

Exceptions

ImportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Parameters

Returns

Exceptions

ImportEncryptedPkcs8PrivateKey(ReadOnlySpan<char>, ReadOnlySpan<byte>)

Parameters

Returns

Exceptions

ImportFromEncryptedPem(ReadOnlySpan<char>, ReadOnlySpan<byte>)

Parameters