OpenSSL

密码学和 SSL/TLS 工具包

provider-kdf

名称

provider-kdf - KDF 库 <-> 提供者函数

概要

#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>

/*
 * None of these are actual functions, but are displayed like this for
 * the function signatures for functions that are offered as function
 * pointers in OSSL_DISPATCH arrays.
 */

/* Context management */
void *OSSL_FUNC_kdf_newctx(void *provctx);
void OSSL_FUNC_kdf_freectx(void *kctx);
void *OSSL_FUNC_kdf_dupctx(void *src);

/* Encryption/decryption */
int OSSL_FUNC_kdf_reset(void *kctx);
int OSSL_FUNC_kdf_derive(void *kctx, unsigned char *key, size_t keylen,
                         const OSSL_PARAM params[]);

/* KDF parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_kdf_gettable_params(void *provctx);
const OSSL_PARAM *OSSL_FUNC_kdf_gettable_ctx_params(void *kcxt, void *provctx);
const OSSL_PARAM *OSSL_FUNC_kdf_settable_ctx_params(void *kcxt, void *provctx);

/* KDF parameters */
int OSSL_FUNC_kdf_get_params(OSSL_PARAM params[]);
int OSSL_FUNC_kdf_get_ctx_params(void *kctx, OSSL_PARAM params[]);
int OSSL_FUNC_kdf_set_ctx_params(void *kctx, const OSSL_PARAM params[]);

描述

此文档主要面向提供者作者。有关更多信息，请参阅 provider(7)。

KDF 操作使提供者能够实现 KDF 算法并通过 API 函数 EVP_KDF_CTX_reset(3) 和 EVP_KDF_derive(3) 使其可供应用程序使用。

这里提到的所有“函数”都作为函数指针在 libcrypto 和提供者之间通过 OSSL_DISPATCH(3) 数组传递，通过 OSSL_ALGORITHM(3) 数组，这些数组由提供者的 provider_query_operation() 函数返回（请参阅 provider-base(7) 中的“提供者函数”）。

所有这些“函数”都有一个名为 OSSL_FUNC_{name}_fn 的对应函数类型定义，以及一个用于从 OSSL_DISPATCH(3) 元素中检索函数指针的辅助函数，名为 OSSL_FUNC_{name}。例如，“函数”OSSL_FUNC_kdf_newctx() 具有这些

typedef void *(OSSL_FUNC_kdf_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_kdf_newctx_fn
    OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) 数组条目由在 openssl-core_dispatch.h(7) 中作为宏提供的数字标识，如下所示

OSSL_FUNC_kdf_newctx               OSSL_FUNC_KDF_NEWCTX
OSSL_FUNC_kdf_freectx              OSSL_FUNC_KDF_FREECTX
OSSL_FUNC_kdf_dupctx               OSSL_FUNC_KDF_DUPCTX

OSSL_FUNC_kdf_reset                OSSL_FUNC_KDF_RESET
OSSL_FUNC_kdf_derive               OSSL_FUNC_KDF_DERIVE

OSSL_FUNC_kdf_get_params           OSSL_FUNC_KDF_GET_PARAMS
OSSL_FUNC_kdf_get_ctx_params       OSSL_FUNC_KDF_GET_CTX_PARAMS
OSSL_FUNC_kdf_set_ctx_params       OSSL_FUNC_KDF_SET_CTX_PARAMS

OSSL_FUNC_kdf_gettable_params      OSSL_FUNC_KDF_GETTABLE_PARAMS
OSSL_FUNC_kdf_gettable_ctx_params  OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS
OSSL_FUNC_kdf_settable_ctx_params  OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS

KDF 算法实现可能不会实现所有这些函数。为了成为一组一致的函数，至少必须实现以下函数：OSSL_FUNC_kdf_newctx()、OSSL_FUNC_kdf_freectx()、OSSL_FUNC_kdf_set_ctx_params()、OSSL_FUNC_kdf_derive()。所有其他函数都是可选的。

上下文管理函数

OSSL_FUNC_kdf_newctx() 应该创建并返回一个指向提供者端结构的指针，用于在 KDF 操作期间保存上下文信息。此上下文的指针将在许多其他 KDF 操作函数调用中传递回来。参数 provctx 是在提供者初始化期间生成的提供者上下文（请参阅 provider(7)）。

OSSL_FUNC_kdf_freectx() 将 kctx 参数中的指针传递给提供者端的 KDF 上下文。如果它收到 kctx 值为 NULL，则它不应该执行任何操作，而应返回。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_kdf_dupctx() 应该复制 kctx 参数中的提供者端的 KDF 上下文，并返回副本。

加密/解密函数

OSSL_FUNC_kdf_reset() 在处理 params 按照 OSSL_FUNC_kdf_set_ctx_params() 后，初始化一个 KDF 操作，该操作给定 kctx 参数中的提供者端的 KDF 上下文。

OSSL_FUNC_kdf_derive() 在处理 params 按照 OSSL_FUNC_kdf_set_ctx_params() 后，执行 KDF 操作。kctx 参数包含指向提供者端上下文的指针。应将所需 keylen 的结果密钥写入 key。如果算法不支持请求的 keylen，则该函数必须返回错误。

KDF 参数

有关这些函数使用的参数结构的更多详细信息，请参阅 OSSL_PARAM(3)。

OSSL_FUNC_kdf_get_params() 获取与提供者算法关联的参数值的详细信息，并将它们存储在 params 中。

OSSL_FUNC_kdf_set_ctx_params() 将与给定提供者端 KDF 上下文 kctx 关联的 KDF 参数设置为 params。任何参数设置都是对先前设置的任何参数的补充。将 params 设为 NULL 应该返回 true。

OSSL_FUNC_kdf_get_ctx_params() 检索与给定提供者端 KDF 上下文 kctx 关联的可获取参数值，并将它们存储在 params 中。将 params 设为 NULL 应该返回 true。

OSSL_FUNC_kdf_gettable_params()、OSSL_FUNC_kdf_gettable_ctx_params() 和 OSSL_FUNC_kdf_settable_ctx_params() 都返回常量 OSSL_PARAM(3) 数组，作为 OSSL_FUNC_kdf_get_params()、OSSL_FUNC_kdf_get_ctx_params() 和 OSSL_FUNC_kdf_set_ctx_params() 可以分别处理的参数的描述符。OSSL_FUNC_kdf_gettable_ctx_params() 和 OSSL_FUNC_kdf_settable_ctx_params() 将返回与提供者端上下文 kctx 关联的参数，该参数处于其当前状态，如果它不是 NULL。否则，它们返回与提供者端算法 provctx 关联的参数。

内置 KDF 目前识别的参数如下。并非所有参数都与所有 KDF 相关或被所有 KDF 理解

"size" (OSSL_KDF_PARAM_SIZE)

从关联的 KDF ctx 获取输出大小。如果算法产生可变数量的输出，则应返回 SIZE_MAX。如果计算固定输出大小所需的输入参数尚未提供，则应返回 0，表示错误。

"key" (OSSL_KDF_PARAM_KEY)

设置关联的 KDF ctx 中的密钥。

"secret" (OSSL_KDF_PARAM_SECRET)

设置关联的 KDF ctx 中的密钥。

"pass" (OSSL_KDF_PARAM_PASSWORD)

设置关联的 KDF ctx 中的密码。

"cipher" (OSSL_KDF_PARAM_CIPHER)
"digest" (OSSL_KDF_PARAM_DIGEST)
"mac" (OSSL_KDF_PARAM_MAC)

设置要使用的底层密码、摘要或 MAC 的名称。它必须为正在使用的 KDF 指定一个合适的算法。

"maclen" (OSSL_KDF_PARAM_MAC_SIZE)

设置关联的 KDF ctx 中 MAC 的长度。

"properties" (OSSL_KDF_PARAM_PROPERTIES)

设置在尝试获取底层算法时要查询的属性。此属性必须与算法命名参数一起给出才能被视为有效。

"iter" (OSSL_KDF_PARAM_ITER)

设置关联的 KDF ctx 中的迭代次数。

"mode" (OSSL_KDF_PARAM_MODE)

设置关联的 KDF ctx 中的模式。

"pkcs5" (OSSL_KDF_PARAM_PKCS5)

启用或禁用 SP800-132 合规性检查。模式 0 启用合规性检查。

执行的检查是

- 迭代次数至少为 1000。
- 盐的长度至少为 128 位。
- 派生密钥的长度至少为 112 位。
"ukm" (OSSL_KDF_PARAM_UKM)

设置发送方提供的可选随机字符串，称为“partyAInfo”。在 CMS 中，这是用户加钥材料。

"cekalg" (OSSL_KDF_PARAM_CEK_ALG)

设置关联的 KDF ctx 中的 CEK 包装算法名称。

"n" (OSSL_KDF_PARAM_SCRYPT_N)

设置关联的 KDF ctx 中的 scrypt 工作因子参数 N。

"r" (OSSL_KDF_PARAM_SCRYPT_R)

设置关联的 KDF ctx 中的 scrypt 工作因子参数 r。

"p" (OSSL_KDF_PARAM_SCRYPT_P)

设置关联的 KDF ctx 中的 scrypt 工作因子参数 p。

"maxmem_bytes" (OSSL_KDF_PARAM_SCRYPT_MAXMEM)

设置关联的 KDF ctx 中的 scrypt 工作因子参数 maxmem。

"prefix" (OSSL_KDF_PARAM_PREFIX)

设置关联的 KDF ctx 中 TLS 1.3 版本的 HKDF 使用的前缀字符串。

"label" (OSSL_KDF_PARAM_LABEL)

设置关联的 KDF ctx 中 TLS 1.3 版本的 HKDF 使用的标签字符串。

"data" (OSSL_KDF_PARAM_DATA)

设置关联的 KDF ctx 中 TLS 1.3 版本的 HKDF 使用的上下文字符串。

"info" (OSSL_KDF_PARAM_INFO)

设置关联的 KDF ctx 中的可选共享信息。

"seed" (OSSL_KDF_PARAM_SEED)

设置关联的 KDF ctx 中的 IV。

"xcghash" (OSSL_KDF_PARAM_SSHKDF_XCGHASH)

设置关联的 KDF ctx 中的 xcghash。

"session_id" (OSSL_KDF_PARAM_SSHKDF_SESSION_ID)

设置关联的 KDF ctx 中的会话 ID。

"type" (OSSL_KDF_PARAM_SSHKDF_TYPE)

设置关联的 KDF ctx 中的 SSH KDF 类型参数。有六种支持的类型

EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV

从客户端到服务器的初始 IV。一个值为 65（ASCII 字符 'A'）的单个字符。

EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI

从服务器到客户端的初始 IV 一个值为 66（ASCII 字符 'B'）的单个字符。

EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV

从客户端到服务器的加密密钥 一个值为 67（ASCII 字符 'C'）的单个字符。

EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI

从服务器到客户端的加密密钥 一个值为 68（ASCII 字符 'D'）的单个字符。

EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV

从客户端到服务器的完整性密钥 一个值为 69（ASCII 字符 'E'）的单个字符。

EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI

从客户端到服务器的完整性密钥 一个值为 70（ASCII 字符 'F'）的单个字符。

"constant" (OSSL_KDF_PARAM_CONSTANT)

设置关联的 KDF ctx 中的常数值。

"id" (OSSL_KDF_PARAM_PKCS12_ID)

设置关联的 KDF ctx 中输出位的预期用途。它按 RFC 7292 第 B.3 节定义。

返回值

OSSL_FUNC_kdf_newctx() 和 OSSL_FUNC_kdf_dupctx() 应该返回新创建的提供者端 KDF 上下文，或者在失败时返回 NULL。

OSSL_FUNC_kdf_derive()、OSSL_FUNC_kdf_get_params()、OSSL_FUNC_kdf_get_ctx_params() 和 OSSL_FUNC_kdf_set_ctx_params() 应该在成功时返回 1，在错误时返回 0。

OSSL_FUNC_kdf_gettable_params()、OSSL_FUNC_kdf_gettable_ctx_params() 和 OSSL_FUNC_kdf_settable_ctx_params() 应该返回一个常量 OSSL_PARAM(3) 数组，或者如果未提供任何数组，则返回 NULL。

注释

KDF 生命周期在 life_cycle-kdf(7) 中描述。提供者应确保支持那里列出的各种过渡。EVP 层将在某个时刻开始强制执行列出的过渡。

参见

provider(7)、life_cycle-kdf(7)、EVP_KDF(3)。

历史

提供者 KDF 接口是在 OpenSSL 3.0 中引入的。

版权所有 2020-2022 The OpenSSL Project Authors。保留所有权利。

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