EVP_MAC-KMAC.7ossl - Man Page

EVP_MAC-KMAC, EVP_MAC-KMAC128, EVP_MAC-KMAC256 ​- The KMAC EVP_MAC implementations

Description

Support for computing KMAC MACs through the EVP_MAC API.

Identity

These implementations are identified with one of these names and properties, to be used with EVP_MAC_fetch():

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

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

Supported parameters

The general description of these parameters can be found in "PARAMETERS" in EVP_MAC(3).

All these parameters (except for "block-size") can be set with ​EVP_MAC_CTX_set_params(). Furthermore, 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. Likewise, the "block-size" parameter can be retrieved with ​EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_block_size().

"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.

"custom" (OSSL_MAC_PARAM_CUSTOM) <octet string>

Sets the customization string. It is an optional value with a length of at most 512 bytes, and is empty by default.

"size" (OSSL_MAC_PARAM_SIZE) <unsigned integer>

Sets the MAC size. By default, it is 32 for KMAC-128 and 64 for KMAC-256.

"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.

"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).

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.

Examples

​  #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

EVP_MAC_CTX_get_params(3), EVP_MAC_CTX_set_params(3), "PARAMETERS" in EVP_MAC(3), OSSL_PARAM(3), SP 800-185 8.4.2 <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf>

Referenced By

EVP_MAC.3ossl(3), fips_module.7ossl(7), openssl-mac.1ossl(1), ossl-guide-migration.7ossl(7), OSSL_PROVIDER-default.7ossl(7), OSSL_PROVIDER-FIPS.7ossl(7), provider-mac.7ossl(7).

The man pages EVP_MAC-KMAC128.7ossl(7) and EVP_MAC-KMAC256.7ossl(7) are aliases of EVP_MAC-KMAC.7ossl(7).

2026-08-25 4.0.2 OpenSSL