/docs/man3.3/man7/EVP_KDF-KB.html

EVP_KDF-KB

名称

EVP_KDF-KB - 基于密钥的EVP_KDF实现

描述

EVP_KDF-KB算法实现了基于密钥的密钥派生函数（KBKDF）。KBKDF通过对输入密钥（和其他可选值）重复应用带密钥的MAC来派生密钥。

标识

“KBKDF”是此实现的名称；它可以与EVP_KDF_fetch()函数一起使用。

支持的参数

支持的参数为：

"mode" (OSSL_KDF_PARAM_MODE) <UTF8字符串>

mode参数决定使用哪种类型的KBKDF - 目前可以选择“counter”和“feedback”。“counter”为默认值，如果未指定则将使用它。

"mac" (OSSL_KDF_PARAM_MAC) <UTF8字符串>

该值为CMAC、HMAC、KMAC128或KMAC256。

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8字符串>

"cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8字符串>

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8字符串>

"key" (OSSL_KDF_PARAM_KEY) <八位字节串>

"salt" (OSSL_KDF_PARAM_SALT) <八位字节串>

"info (OSSL_KDF_PARAM_INFO) <八位字节串>

"seed" (OSSL_KDF_PARAM_SEED) <八位字节串>

seed参数在计数器模式下未使用。

"use-l" (OSSL_KDF_PARAM_KBKDF_USE_L) <整数>

设置为0以禁用使用可选的固定输入数据'L'（参见SP800-108）。如果未指定，则将使用默认值1。

"use-separator" (OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR) <整数>

设置为0以禁用使用可选的固定输入数据'零分隔符'（参见SP800-108），该分隔符位于标签和上下文之间。如果未指定，则将使用默认值1。

"r" (OSSL_KDF_PARAM_KBKDF_R) <整数>

设置固定值'r'，指示计数器的长度（以位为单位）。

支持的值为8、16、24和32。如果未指定，则将使用默认值32。

根据mac是CMAC还是HMAC，digest或cipher（分别）是必需的，另一个则未使用。它们在KMAC128和KMAC256中未使用。

参数key、salt、info和seed分别对应于SP800-108中的KI、Label、Context和IV。与该文档一样，salt、info和seed是可选的，可以省略。

"mac"、"digest"、cipher"和"properties"在"EVP_KDF(3)中的PARAMETERS"中进行了描述。

备注

可以通过调用以下方法获取KBKDF的上下文：

EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);

KBKDF的输出长度通过EVP_KDF_derive(3)函数的keylen参数指定。

请注意，目前OpenSSL仅实现了计数器和反馈模式。将来可能会支持其他变体。

示例

此示例使用COUNTER-HMAC-SHA256派生10个字节，其中KI为“secret”，Label为“label”，Context为“context”。

EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[6], *p = params;

kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);

*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
                                        "SHA2-256", 0);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
                                        "HMAC", 0);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                         "secret", strlen("secret"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                         "label", strlen("label"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                         "context", strlen("context"));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
    error("EVP_KDF_derive");

EVP_KDF_CTX_free(kctx);

此示例使用FEEDBACK-CMAC-AES256派生10个字节，其中KI为“secret”，Label为“label”，IV为“十六个字节的iv”。

EVP_KDF *kdf;
EVP_KDF_CTX *kctx;
unsigned char out[10];
OSSL_PARAM params[8], *p = params;
unsigned char *iv = "sixteen bytes iv";

kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);

*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                         "secret", strlen("secret"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                         "label", strlen("label"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
                                         "context", strlen("context"));
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
                                         iv, strlen(iv));
*p = OSSL_PARAM_construct_end();
if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0)
    error("EVP_KDF_derive");

EVP_KDF_CTX_free(kctx);

符合标准

NIST SP800-108、IETF RFC 6803、IETF RFC 8009。

参见

EVP_KDF(3)、EVP_KDF_CTX_free(3)、EVP_KDF_CTX_get_kdf_size(3)、EVP_KDF_derive(3)、"EVP_KDF(3)中的PARAMETERS"

历史

此功能在OpenSSL 3.0中添加。

对KMAC的支持是在OpenSSL 3.1中添加的。

版权

根据Apache许可证2.0版（“许可证”）获得许可。除非符合许可证，否则您不得使用此文件。您可以在源代码分发中的LICENSE文件中或https://www.openssl.org/source/license.html中获取副本。