mldsa.h

All headers

ML-DSA.

This implements the Module-Lattice-Based Digital Signature Standard from https://csrc.nist.gov/pubs/fips/204/final

  1. MLDSA_SEED_BYTES
  2. MLDSA_MU_BYTES
  3. ML-DSA-65
  4. MLDSA65_private_key
  5. MLDSA65_public_key
  6. MLDSA65_prehash
  7. MLDSA65_PRIVATE_KEY_BYTES
  8. MLDSA65_PUBLIC_KEY_BYTES
  9. MLDSA65_SIGNATURE_BYTES
  10. MLDSA65_generate_key
  11. MLDSA65_private_key_from_seed
  12. MLDSA65_public_from_private
  13. MLDSA65_sign
  14. MLDSA65_verify
  15. MLDSA65_prehash_init
  16. MLDSA65_prehash_update
  17. MLDSA65_prehash_finalize
  18. MLDSA65_sign_message_representative
  19. MLDSA65_marshal_public_key
  20. MLDSA65_parse_public_key
  21. ML-DSA-87
  22. MLDSA87_private_key
  23. MLDSA87_public_key
  24. MLDSA87_prehash
  25. MLDSA87_PRIVATE_KEY_BYTES
  26. MLDSA87_PUBLIC_KEY_BYTES
  27. MLDSA87_SIGNATURE_BYTES
  28. MLDSA87_generate_key
  29. MLDSA87_private_key_from_seed
  30. MLDSA87_public_from_private
  31. MLDSA87_sign
  32. MLDSA87_verify
  33. MLDSA87_prehash_init
  34. MLDSA87_prehash_update
  35. MLDSA87_prehash_finalize
  36. MLDSA87_sign_message_representative
  37. MLDSA87_marshal_public_key
  38. MLDSA87_parse_public_key

MLDSA_SEED_BYTES is the number of bytes in an ML-DSA seed value.

#define MLDSA_SEED_BYTES 32

MLDSA_MU_BYTES is the number of bytes in an ML-DSA mu value.

#define MLDSA_MU_BYTES 64

ML-DSA-65.

MLDSA65_private_key contains an ML-DSA-65 private key. The contents of this object should never leave the address space since the format is unstable.

struct MLDSA65_private_key {
  union {
    uint8_t bytes[32 + 32 + 64 + 256 * 4 * (5 + 6 + 6)];
    uint32_t alignment;
  } opaque;
};

MLDSA65_public_key contains an ML-DSA-65 public key. The contents of this object should never leave the address space since the format is unstable.

struct MLDSA65_public_key {
  union {
    uint8_t bytes[32 + 64 + 256 * 4 * 6];
    uint32_t alignment;
  } opaque;
};

MLDSA65_prehash contains a pre-hash context for ML-DSA-65. The contents of this object should never leave the address space since the format is unstable.

struct MLDSA65_prehash {
  union {
    uint8_t bytes[200 + 4 + 4 + 4 * sizeof(size_t)];
    uint64_t alignment;
  } opaque;
};

MLDSA65_PRIVATE_KEY_BYTES is the number of bytes in an encoded ML-DSA-65 private key.

#define MLDSA65_PRIVATE_KEY_BYTES 4032

MLDSA65_PUBLIC_KEY_BYTES is the number of bytes in an encoded ML-DSA-65 public key.

#define MLDSA65_PUBLIC_KEY_BYTES 1952

MLDSA65_SIGNATURE_BYTES is the number of bytes in an encoded ML-DSA-65 signature.

#define MLDSA65_SIGNATURE_BYTES 3309

MLDSA65_generate_key generates a random public/private key pair, writes the encoded public key to out_encoded_public_key, writes the seed to out_seed, and sets out_private_key to the private key. Returns 1 on success and 0 on allocation failure.

OPENSSL_EXPORT int MLDSA65_generate_key(
    uint8_t out_encoded_public_key[MLDSA65_PUBLIC_KEY_BYTES],
    uint8_t out_seed[MLDSA_SEED_BYTES],
    struct MLDSA65_private_key *out_private_key);

MLDSA65_private_key_from_seed regenerates a private key from a seed value that was generated by MLDSA65_generate_key. Returns 1 on success and 0 on allocation failure or if seed_len is incorrect.

OPENSSL_EXPORT int MLDSA65_private_key_from_seed(
    struct MLDSA65_private_key *out_private_key, const uint8_t *seed,
    size_t seed_len);

MLDSA65_public_from_private sets *out_public_key to the public key that corresponds to private_key. Returns 1 on success and 0 on failure.

OPENSSL_EXPORT int MLDSA65_public_from_private(
    struct MLDSA65_public_key *out_public_key,
    const struct MLDSA65_private_key *private_key);

MLDSA65_sign generates a signature for the message msg of length msg_len using private_key (following the randomized algorithm), and writes the encoded signature to out_encoded_signature. The context argument is also signed over and can be used to include implicit contextual information that isn't included in msg. The same value of context must be presented to MLDSA65_verify in order for the generated signature to be considered valid. context and context_len may be NULL and 0 to use an empty context (this is common). Returns 1 on success and 0 on failure.

OPENSSL_EXPORT int MLDSA65_sign(
    uint8_t out_encoded_signature[MLDSA65_SIGNATURE_BYTES],
    const struct MLDSA65_private_key *private_key, const uint8_t *msg,
    size_t msg_len, const uint8_t *context, size_t context_len);

MLDSA65_verify verifies that signature constitutes a valid signature for the message msg of length msg_len using public_key. The value of context must equal the value that was passed to MLDSA65_sign when the signature was generated. Returns 1 on success or 0 on error.

OPENSSL_EXPORT int MLDSA65_verify(const struct MLDSA65_public_key *public_key,
                                  const uint8_t *signature,
                                  size_t signature_len, const uint8_t *msg,
                                  size_t msg_len, const uint8_t *context,
                                  size_t context_len);

MLDSA65_prehash_init initializes a pre-hashing state using public_key. The context argument can be used to include implicit contextual information that isn't included in the message. The same value of context must be presented to MLDSA65_verify in order for the generated signature to be considered valid. context and context_len may be NULL and 0 to use an empty context (this is common). Returns 1 on success and 0 on failure (if the context is too long).

OPENSSL_EXPORT int MLDSA65_prehash_init(
    struct MLDSA65_prehash *out_state,
    const struct MLDSA65_public_key *public_key, const uint8_t *context,
    size_t context_len);

MLDSA65_prehash_update incorporates the given msg of length msg_len into the pre-hashing state. This can be called multiple times on successive chunks of the message. This should be called after MLDSA65_prehash_init and before MLDSA65_prehash_finalize.

OPENSSL_EXPORT void MLDSA65_prehash_update(struct MLDSA65_prehash *inout_state,
                                           const uint8_t *msg, size_t msg_len);

MLDSA65_prehash_finalize extracts a pre-hashed message representative from the given pre-hashing state. This should be called after MLDSA65_prehash_init and MLDSA65_prehash_update. The resulting out_msg_rep should then be passed to MLDSA65_sign_message_representative to obtain a signature.

OPENSSL_EXPORT void MLDSA65_prehash_finalize(
    uint8_t out_msg_rep[MLDSA_MU_BYTES], struct MLDSA65_prehash *inout_state);

MLDSA65_sign_message_representative generates a signature for the pre-hashed message msg_rep using private_key (following the randomized algorithm), and writes the encoded signature to out_encoded_signature. The msg_rep should be obtained via calls to MLDSA65_prehash_init, MLDSA65_prehash_update and MLDSA65_prehash_finalize using the public key from the same key pair, otherwise the signature will not verify. Returns 1 on success and 0 on failure.

OPENSSL_EXPORT int MLDSA65_sign_message_representative(
    uint8_t out_encoded_signature[MLDSA65_SIGNATURE_BYTES],
    const struct MLDSA65_private_key *private_key,
    const uint8_t msg_rep[MLDSA_MU_BYTES]);

MLDSA65_marshal_public_key serializes public_key to out in the standard format for ML-DSA-65 public keys. It returns 1 on success or 0 on allocation error.

OPENSSL_EXPORT int MLDSA65_marshal_public_key(
    CBB *out, const struct MLDSA65_public_key *public_key);

MLDSA65_parse_public_key parses a public key, in the format generated by MLDSA65_marshal_public_key, from in and writes the result to out_public_key. It returns 1 on success or 0 on parse error or if there are trailing bytes in in.

OPENSSL_EXPORT int MLDSA65_parse_public_key(
    struct MLDSA65_public_key *public_key, CBS *in);

ML-DSA-87.

ML-DSA-87 is excessively and unnecessarily large. Use -65 unless you are specifically attempting to achieve CNSA 2.0 compliance.

MLDSA87_private_key contains an ML-DSA-87 private key. The contents of this object should never leave the address space since the format is unstable.

struct MLDSA87_private_key {
  union {
    uint8_t bytes[32 + 32 + 64 + 256 * 4 * (7 + 8 + 8)];
    uint32_t alignment;
  } opaque;
};

MLDSA87_public_key contains an ML-DSA-87 public key. The contents of this object should never leave the address space since the format is unstable.

struct MLDSA87_public_key {
  union {
    uint8_t bytes[32 + 64 + 256 * 4 * 8];
    uint32_t alignment;
  } opaque;
};

MLDSA87_prehash contains a pre-hash context for ML-DSA-87. The contents of this object should never leave the address space since the format is unstable.

struct MLDSA87_prehash {
  union {
    uint8_t bytes[200 + 4 + 4 + 4 * sizeof(size_t)];
    uint64_t alignment;
  } opaque;
};

MLDSA87_PRIVATE_KEY_BYTES is the number of bytes in an encoded ML-DSA-87 private key.

#define MLDSA87_PRIVATE_KEY_BYTES 4896

MLDSA87_PUBLIC_KEY_BYTES is the number of bytes in an encoded ML-DSA-87 public key.

#define MLDSA87_PUBLIC_KEY_BYTES 2592

MLDSA87_SIGNATURE_BYTES is the number of bytes in an encoded ML-DSA-87 signature.

#define MLDSA87_SIGNATURE_BYTES 4627

MLDSA87_generate_key generates a random public/private key pair, writes the encoded public key to out_encoded_public_key, writes the seed to out_seed, and sets out_private_key to the private key. Returns 1 on success and 0 on allocation failure.

OPENSSL_EXPORT int MLDSA87_generate_key(
    uint8_t out_encoded_public_key[MLDSA87_PUBLIC_KEY_BYTES],
    uint8_t out_seed[MLDSA_SEED_BYTES],
    struct MLDSA87_private_key *out_private_key);

MLDSA87_private_key_from_seed regenerates a private key from a seed value that was generated by MLDSA87_generate_key. Returns 1 on success and 0 on allocation failure or if seed_len is incorrect.

OPENSSL_EXPORT int MLDSA87_private_key_from_seed(
    struct MLDSA87_private_key *out_private_key, const uint8_t *seed,
    size_t seed_len);

MLDSA87_public_from_private sets *out_public_key to the public key that corresponds to private_key. Returns 1 on success and 0 on failure.

OPENSSL_EXPORT int MLDSA87_public_from_private(
    struct MLDSA87_public_key *out_public_key,
    const struct MLDSA87_private_key *private_key);

MLDSA87_sign generates a signature for the message msg of length msg_len using private_key (following the randomized algorithm), and writes the encoded signature to out_encoded_signature. The context argument is also signed over and can be used to include implicit contextual information that isn't included in msg. The same value of context must be presented to MLDSA87_verify in order for the generated signature to be considered valid. context and context_len may be NULL and 0 to use an empty context (this is common). Returns 1 on success and 0 on failure.

OPENSSL_EXPORT int MLDSA87_sign(
    uint8_t out_encoded_signature[MLDSA87_SIGNATURE_BYTES],
    const struct MLDSA87_private_key *private_key, const uint8_t *msg,
    size_t msg_len, const uint8_t *context, size_t context_len);

MLDSA87_verify verifies that signature constitutes a valid signature for the message msg of length msg_len using public_key. The value of context must equal the value that was passed to MLDSA87_sign when the signature was generated. Returns 1 on success or 0 on error.

OPENSSL_EXPORT int MLDSA87_verify(const struct MLDSA87_public_key *public_key,
                                  const uint8_t *signature,
                                  size_t signature_len, const uint8_t *msg,
                                  size_t msg_len, const uint8_t *context,
                                  size_t context_len);

MLDSA87_prehash_init initializes a pre-hashing state using public_key. The context argument can be used to include implicit contextual information that isn't included in the message. The same value of context must be presented to MLDSA87_verify in order for the generated signature to be considered valid. context and context_len may be NULL and 0 to use an empty context (this is common). Returns 1 on success and 0 on failure (if the context is too long).

OPENSSL_EXPORT int MLDSA87_prehash_init(
    struct MLDSA87_prehash *out_state,
    const struct MLDSA87_public_key *public_key, const uint8_t *context,
    size_t context_len);

MLDSA87_prehash_update incorporates the given msg of length msg_len into the pre-hashing state. This can be called multiple times on successive chunks of the message. This should be called after MLDSA87_prehash_init and before MLDSA87_prehash_finalize.

OPENSSL_EXPORT void MLDSA87_prehash_update(struct MLDSA87_prehash *inout_state,
                                           const uint8_t *msg, size_t msg_len);

MLDSA87_prehash_finalize extracts a pre-hashed message representative from the given pre-hashing state. This should be called after MLDSA87_prehash_init and MLDSA87_prehash_update. The resulting out_msg_rep should then be passed to MLDSA87_sign_message_representative to obtain a signature.

OPENSSL_EXPORT void MLDSA87_prehash_finalize(
    uint8_t out_msg_rep[MLDSA_MU_BYTES], struct MLDSA87_prehash *inout_state);

MLDSA87_sign_message_representative generates a signature for the pre-hashed message msg_rep using private_key (following the randomized algorithm), and writes the encoded signature to out_encoded_signature. The msg_rep should be obtained via calls to MLDSA87_prehash_init, MLDSA87_prehash_update and MLDSA87_prehash_finalize using the public key from the same key pair, otherwise the signature will not verify. Returns 1 on success and 0 on failure.

OPENSSL_EXPORT int MLDSA87_sign_message_representative(
    uint8_t out_encoded_signature[MLDSA87_SIGNATURE_BYTES],
    const struct MLDSA87_private_key *private_key,
    const uint8_t msg_rep[MLDSA_MU_BYTES]);

MLDSA87_marshal_public_key serializes public_key to out in the standard format for ML-DSA-87 public keys. It returns 1 on success or 0 on allocation error.

OPENSSL_EXPORT int MLDSA87_marshal_public_key(
    CBB *out, const struct MLDSA87_public_key *public_key);

MLDSA87_parse_public_key parses a public key, in the format generated by MLDSA87_marshal_public_key, from in and writes the result to out_public_key. It returns 1 on success or 0 on parse error or if there are trailing bytes in in.

OPENSSL_EXPORT int MLDSA87_parse_public_key(
    struct MLDSA87_public_key *public_key, CBS *in);