EVP_MAC-KMAC7ssl
The kmac evp_mac implementations
Overview
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;}
Releases
3 releases since Debian 12 (Bookworm); the text changed 2 times.