《OpenSSL3.0学习之二十提供程序-kdf》-CFANZ编程社区

文章目录

🌺概要

 #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[]);

🌻描述

本文档主要面向提供程序作者。有关详细信息，请参阅提供程序。

KDF 操作使提供程序能够实现 KDF 算法，并通过 API 函数 EVP_KDF_CTX_reset 和 EVP_KDF_derive 将其提供给应用程序。

这里提到的所有"函数"都作为函数指针在libcrypto和OSSL_DISPATCH数组中的提供程序之间传递，通过由提供程序的**provider_query_operation（）**函数返回的OSSL_ALGORITHM数组（参见提供程序-base中的"提供程序函数"）。

所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"OSSL_FUNC_kdf_newctx（）具有以下功能：

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

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

 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 是在提供程序初始化期间生成的提供程序上下文（参见提供程序）。

OSSL_FUNC_kdf_freectx（）在 kctx 参数中传递指向提供程序端 KDF 上下文的指针。如果它接收 NULL 作为 kctx 值，则除了返回之外，它不应执行任何其他操作。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_kdf_dupctx（）应在 kctx 参数中复制提供程序端 KDF 上下文并返回重复的副本。

🌷加密/解密函数

OSSL_FUNC_kdf_reset（）在 kctx 参数中给定提供者端 KDF 上下文的情况下初始化 KDF 操作。

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

🌼KDF 参数

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

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数组，作为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) < unsigned integer >
从关联的 KDF ctx 获取输出大小。如果算法生成可变量的输出，则应返回SIZE_MAX。如果尚未提供计算固定输出大小所需的输入参数，则应返回 0 以指示错误。
“key” （OSSL_KDF_PARAM_KEY） < octet string >
在关联的 KDF ctx 中设置密钥。
“secret” (OSSL_KDF_PARAM_SECRET) < octet string >
在关联的 KDF ctx 中设置密钥。
“pass” (OSSL_KDF_PARAM_PASSWORD) < octet string >
在关联的 KDF ctx 中设置密码。
“cipher” (OSSL_KDF_PARAM_CIPHER) < UTF8 string >
“digest” (OSSL_KDF_PARAM_DIGEST) < UTF8 string >
“mac” (OSSL_KDF_PARAM_MAC) < UTF8 string >
设置要使用的基础密码、摘要或 MAC 的名称。它必须为正在使用的 KDF 命名合适的算法。
“maclen” (OSSL_KDF_PARAM_MAC_SIZE) < octet string >
在关联的 KDF ctx 中设置 MAC 的长度。
“properties” (OSSL_KDF_PARAM_PROPERTIES) < UTF8 string >
设置在尝试获取基础算法时要查询的属性。这必须与算法命名参数一起给出，才能被视为有效。
“iter” (OSSL_KDF_PARAM_ITER) < unsigned integer >
设置关联的 KDF ctx 中的迭代次数。
“mode” (OSSL_KDF_PARAM_MODE) < UTF8 string >
在关联的 KDF ctx 中设置模式。
“pkcs5” (OSSL_KDF_PARAM_PKCS5) < integer >
启用或禁用 SP800-132 合规性检查。模式 0 将启用合规性检查。
执行的检查包括：
1. 迭代计数至少为 1000。
2. 盐的长度至少为128位。
3. 派生的密钥长度至少为 112 位。
“ukm” (OSSL_KDF_PARAM_UKM) < octet string >
设置由发件人提供的名为"partyAInfo"的可选随机字符串。在CMS中，这是用户密钥材料。
“cekalg” (OSSL_KDF_PARAM_CEK_ALG) < UTF8 string >
在关联的 KDF ctx 中设置 CEK 包装算法名称。
“n” (OSSL_KDF_PARAM_SCRYPT_N) < unsigned integer >
在关联的 KDF ctx 中设置 scrypt 工作因子参数 N。
“r” (OSSL_KDF_PARAM_SCRYPT_R) < unsigned integer >
在关联的 KDF ctx 中设置隐蔽工作因子参数 r。
“p” (OSSL_KDF_PARAM_SCRYPT_P) < unsigned integer >
在关联的 KDF ctx 中设置 scrypt 工作因子参数 p。
“maxmem_bytes” (OSSL_KDF_PARAM_SCRYPT_MAXMEM) < unsigned integer >
在关联的 KDF ctx 中设置 scrypt 工作因子参数 maxmem。
“prefix” (OSSL_KDF_PARAM_PREFIX) < octet string >
设置由 TLS 1.3 版本的 HKDF 在关联的 KDF ctx 中使用的前缀字符串。
“label” (OSSL_KDF_PARAM_LABEL) < octet string >
设置由 TLS 1.3 版本的 HKDF 在关联的 KDF ctx 中使用的标签字符串。
“data” (OSSL_KDF_PARAM_DATA) < octet string >
在关联的 KDF ctx 中使用由 TLS 1.3 版本的 HKDF 使用的上下文字符串。
“info” (OSSL_KDF_PARAM_INFO) < octet string >
在关联的 KDF ctx 中设置可选的共享信息。
“seed” (OSSL_KDF_PARAM_SEED) < octet string >
在关联的 KDF ctx 中设置 IV。
“xcghash” (OSSL_KDF_PARAM_SSHKDF_XCGHASH) < octet string >
在关联的 KDF ctx 中设置 xcghash。
“session_id” (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) < octet string >
在关联的 KDF ctx 中设置会话 ID。
“type” (OSSL_KDF_PARAM_SSHKDF_TYPE) < UTF8 string >
在关联的 KDF ctx 中设置 SSH KDF 类型参数。有六种受支持的类型：
1. EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
  从客户端到服务器的初始 IV。值为 65 的单个字符（ASCII 字符"A"）。
2. EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
  从服务器到客户端的初始 IV 值为 66 的单个字符（ASCII 字符"B"）。
3. EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV
  从客户端到服务器的加密密钥值为 67 的单个字符（ASCII 字符"C"）。
4. EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI
  从服务器到客户端的加密密钥值为 68 的单个字符（ASCII 字符"D"）。
5. EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV
  从客户端到服务器的完整性密钥值为 69 的单个字符（ASCII 字符"E"）。
6. EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI
  从客户端到服务器的完整性密钥值为 70 的单个字符（ASCII 字符"F"）。
“constant” (OSSL_KDF_PARAM_CONSTANT) < octet string >
在关联的 KDF ctx 中设置常量值。
“id” (OSSL_KDF_PARAM_PKCS12_ID) < integer >
设置关联 KDF ctx 中输出位的预期用法。它根据 RFC 7292 B.3 节进行定义。