EVP_MAC-KMAC(7SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 EVP_MAC-KMAC 💖

okay bestie, so this is <cyan>EVP_MAC-KMAC</cyan>, <cyan>EVP_MAC-KMAC128</cyan>, and <cyan>EVP_MAC-KMAC256</cyan> — that's the whole girl gang of KMAC EVP_MAC implementations, straight out of OpenSSL. they're pages in section 7SSL ofc, iykyk. 🎀

✨ NAME ✨

EVP_MAC-KMAC, EVP_MAC-KMAC128, EVP_MAC-KMAC256 — the KMAC EVP_MAC implementations. that's the entire vibe, no cap. 🦋

🌸 DESCRIPTION 🌸

so like. these give you support for computing KMAC MACs through the EVP_MAC API. that's it, that's the job. 💅

🫶 Identity 🫶

these implementations are identified with one of these names and properties, and you use them with EVP_MAC_fetch():

  • "KMAC-128", "provider=default" or "provider=fips"
  • "KMAC-256", "provider=default" or "provider=fips"

like, pick your fighter. both are iconic. ✨

🔥 Supported parameters 🔥

the general description of these parameters lives in "PARAMETERS" in EVP_MAC(3) — go check her out if you want the deep lore.

every single one of these parameters (except for "block-size", she's special) can be set with EVP_MAC_CTX_set_params(). and then, on top of that:

  • the "size" parameter can be retrieved with EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_mac_size(). the length of the "size" parameter should not exceed that of a size_t. (that's not a vibe you want to fail.)
  • likewise, the "block-size" parameter can be retrieved with EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_block_size().

now, the parameters themselves, one by one, no skips:

  • "key" (OSSL_MAC_PARAM_KEY) <octet string> — sets the MAC key. setting this parameter is identical to passing a key to EVP_MAC_init(3). the length of the key (in bytes) must be in the range 4...512. yes those are the boundaries, don't test them. 🚫
  • "custom" (OSSL_MAC_PARAM_CUSTOM) <octet string> — sets the customization string. it's an optional value with a length of at most 512 bytes, and it is empty by default. so if you cba, you literally can skip it. 🙈
  • "size" (OSSL_MAC_PARAM_SIZE) <unsigned integer> — sets the MAC size. by default, it is 32 for "KMAC-128" and 64 for "KMAC-256". main character energy per size, honestly. 👑
  • "block-size" (OSSL_MAC_PARAM_BLOCK_SIZE) <unsigned integer> — gets the MAC block size. it is 168 for "KMAC-128" and 136 for "KMAC-256". (notice it's a get, not a set — remember, she's the exception.)
  • "xof" (OSSL_MAC_PARAM_XOF) <integer> — the "xof" parameter value is expected to be 1 or 0. use 1 to enable XOF mode. the default value is 0.
  • "fips-indicator" (OSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR) <int> — this settable parameter is described in provider-mac(7).
  • "no-short-mac" (OSSL_MAC_PARAM_FIPS_NO_SHORT_MAC) <integer> — this settable parameter is described in provider-mac(7). it is used by the OpenSSL FIPS provider and the minimum length output for KMAC is defined by NIST's SP 800-185 8.4.2. 📜
  • "key-check" (OSSL_MAC_PARAM_FIPS_KEY_CHECK) <integer> — this settable parameter is described in provider-mac(7).

and now the timing tea, because this part actually matters:

the "custom" and "no-short-mac" parameters must be set as part of or before the EVP_MAC_init() call. the "xof" and "size" parameters can be set at any time before EVP_MAC_final(). the "key" parameter is set as part of the EVP_MAC_init() call, but can be set before it instead. get the order wrong and it's giving 💀, so like, read the list twice bestie.

🌈 EXAMPLES 🌈

here's the whole thing, verbatim, copy it exactly:

#include <openssl/evp.h>
#include <openssl/params.h>

static int do_kmac(const unsigned char *in, size_t in_len,
                   const unsigned char *key, size_t key_len,
                   const unsigned char *custom, size_t custom_len,
                   int xof_enabled, unsigned char *out, int out_len)
{
    EVP_MAC_CTX *ctx = NULL;
    EVP_MAC *mac = NULL;
    OSSL_PARAM params[4], *p;
    int ret = 0;
    size_t l = 0;

    mac = EVP_MAC_fetch(NULL, "KMAC-128", NULL);
    if (mac == NULL)
        goto err;
    ctx = EVP_MAC_CTX_new(mac);
    /* The mac can be freed after it is used by EVP_MAC_CTX_new */
    EVP_MAC_free(mac);
    if (ctx == NULL)
        goto err;

    /*
     * Setup parameters required before calling EVP_MAC_init()
     * The parameters OSSL_MAC_PARAM_XOF and OSSL_MAC_PARAM_SIZE may also be
     * used at this point.
     */
    p = params;
    *p++ = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,
                                             (void *)key, key_len);
    if (custom != NULL && custom_len != 0)
      *p++ = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_CUSTOM,
                                               (void *)custom, custom_len);
    *p = OSSL_PARAM_construct_end();
    if (!EVP_MAC_CTX_set_params(ctx, params))
        goto err;

    if (!EVP_MAC_init(ctx))
        goto err;

    /*
     * Note: the following optional parameters can be set any time
     * before EVP_MAC_final().
     */
    p = params;
    *p++ = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_XOF, &xof_enabled);
    *p++ = OSSL_PARAM_construct_int(OSSL_MAC_PARAM_SIZE, &out_len);
    *p = OSSL_PARAM_construct_end();
    if (!EVP_MAC_CTX_set_params(ctx, params))
        goto err;

    /* The update may be called multiple times here for streamed input */
    if (!EVP_MAC_update(ctx, in, in_len))
        goto err;
    if (!EVP_MAC_final(ctx, out, &l, out_len))
        goto err;
    ret = 1;
err:
    EVP_MAC_CTX_free(ctx);
    return ret;
}

👀 SEE ALSO 👀

go read these next, they're all part of the same cinematic universe:

copyright 2018-2024 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!! ✨ version 4.0.3, dated 2026-09-29, from the OpenSSL crew — literally iconic, go forth and MAC responsibly 💅🎀🦋

📦 where this page comes from