/docs/man3.3/man7/provider-storemgmt.html

provider-storemgmt

名称

provider-storemgmt - OSSL_STORE 库 <-> 提供程序函数

摘要

#include <openssl/core_dispatch.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.
 */

void *OSSL_FUNC_store_open(void *provctx, const char *uri);
void *OSSL_FUNC_store_attach(void *provctx, OSSL_CORE_BIO *bio);
const OSSL_PARAM *store_settable_ctx_params(void *provctx);
int OSSL_FUNC_store_set_ctx_params(void *loaderctx, const OSSL_PARAM[]);
int OSSL_FUNC_store_load(void *loaderctx,
                         OSSL_CALLBACK *object_cb, void *object_cbarg,
                         OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
int OSSL_FUNC_store_eof(void *loaderctx);
int OSSL_FUNC_store_close(void *loaderctx);

int OSSL_FUNC_store_export_object
    (void *loaderctx, const void *objref, size_t objref_sz,
     OSSL_CALLBACK *export_cb, void *export_cbarg);
void *OSSL_FUNC_store_open_ex(void *provctx, const char *uri,
                              const OSSL_PARAM params[],
                              OSSL_PASSPHRASE_CALLBACK *pw_cb,
                              void *pw_cbarg);

int OSSL_FUNC_store_delete(void *provctx, const char *uri,
                   const OSSL_PARAM params[],
                   OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);

描述

STORE 操作是 ossl_store(7) API 的提供程序端。

STORE 操作的主要职责是从 URI 指示的容器中加载各种对象。这些对象以提供程序原生对象抽象形式（参见 provider-object(7)）提供给 OpenSSL 库。然后，OpenSSL 库负责将该抽象传递给合适的提供程序函数。

OpenSSL 库可以将抽象传递到的函数示例包括 OSSL_FUNC_keymgmt_load() (provider-keymgmt(7))、OSSL_FUNC_store_export_object()（以参数化形式导出对象）。

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

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

typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx,
                                          OSSL_CORE_BIO * bio);
static ossl_inline OSSL_FUNC_store_attach_fn
    OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_store_open                 OSSL_FUNC_STORE_OPEN
OSSL_FUNC_store_attach               OSSL_FUNC_STORE_ATTACH
OSSL_FUNC_store_settable_ctx_params  OSSL_FUNC_STORE_SETTABLE_CTX_PARAMS
OSSL_FUNC_store_set_ctx_params       OSSL_FUNC_STORE_SET_CTX_PARAMS
OSSL_FUNC_store_load                 OSSL_FUNC_STORE_LOAD
OSSL_FUNC_store_eof                  OSSL_FUNC_STORE_EOF
OSSL_FUNC_store_close                OSSL_FUNC_STORE_CLOSE
OSSL_FUNC_store_export_object        OSSL_FUNC_STORE_EXPORT_OBJECT
OSSL_FUNC_store_delete               OSSL_FUNC_STORE_DELETE
OSSL_FUNC_store_open_ex              OSSL_FUNC_STORE_OPEN_EX

函数

OSSL_FUNC_store_open() 应该使用基于输入 uri 的数据创建一个提供程序端上下文。实现完全负责 URI 的解释。

OSSL_FUNC_store_attach() 应该使用附加的核心 BIO bio 创建一个提供程序端上下文。这是一种查找存储的替代方法，支持 OSSL_STORE_attach(3)。

OSSL_FUNC_store_settable_ctx_params() 应该返回一个描述符 OSSL_PARAM(3) 的常量数组，用于 OSSL_FUNC_store_set_ctx_params() 可以处理的参数。

OSSL_FUNC_store_set_ctx_params() 应该设置其他参数，例如期望获取的数据类型、搜索条件等。更多信息请参见下文 “加载参数”。未识别的参数是错误还是简单忽略由实现决定。将 params 传递为 NULL 应该返回 true。

OSSL_FUNC_store_load() 从 OSSL_FUNC_store_open() 打开的 URI 加载下一个对象，为其创建一个对象抽象（参见 provider-object(7)），并使用它以及 object_cbarg 调用 object_cb。然后，object_cb 将解释对象抽象并尽其所能将其包装或解码成 OpenSSL 结构。如果需要提示密码来解锁对象，则应调用 pw_cb。

OSSL_FUNC_store_eof() 指示是否已到达 URI 对象集的末尾。发生这种情况时，就没有必要尝试进行任何进一步的加载。

OSSL_FUNC_store_close() 释放提供程序端上下文 ctx。

当存储管理器创建提供程序原生对象时，它不适合直接与外部提供程序一起使用。如果外部提供程序支持对象的类型并提供导入函数，则导出函数允许将对象导出到该外部提供程序。

OSSL_FUNC_store_export_object() 应该将 objref 引用的大小为 objref_sz 的对象导出为 OSSL_PARAM(3) 数组，并将其传递给 export_cb 以及给定的 export_cbarg。

OSSL_FUNC_store_delete() 删除由 uri 标识的对象。实现完全负责 URI 的解释。如果需要提示密码来删除对象，则应调用 pw_cb。

OSSL_FUNC_store_open_ex() 是 OSSL_FUNC_store_open() 的扩展变体。如果提供程序未实现此函数，则代码会在内部回退到使用原始 OSSL_FUNC_store_open()。此变体还接受一个 OSSL_PARAM(3) 对象和一个 pw_cb 回调，该回调可用于在需要在执行任何加载操作之前解锁整个存储的情况下请求密码。

加载参数

“expect”（OSSL_STORE_PARAM_EXPECT）<整数>

是 OpenSSL 库期望获取的数据类型的提示。这仅对优化有用，因为库也会检查对象类型是否与预期匹配。

可以通过此参数提供的数字在 <openssl/store.h> 中找到，其中宏的名称以 OSSL_STORE_INFO_ 开头。这些在 OSSL_STORE_INFO(3) 中的“支持的对象” 中有进一步描述。

“subject”（OSSL_STORE_PARAM_SUBJECT）<八位字节串>

指示调用方希望搜索与给定主题关联的对象。这可用于根据主题选择特定证书。

预期八位字节串的内容为 DER 格式。

“issuer”（OSSL_STORE_PARAM_ISSUER）<八位字节串>

指示调用方希望搜索与给定发行者关联的对象。这可用于根据发行者选择特定证书。

预期八位字节串的内容为 DER 格式。

“serial”（OSSL_STORE_PARAM_SERIAL）<整数>

指示调用方希望搜索与给定序列号关联的对象。

“digest”（OSSL_STORE_PARAM_DIGEST）<UTF8 字符串>

“fingerprint”（OSSL_STORE_PARAM_FINGERPRINT）<八位字节串>

指示调用方希望搜索与给定指纹关联的对象，该指纹使用给定的摘要计算得出。

“alias”（OSSL_STORE_PARAM_ALIAS）<UTF8 字符串>

指示调用方希望搜索与给定别名（有些人称其为“友好名称”）关联的对象。

“properties”（OSSL_STORE_PARAM_PROPERTIES）<utf8 字符串>

在查询算法（例如 OSSL_DECODER 解码器实现）时使用的属性字符串。

“input-type”（OSSL_STORE_PARAM_INPUT_TYPE）<utf8 字符串>

输入格式的类型，作为解码存储中的对象时使用的提示。

可以组合这些搜索条件中的几个。例如，要按发行者+序列号搜索证书，将同时给出“issuer”和“serial”参数。

参见

provider(7)

历史

STORE 接口在 OpenSSL 3.0 中引入。

OSSL_FUNC_store_delete() 回调在 OpenSSL 3.2 中添加

版权

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