OpenSSL

密码学和SSL/TLS工具包

provider-signature

名称

provider-signature - 签名库 <-> 提供程序函数

概要

#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, const char *propq);
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,
                                         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 *sig, 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,
                                           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);

描述

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

签名 (OSSL_OP_SIGNATURE) 操作使提供程序能够实现签名算法并通过 API 函数 EVP_PKEY_sign(3)、EVP_PKEY_verify(3) 和 EVP_PKEY_verify_recover(3)（以及其他相关函数）提供给应用程序。

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

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

typedef void *(OSSL_FUNC_signature_newctx_fn)(void *provctx, const char *propq);
static ossl_inline OSSL_FUNC_signature_newctx_fn
    OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH(3) 数组由数字索引，这些数字作为宏提供在 openssl-core_dispatch.h(7) 中，如下所示

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_recover
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) 操作生成、加载或导入密钥的机制。有关更多详细信息，请参阅 provider-keymgmt(7)。

上下文管理函数

OSSL_FUNC_signature_newctx() 应该创建并返回指向提供程序端结构的指针，用于在签名操作期间保存上下文信息。此上下文的指针将在许多其他签名操作函数调用中传递回。参数 provctx 是在提供程序初始化期间生成的提供程序上下文（请参阅 provider(7)）。propq 参数是一个属性查询字符串，提供程序在执行任何“获取”（如果执行任何获取）期间可以（可选地）使用。

OSSL_FUNC_signature_freectx() 将 ctx 参数中提供程序端签名上下文的指针作为参数传递。此函数应释放与该上下文关联的任何资源。

OSSL_FUNC_signature_dupctx() 应该复制 ctx 参数中的提供程序端签名上下文并返回副本。

签名函数

OSSL_FUNC_signature_sign_init() 初始化一个用于签名的上下文，给定 ctx 参数中的提供程序端签名上下文，以及 provkey 参数中的提供程序密钥对象的指针。如果 params 不为 NULL，则应以类似于使用 OSSL_FUNC_signature_set_ctx_params() 的方式将其设置为上下文。密钥对象应已使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)）先前在提供程序中生成、加载或导入。

OSSL_FUNC_signature_sign() 执行实际签名本身。ctx 参数中传递了先前初始化的签名上下文。要签名的数据的指针为 tbs 参数，其长度为 tbslen 字节。除非 sig 为 NULL，否则签名应写入 sig 参数指向的位置，并且其长度不应超过 sigsize 字节。签名的长度应写入 *siglen。如果 sig 为 NULL，则签名的最大长度应写入 *siglen。

验证函数

OSSL_FUNC_signature_verify_init() 初始化一个用于验证签名的上下文，给定 ctx 参数中的提供程序端签名上下文，以及 provkey 参数中的提供程序密钥对象的指针。如果 params 不为 NULL，则应以类似于使用 OSSL_FUNC_signature_set_ctx_params() 的方式将其设置为上下文。密钥对象应已使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)）先前在提供程序中生成、加载或导入。

OSSL_FUNC_signature_verify() 执行实际验证本身。ctx 参数中传递了先前初始化的签名上下文。签名覆盖的数据的指针为 tbs 参数，其长度为 tbslen 字节。签名的指针为 sig 参数，其长度为 siglen 字节。

验证恢复函数

OSSL_FUNC_signature_verify_recover_init() 初始化一个用于恢复已签名数据的上下文，给定 ctx 参数中的提供程序端签名上下文，以及 provkey 参数中的提供程序密钥对象的指针。如果 params 不为 NULL，则应以类似于使用 OSSL_FUNC_signature_set_ctx_params() 的方式将其设置为上下文。密钥对象应已使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)）先前在提供程序中生成、加载或导入。

OSSL_FUNC_signature_verify_recover() 执行实际验证恢复本身。ctx 参数中传递了先前初始化的签名上下文。签名的指针为 sig 参数，其长度为 siglen 字节。除非 rout 为 NULL，否则恢复的数据应写入 rout 参数指向的位置，并且其长度不应超过 routsize 字节。恢复数据的长度应写入 *routlen。如果 rout 为 NULL，则输出缓冲区的大小写入 routlen 参数。

摘要签名函数

OSSL_FUNC_signature_digeset_sign_init() 初始化一个用于签名的上下文，给定 ctx 参数中的提供程序端签名上下文，以及 provkey 参数中的提供程序密钥对象的指针。如果 params 不为 NULL，则应以类似于使用 OSSL_FUNC_signature_set_ctx_params() 和 OSSL_FUNC_signature_set_ctx_md_params() 的方式将其设置为上下文。密钥对象应已使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)）先前在提供程序中生成、加载或导入。要使用的摘要的名称将在 mdname 参数中。

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 参数中传递了先前初始化的签名上下文。要签名的数据位于 tbs 中，其长度应为 tbslen 字节。除非 sig 为 NULL，否则签名应写入 sig 参数指向的位置，并且其长度不应超过 sigsize 字节。签名的长度应写入 *siglen。如果 sig 为 NULL，则签名的最大长度应写入 *siglen。

摘要验证函数

OSSL_FUNC_signature_digeset_verify_init() 初始化一个用于验证的上下文，给定 ctx 参数中的提供程序端验证上下文，以及 provkey 参数中的提供程序密钥对象的指针。如果 params 不为 NULL，则应以类似于 OSSL_FUNC_signature_set_ctx_params() 和 OSSL_FUNC_signature_set_ctx_md_params() 的方式将其设置为上下文。密钥对象应已使用密钥管理 (OSSL_OP_KEYMGMT) 操作（请参阅 provider-keymgmt(7)）先前在提供程序中生成、加载或导入。要使用的摘要的名称将在 mdname 参数中。

OSSL_FUNC_signature_digest_verify_update() 提供要验证的 data 参数中的数据，其长度应为 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 参数中传递了先前初始化的验证上下文。要验证的数据位于 tbs 中，其长度应为 tbslen 字节。要验证的签名位于 sig 中，其长度为 siglen 字节。

签名参数

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

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 字符串>

获取或设置用于签名函数输入的摘要算法的名称。它是为了计算“算法 ID”而必需的。

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

设置与“摘要”算法关联的属性查询的名称。如果未设置此可选值，则使用 NULL。

"digest-size" (OSSL_SIGNATURE_PARAM_DIGEST_SIZE) <无符号整数>

获取或设置用于签名函数输入的摘要算法的输出大小。“digest-size”参数的长度不应超过 size_t 的长度。

"algorithm-id" (OSSL_SIGNATURE_PARAM_ALGORITHM_ID) <八位字节串>

获取与签名操作的签名算法和摘要算法组合相对应的 DER 编码的 AlgorithmIdentifier。

"nonce-type" (OSSL_SIGNATURE_PARAM_NONCE_TYPE) <无符号整数>

将此设置为 1 以使用确定性数字签名生成与 ECDSA 或 DSA，如 RFC 6979 中所定义（参见第 3.2 节“k 的生成”）。在这种情况下，必须显式设置“digest”参数（否则，确定性随机数生成将失败）。在使用确定性数字签名生成之前，请阅读 RFC 6979 第 4 节“安全注意事项”。“nonce-type”的默认值为 0，导致为随机数k使用随机值，如 FIPS 186-4 第 6.3 节“秘密数生成”中所定义。

"kat" (OSSL_SIGNATURE_PARAM_KAT) <无符号整数>

设置一个标志来修改签名操作，如果初始计算的签名无效则返回错误。在正常操作模式下 - 选择新的随机值，直到签名操作成功。默认情况下，它会重试直到计算出签名。将值设置为 0 会导致签名操作重试，否则签名操作只尝试一次并返回它是否成功。如果覆盖随机生成器以提供通过或失败的已知值，则可以执行已知答案测试。

OSSL_FUNC_signature_gettable_ctx_params() 和 OSSL_FUNC_signature_settable_ctx_params() 获取一个描述可获取和可设置参数的常量 OSSL_PARAM(3) 数组，即分别可用于 OSSL_FUNC_signature_get_ctx_params() 和 OSSL_FUNC_signature_set_ctx_params() 的参数。

MD 参数

有关 OSSL_FUNC_signature_get_md_ctx_params() 和 OSSL_FUNC_signature_set_md_ctx_params() 函数使用的参数结构的更多详细信息，请参见 OSSL_PARAM(3)。

OSSL_FUNC_signature_get_md_ctx_params() 获取与给定提供程序端摘要签名上下文ctx关联的摘要参数，并将它们存储在params中。如果params为 NULL，则应返回 true。

OSSL_FUNC_signature_set_ms_ctx_params() 将与给定提供程序端摘要签名上下文ctx关联的摘要参数设置为params。任何参数设置都是对之前设置的任何参数的补充。如果params为 NULL，则应返回 true。

内置签名算法当前识别的参数与内置摘要算法的参数相同。有关更多信息，请参见 provider-digest(7) 中的“摘要参数”。

OSSL_FUNC_signature_gettable_md_ctx_params() 和 OSSL_FUNC_signature_settable_md_ctx_params() 获取一个描述可获取和可设置摘要参数的常量 OSSL_PARAM(3) 数组，即分别可用于 OSSL_FUNC_signature_get_md_ctx_params() 和 OSSL_FUNC_signature_set_md_ctx_params() 的参数。

返回值

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(3) 数组中返回可获取或可设置的参数。

所有其他函数在成功时应返回 1，在错误时返回 0。

另请参见

provider(7)

历史

提供程序 SIGNATURE 接口是在 OpenSSL 3.0 中引入的。

版权所有 2019-2024 OpenSSL 项目作者。保留所有权利。

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