文章目录
🌺概要
#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_signature_newctx(void *provctx);
void OSSL_FUNC_signature_freectx(void *ctx);
void *OSSL_FUNC_signature_dupctx(void *ctx);
/* Signing */
int OSSL_FUNC_signature_sign_init(void *ctx, void *provkey,
const OSSL_PARAM params[]);
int OSSL_FUNC_signature_sign(void *ctx, unsigned char *sig, size_t *siglen,
size_t sigsize, const unsigned char *tbs, size_t tbslen);
/* Verifying */
int OSSL_FUNC_signature_verify_init(void *ctx, void *provkey,
const OSSL_PARAM params[]);
int OSSL_FUNC_signature_verify(void *ctx, const unsigned char *sig, size_t siglen,
const unsigned char *tbs, size_t tbslen);
/* Verify Recover */
int OSSL_FUNC_signature_verify_recover_init(void *ctx, void *provkey,
const OSSL_PARAM params[]);
int OSSL_FUNC_signature_verify_recover(void *ctx, unsigned char *rout,
size_t *routlen, size_t routsize,
const unsigned char *sig, size_t siglen);
/* Digest Sign */
int OSSL_FUNC_signature_digest_sign_init(void *ctx, const char *mdname,
const char *props, void *provkey,
const OSSL_PARAM params[]);
int OSSL_FUNC_signature_digest_sign_update(void *ctx, const unsigned char *data,
size_t datalen);
int OSSL_FUNC_signature_digest_sign_final(void *ctx, unsigned char *sig,
size_t *siglen, size_t sigsize);
int OSSL_FUNC_signature_digest_sign(void *ctx,
unsigned char *sigret, size_t *siglen,
size_t sigsize, const unsigned char *tbs,
size_t tbslen);
/* Digest Verify */
int OSSL_FUNC_signature_digest_verify_init(void *ctx, const char *mdname,
const char *props, void *provkey,
const OSSL_PARAM params[]);
int OSSL_FUNC_signature_digest_verify_update(void *ctx,
const unsigned char *data,
size_t datalen);
int OSSL_FUNC_signature_digest_verify_final(void *ctx, const unsigned char *sig,
size_t siglen);
int OSSL_FUNC_signature_digest_verify(void *ctx, const unsigned char *sig,
size_t siglen, const unsigned char *tbs,
size_t tbslen);
/* Signature parameters */
int OSSL_FUNC_signature_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_signature_gettable_ctx_params(void *ctx,
void *provctx);
int OSSL_FUNC_signature_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_signature_settable_ctx_params(void *ctx,
void *provctx);
/* MD parameters */
int OSSL_FUNC_signature_get_ctx_md_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM * OSSL_FUNC_signature_gettable_ctx_md_params(void *ctx);
int OSSL_FUNC_signature_set_ctx_md_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM * OSSL_FUNC_signature_settable_ctx_md_params(void *ctx);
🌻描述
本文档主要面向提供程序作者。有关详细信息，请参阅提供程序。
签名（OSSL_OP_SIGNATURE）操作使提供程序能够实现签名算法，并通过API函数EVP_PKEY_sign，EVP_PKEY_verify和EVP_PKEY_verify_recover（以及其他相关函数）将其提供给应用程序。
这里提到的所有"函数"都作为函数指针在libcrypto和OSSL_DISPATCH数组中的提供程序之间传递，通过由提供程序的provider_query_operation（）函数返回的OSSL_ALGORITHM数组（参见提供程序-base中的"提供程序函数"）。
所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"OSSL_FUNC_signature_newctx（） 具有以下功能：
typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_signature_newctx_fn
OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf);
OSSL_DISPATCH数组由 openssl-core_dispatch.h中作为宏提供的数字编制索引，如下所示：
OSSL_FUNC_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX
OSSL_FUNC_signature_freectx OSSL_FUNC_SIGNATURE_FREECTX
OSSL_FUNC_signature_dupctx OSSL_FUNC_SIGNATURE_DUPCTX
OSSL_FUNC_signature_sign_init OSSL_FUNC_SIGNATURE_SIGN_INIT
OSSL_FUNC_signature_sign OSSL_FUNC_SIGNATURE_SIGN
OSSL_FUNC_signature_verify_init OSSL_FUNC_SIGNATURE_VERIFY_INIT
OSSL_FUNC_signature_verify OSSL_FUNC_SIGNATURE_VERIFY
OSSL_FUNC_signature_verify_recover_init OSSL_FUNC_SIGNATURE_VERIFY_RECOVER_INIT
OSSL_FUNC_signature_verify_recover OSSL_FUNC_SIGNATURE_VERIFY_RECOVER
OSSL_FUNC_signature_digest_sign_init OSSL_FUNC_SIGNATURE_DIGEST_SIGN_INIT
OSSL_FUNC_signature_digest_sign_update OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE
OSSL_FUNC_signature_digest_sign_final OSSL_FUNC_SIGNATURE_DIGEST_SIGN_FINAL
OSSL_FUNC_signature_digest_sign OSSL_FUNC_SIGNATURE_DIGEST_SIGN
OSSL_FUNC_signature_digest_verify_init OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_INIT
OSSL_FUNC_signature_digest_verify_update OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_UPDATE
OSSL_FUNC_signature_digest_verify_final OSSL_FUNC_SIGNATURE_DIGEST_VERIFY_FINAL
OSSL_FUNC_signature_digest_verify OSSL_FUNC_SIGNATURE_DIGEST_VERIFY
OSSL_FUNC_signature_get_ctx_params OSSL_FUNC_SIGNATURE_GET_CTX_PARAMS
OSSL_FUNC_signature_gettable_ctx_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_PARAMS
OSSL_FUNC_signature_set_ctx_params OSSL_FUNC_SIGNATURE_SET_CTX_PARAMS
OSSL_FUNC_signature_settable_ctx_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_PARAMS
OSSL_FUNC_signature_get_ctx_md_params OSSL_FUNC_SIGNATURE_GET_CTX_MD_PARAMS
OSSL_FUNC_signature_gettable_ctx_md_params OSSL_FUNC_SIGNATURE_GETTABLE_CTX_MD_PARAMS
OSSL_FUNC_signature_set_ctx_md_params OSSL_FUNC_SIGNATURE_SET_CTX_MD_PARAMS
OSSL_FUNC_signature_settable_ctx_md_params OSSL_FUNC_SIGNATURE_SETTABLE_CTX_MD_PARAMS
签名算法实现可能无法实现所有这些功能。为了成为一组一致的函数，我们必须至少有一组上下文函数（OSSL_FUNC_signature_newctx和OSSL_FUNC_signature_freectx）以及一组"签名"函数，即至少一个：
OSSL_FUNC_signature_sign_init和OSSL_FUNC_signature_sign
OSSL_FUNC_signature_verify_init和OSSL_FUNC_signature_verify
OSSL_FUNC_signature_verify_recover_init和OSSL_FUNC_signature_verify_init
OSSL_FUNC_signature_digest_sign_init、OSSL_FUNC_signature_digest_sign_update和OSSL_FUNC_signature_digest_sign_final
OSSL_FUNC_signature_digest_verify_init、OSSL_FUNC_signature_digest_verify_update和OSSL_FUNC_signature_digest_verify_final
OSSL_FUNC_signature_digest_sign_init和OSSL_FUNC_signature_digest_sign
OSSL_FUNC_signature_digest_verify_init和OSSL_FUNC_signature_digest_verify
OSSL_FUNC_signature_set_ctx_params和OSSL_FUNC_signature_settable_ctx_params是可选的，但如果其中一个存在，那么另一个也必须存在。这同样适用于OSSL_FUNC_signature_get_ctx_params和OSSL_FUNC_signature_gettable_ctx_params以及"md_params"功能。OSSL_FUNC_signature_dupctx功能是可选的。
签名算法还必须实现一些机制，以便通过密钥管理 （OSSL_OP_KEYMGMT） 操作生成、加载或导入密钥。有关详细信息，请参阅提供程序-keymgmt。
🌹上下文管理功能
OSSL_FUNC_signature_newctx（） 应创建并返回指向提供程序端结构的指针，以便在签名操作期间保存上下文信息。指向此上下文的指针将在许多其他签名操作函数调用中传递回去。参数 provctx 是在提供程序初始化期间生成的提供程序上下文（参见提供程序）。
OSSL_FUNC_signature_freectx（） 在 ctx 参数中传递指向提供程序端签名上下文的指针。此函数应释放与该上下文关联的任何资源。
OSSL_FUNC_signature_dupctx（） 应在 ctx 参数中复制提供程序端签名上下文并返回重复的副本。
🌷签名函数
OSSL_FUNC_signature_sign_init（） 初始化用于签名的上下文，给定 ctx 参数中的提供程序端签名上下文，以及指向 provkey 参数中提供程序密钥对象的指针。参数（如果不是 NULL），则应以类似于使用 OSSL_FUNC_signature_set_ctx_params（） 的方式在上下文中设置。密钥对象应已于先前使用密钥管理 （OSSL_OP_KEYMGMT） 操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt）。
OSSL_FUNC_signature_sign（） 执行实际签名本身。在 ctx 参数中传递以前初始化的签名上下文。要签名的数据被指向 tbs 参数，该参数的长度为 tbslen 字节。除非 sig 为 NULL，否则签名应写入 sig 参数所指向的位置，并且长度不应超过 sigsize 字节。签名的长度应写入 *siglen。如果 sig 为 NULL，则签名的最大长度应写入 *siglen。
🌼验证函数
OSSL_FUNC_signature_verify_init（） 初始化一个上下文，用于验证在 ctx 参数中给定提供者端签名上下文的签名，并在 provkey 参数中初始化指向提供者密钥对象的指针。参数（如果不是 NULL），则应以类似于使用 OSSL_FUNC_signature_set_ctx_params（） 的方式在上下文中设置。密钥对象应已于先前使用密钥管理 （OSSL_OP_KEYMGMT） 操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt）。
OSSL_FUNC_signature_verify（） 执行实际验证本身。在 ctx 参数中传递以前初始化的签名上下文。签名覆盖的数据指向 tbs 参数，该参数的长度为 tbslen 字节。签名由 sig 参数指向，该参数的长度为 siglen 字节。
🌸验证恢复功能
OSSL_FUNC_signature_verify_recover_init（） 初始化用于在 ctx 参数中给定提供程序端签名上下文的上下文，并在 provkey 参数中初始化指向提供程序密钥对象的指针，以恢复已签名的数据。参数（如果不是 NULL），则应以类似于使用 OSSL_FUNC_signature_set_ctx_params（） 的方式在上下文中设置。键对象应已于先前使用密钥管理 （OSSL_OP_KEYMGMT） 操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt）。
OSSL_FUNC_signature_verify_recover（） 执行实际的验证恢复本身。在 ctx 参数中传递以前初始化的签名上下文。签名由 sig 参数指向，该参数的长度为 siglen 字节。除非 rout 为 NULL，否则恢复的数据应写入 rout 所指向的位置，该位置的长度不应超过 rout 大小字节。恢复数据的长度应写入 *routlen。如果 rout 为 NULL，则输出缓冲区的最大大小将写入 routlen 参数。
💐摘要签名函数
OSSL_FUNC_signature_digeset_sign_init（） 初始化用于签名的上下文，给定 ctx 参数中的提供程序端签名上下文，以及 provkey 参数中指向提供程序密钥对象的指针。参数（如果不是 NULL）应以类似于使用 OSSL_FUNC_signature_set_ctx_params（） 和 OSSL_FUNC_signature_set_ctx_md_params（） 的方式在上下文中设置。密钥对象应已于先前使用密钥管理 （OSSL_OP_KEYMGMT） 操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt）。要使用的摘要的名称将位于 mdname 参数中。在 props 参数中获取摘要时，也可能使用一些属性，尽管提供程序可能会忽略这一点。
OSSL_FUNC_signature_digest_sign_update（） 提供了要在 data 参数中签名的数据，该参数的长度应为 datalen。在 ctx 参数中传递以前初始化的签名上下文。可以多次调用此函数以累积添加要签名的数据。
OSSL_FUNC_signature_digest_sign_final（） 完成先前通过 OSSL_FUNC_signature_digest_sign_init（） 和 OSSL_FUNC_signature_digest_sign_update（） 调用启动的签名操作。一旦最终确定，将不再通过OSSL_FUNC_signature_digest_sign_update（）添加更多数据。在 ctx 参数中传递以前初始化的签名上下文。除非 sig 为 NULL，否则签名应写入 sig 参数所指向的位置，并且长度不应超过 sigsize 字节。签名的长度应写入 *siglen。如果 sig 为 NULL，则签名的最大长度应写入 *siglen。
OSSL_FUNC_signature_digest_sign（） 实现了先前通过 OSSL_FUNC_signature_digeset_sign_init（） 启动的"一次性"摘要符号操作。在 ctx 参数中传递以前初始化的签名上下文。要签名的数据以 tb 为单位，长度应为 tbslen 字节。除非 sig 为 NULL，否则签名应写入 sig 参数所指向的位置，并且长度不应超过 sigsize 字节。签名的长度应写入 *siglen。如果 sig 为 NULL，则签名的最大长度应写入 *siglen。
🍂摘要验证函数
OSSL_FUNC_signature_digeset_verify_init（） 初始化一个上下文，用于验证 ctx 参数中给定的提供程序端验证上下文，以及指向 provkey 参数中提供程序键对象的指针。参数（如果不是 NULL）应以类似于 OSSL_FUNC_signature_set_ctx_params（） 和 OSSL_FUNC_signature_set_ctx_md_params（） 的方式在上下文中设置。键对象应已于先前使用密钥管理 （OSSL_OP_KEYMGMT） 操作生成、加载或导入到提供程序中（请参阅提供程序-keymgmt）。要使用的摘要的名称将位于 mdname 参数中。在 props 参数中获取摘要时，也可能使用一些属性，尽管提供程序可能会忽略这一点。
OSSL_FUNC_signature_digest_verify_update（） 提供了要在数据参数中验证的数据，该参数的长度应为 datalen。在 ctx 参数中传递以前初始化的验证上下文。可以多次调用此函数，以累积添加要验证的数据。
OSSL_FUNC_signature_digest_verify_final（） 完成先前通过 OSSL_FUNC_signature_digest_verify_init（） 和 OSSL_FUNC_signature_digest_verify_update（） 调用启动的验证操作。一旦最终确定，将不再通过OSSL_FUNC_signature_digest_verify_update（）添加更多数据。在 ctx 参数中传递以前初始化的验证上下文。要验证的签名采用 sig 格式，长度为 siglen 字节。
OSSL_FUNC_signature_digest_verify（） 实现了先前通过 OSSL_FUNC_signature_digeset_verify_init（） 启动的"一次性"摘要验证操作。在 ctx 参数中传递以前初始化的验证上下文。要验证的数据以 tb 为单位，长度应为 tbslen 字节。要验证的签名采用 sig 格式，长度为 siglen 字节。
🍁签名参数
有关 OSSL_FUNC_signature_get_ctx_params（） 和 OSSL_FUNC_signature_set_ctx_params（） 函数使用的参数结构的更多详细信息，请参见 OSSL_PARAM。
OSSL_FUNC_signature_get_ctx_params（） 获取与给定提供程序端签名上下文 ctx 关联的签名参数，并将其存储在params中。为params传递 NULL 应返回 true。
OSSL_FUNC_signature_set_ctx_params（） 将与给定提供程序端签名上下文 ctx 关联的签名参数设置为params。任何参数设置都是对以前设置的任何参数设置的附加设置。为params传递 NULL 应返回 true。
内置签名算法当前识别的常见参数如下。
-
“digest” (OSSL_SIGNATURE_PARAM_DIGEST) < UTF8 string >
获取或设置用于输入签名函数的摘要算法的名称。为了计算"算法id"，这是必需的。 -
“properties” (OSSL_SIGNATURE_PARAM_PROPERTIES) < UTF8 string >
设置与"摘要"算法关联的属性查询的名称。如果未设置此可选值，则使用 NULL。 -
“digest-size” (OSSL_SIGNATURE_PARAM_DIGEST_SIZE) < unsigned integer >
获取或设置用于输入签名函数的摘要算法的输出大小。"摘要大小"参数的长度不应超过size_t的长度。 -
“algorithm-id” (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) < octet string >
获取 DER 编码的算法标识，该标识符对应于签名操作的签名算法和摘要算法的组合。 -
“kat” (OSSL_SIGNATURE_PARAM_KAT) < unsigned integer >
设置一个标志以修改签名操作，以便在初始计算签名无效时返回错误。在正常操作模式下 - 选择新的随机值，直到签名操作成功。默认情况下，它会重试，直到计算出签名。将该值设置为 0 将导致符号操作重试，否则该签名操作仅尝试一次，并返回是否成功。如果覆盖随机生成器以提供通过或失败的已知值，则可以执行已知答案测试。
OSSL_FUNC_signature_gettable_ctx_params（） 和 OSSL_FUNC_signature_settable_ctx_params（） 得到一个常量OSSL_PARAM数组，该数组描述了可获取参数和可设置参数，即可分别与 OSSL_FUNC_signature_get_ctx_params（） 和 OSSL_FUNC_signature_set_ctx_params（） 一起使用的参数。请参阅OSSL_PARAM 以使用 OSSL_PARAM 作为参数描述符。
🌾MD 参数
有关 OSSL_FUNC_signature_get_md_ctx_params（） 和 OSSL_FUNC_signature_set_md_ctx_params（） 函数使用的参数结构的更多详细信息，请参见 OSSL_PARAM。
OSSL_FUNC_signature_get_md_ctx_params（） 获取与给定提供者端摘要签名上下文 ctx 关联的摘要参数，并将它们存储在参数中。为参数传递 NULL 应返回 true。
OSSL_FUNC_signature_set_ms_ctx_params（） 将与给定提供程序端摘要签名上下文 ctx 关联的摘要参数设置为参数。任何参数设置都是对以前设置的任何参数设置的附加设置。为参数传递 NULL 应返回 true。
当前由内置签名算法识别的参数与内置摘要算法的参数相同。有关详细信息，请参阅提供程序-digest中的"摘要参数"。
OSSL_FUNC_signature_gettable_md_ctx_params（） 和 OSSL_FUNC_signature_settable_md_ctx_params（） 得到一个常量OSSL_PARAM数组，该数组描述可获取和可设置的摘要参数，即可以分别与 OSSL_FUNC_signature_get_md_ctx_params（） 和 OSSL_FUNC_signature_set_md_ctx_params（） 一起使用的参数。请参阅 OSSL_PARAM 以使用 OSSL_PARAM 作为参数描述符。
🥀返回值
OSSL_FUNC_signature_newctx（） 和 OSSL_FUNC_signature_dupctx（） 应返回新创建的提供程序端签名，或在失败时返回 NULL。
OSSL_FUNC_signature_gettable_ctx_params（）、OSSL_FUNC_signature_settable_ctx_params（）、OSSL_FUNC_signature_gettable_md_ctx_params（） 和 OSSL_FUNC_signature_settable_md_ctx_params（）， 返回常量OSSL_PARAM数组中的可获取或可设置参数。
所有其他函数应返回 1 表示成功，或在出错时返回 0。
