開放SSL

EVP_MAC-KMAC256

名稱

EVP_MAC-KMAC、EVP_MAC-KMAC128、EVP_MAC-KMAC256 - KMAC EVP_MAC 實作

描述

透過 EVP_MAC API 支援計算 KMAC MAC。

身分

這些實作會識別為下列名稱和屬性之一，與 EVP_MAC_fetch() 搭配使用

"KMAC-128"、"provider=default" 或 "provider=fips"

"KMAC-256"、"provider=default" 或 "provider=fips"

支援的參數

這些參數的一般說明可以在 EVP_MAC(3) 中的「參數」 中找到。

所有這些參數（「區塊大小」除外）都可以使用 EVP_MAC_CTX_set_params() 設定。此外，「大小」參數可以使用 EVP_MAC_CTX_get_params() 或 EVP_MAC_CTX_get_mac_size() 擷取。size_t 的長度不應超過「大小」參數的長度。同樣地，「區塊大小」參數可以使用 EVP_MAC_CTX_get_params() 或 EVP_MAC_CTX_get_block_size() 擷取。

"金鑰" (OSSL_MAC_PARAM_KEY) <八位元組字串>

設定 MAC 金鑰。設定此參數等同於將 金鑰 傳遞給 EVP_MAC_init(3)。金鑰的長度（以位元組為單位）必須在 4...512 的範圍內。

"自訂" (OSSL_MAC_PARAM_CUSTOM) <八位元組字串>

設定自訂字串。這是一個長度最多為 512 位元組的選用值，預設為空。

"大小" (OSSL_MAC_PARAM_SIZE) <未簽署整數>

設定 MAC 大小。預設值為 KMAC-128 的 32 和 KMAC-256 的 64。

"區塊大小" (OSSL_MAC_PARAM_BLOCK_SIZE) <未簽署整數>

取得 MAC 區塊大小。KMAC-128 為 168，KMAC-256 為 136。

"xof" (OSSL_MAC_PARAM_XOF) <整數>

"xof" 參數值預期為 1 或 0。使用 1 來啟用 XOF 模式。預設值為 0。

「自訂」參數必須在 EVP_MAC_init() 呼叫中或呼叫之前設定。「xof」和「size」參數可以在 EVP_MAC_final() 之前隨時設定。「key」參數在 EVP_MAC_init() 呼叫中設定，但也可以在呼叫之前設定。

範例

#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;
}

另請參閱

EVP_MAC_CTX_get_params(3)、EVP_MAC_CTX_set_params(3)、EVP_MAC(3) 中的「PARAMETERS」、OSSL_PARAM(3)

版權

Copyright 2018-2021 The OpenSSL Project Authors。保留所有權利。

在 Apache License 2.0（「授權」）下授權。您只能在遵守授權的情況下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案或在 https://www.openssl.org/source/license.html 中取得副本。