EVP_MD-ML-DSA-MU(7SSL)

📦
version 4.0.3 · 2 versions
, in ubuntu stonking

💖 EVP_MD-ML-DSA-MU — the ML-DSA-MU EVP_MD implementation 💖

okay so bestie, this is the EVP_MD-ML-DSA-MU(7SSL) page from the OpenSSL manual, and it's genuinely so cool. let's get into it 🫶

✨ NAME ✨

EVP_MD-ML-DSA-MU — the ML-DSA-MU EVP_MD implementation 💅

🌸 DESCRIPTION 🌸

So basically this gives you support for computing the value of external mu for ML-DSA using the EVP_MD API. iconic.

Normally the value of "mu" gets calculated internally, as part of an ML-DSA sign or verify operation — like it just happens, no thoughts. And "mu" is defined as:

mu = SHAKE256(tr || M', 64)

Where tr is the hash of the encoded public key, and, for Pure (ML-DSA):

M' = 0x00 || ctx_len || ctx || message

Now, in cases where prehashing the message is required, FIPS 204 says it's fine to do the "mu" calculation externally, and then pass that "mu" into ML-DSA sign or verify operations. slay.

PreHash (HASH-ML-DSA) is also supported and uses:

M' = 0x01 || ctx_len || ctx || OID || HashedMessage

The output "mu" value can then be supplied as an input to EVP_SIGNATURE-ML-DSA(7) using the ML-DSA Signature Parameter OSSL_SIGNATURE_PARAM_MU (i.e. "mu"). ✨ This lets larger messages get hashed (or hidden) before they're passed to pure ML-DSA sign or verify operations. the way that just works.

🎀 Identities 🎀

This implementation is available with the FIPS provider as well as the default provider, and it's identified with the name "ML-DSA-MU".

🦋 Parameters 🦋

This implementation supports the following settable OSSL_PARAM(3) parameters:

  • "pub" (OSSL_DIGEST_PARAM_MU_PUB_KEY) <octet string> — An ML-DSA encoded public key value of size 1312, 1952 or 2592 bytes, depending on the respective key type of ML-DSA-44, ML-DSA-65 or ML-DSA-87. You can retrieve this from an EVP_PKEY-ML-DSA(7) key by calling EVP_PKEY_get_octet_string_param(key, OSSL_PKEY_PARAM_PUB_KEY, pub, sizeof(pub), &publen). This parameter MUST be set or an error will occur — no cap, it's mandatory bestie 🚨
  • "context-string" (OSSL_DIGEST_PARAM_MU_CONTEXT_STRING) <octet string> — An optional string of octets with length at most 255. By default it's the empty string.
  • "digest" (OSSL_DIGEST_PARAM_MU_DIGEST) <utf8 string> — An optional parameter related to "HASH-ML-DSA". If used, it determines the OID in the definition of PreHash M' above.

When this parameter is not specified, pure ML-DSA "mu" is computed, and the input data is expected to be the full message. Otherwise the input data must be the result of prehashing the message with the corresponding digest algorithm.

The HASH-ML-DSA variant is available to enable specialised use-cases, in which signing the full message with pure ML-DSA is not practical, and the external-mu API is a viable alternative. HASH-ML-DSA is not used in protocols such as X509 & CMS (See RFC 9981 and 9982), and is not presently implemented as an independent OpenSSL signature algorithm. iykyk.

It is the users responsibility to chose a digest that has the minimum required security strength. To match the security category for ML-DSA-44, ML-DSA-65 and ML-DSA-87 the user should chose a digest that has a security strength of at least 128 bits, 192 bits and 256 bits respectively.

OpenSSL accepts the following digest names:

  • "SHA-224" and "SHA3-224" — These digests have a security strength of 112 bits.
  • "SHA-256" and "SHA3-256" — These digests have a security strength of 128 bits.
  • "SHA-384" and "SHA3-384" — These digests have a security strength of 192 bits.
  • "SHA-512" and "SHA3-512" — These digests have a security strength of 256 bits.
  • "SHAKE-128" and "SHAKE-256" — For SHAKE-128 and SHAKE-256 the expected XOF digest lengths are 32 and 64 respectively, which correspond to a security strength of 128 and 256 bits respectively.

The total size of the "HashedMessage" passed to EVP_DigestUpdate() MUST match the size of the digest. 💀

  • "properties" (OSSL_DIGEST_PARAM_MU_PROPERTIES) <utf8 string> — Sets the properties to be queried when trying to fetch the underlying digest.

⭐ Gettable Parameters ⭐

This implementation supports the common gettable parameters described in EVP_MD-common(7). easy.

👑 CONFORMING TO 👑

FIPS 204 and https://csrc.nist.gov/csrc/media/Projects/post-quantum-cryptography/documents/faq/fips204-sec6-03192025.pdf

🌈 EXAMPLES 🌈

To generate external 'mu' given an existing ML-DSA key and a large message:

calculate_mu(EVP_PKEY *pkey, const unsigned char *msg, size_t msglen,
             const unsigned char *ctx, size_t ctxlen, unsigned char mu[64])
{
    unsigned char pub[2592];
    size_t publen = 0, chunk;
    OSSL_PARAM params[4], *p = params;

    /* Retrieve the ML-DSA encoded public key */
    EVP_PKEY_get_octet_string_param(pkey, OSSL_PKEY_PARAM_PUB_KEY,
                                    pub, sizeof(pub), &publen);

    *p++ = OSSL_PARAM_construct_octet_string(OSSL_DIGEST_PARAM_MU_PUB_KEY, pub, publen);
    /* This is an optional parameter */
    if (ctx != NULL && ctxlen != 0)
        *p++ = OSSL_PARAM_construct_octet_string(OSSL_DIGEST_PARAM_MU_CONTEXT_STRING, ctx, ctxlen);
    /*
     * Optionally we could also set the digest name for HASH-ML-DSA
     * *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DIGEST_PARAM_MU_DIGEST, "SHA-512", 0);
     */
    *p = OSSL_PARAM_construct_end();

    mdctx = EVP_MD_CTX_new();
    md = EVP_MD_fetch(libctx, "ML-DSA-MU", NULL);
    EVP_DigestInit_ex2(mdctx, md, params);
    /* Call EVP_DigestUpdate() multiple times to stream the message */
    while (msglen != 0) {
        /* Account for the last chunk being less than 64 */
        chunk = (msglen >= 64) ? 64 : msglen;
        EVP_DigestUpdate(mdctx, msg, chunk);
        msg += chunk;
        msglen -= chunk;
    }
    EVP_DigestFinalXOF(mdctx, mu, sizeof(mu))
}

like look at that streaming loop, main character energy fr 🔥

🫶 SEE ALSO 🫶

EVP_SIGNATURE-ML-DSA(7), EVP_PKEY-ML-DSA(7), provider-digest(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-default(7)

💜 HISTORY 💜

The ML-DSA-MU pseudo-digest was added in OpenSSL 4.0.0. new era behavior ✨

Copyright 2025-2026 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page bestie 🎀 you just read the OpenSSL 4.0.3 documentation for EVP_MD-ML-DSA-MU(7SSL), dated 2026-09-29. go forth and compute some external mu, you ate 💅🌸✨

📦 where this page comes from