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

provider-decoder

名称

provider-decoder - OSSL_DECODER 库 <-> 提供者函数

概要

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

/* Decoder parameter accessor and descriptor */
const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx);
int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]);

/* Functions to construct / destruct / manipulate the decoder context */
void *OSSL_FUNC_decoder_newctx(void *provctx);
void OSSL_FUNC_decoder_freectx(void *ctx);
const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx);
int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);

/* Functions to check selection support */
int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);

/* Functions to decode object data */
int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
                             int selection,
                             OSSL_CALLBACK *data_cb, void *data_cbarg,
                             OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);

/* Functions to export a decoded object */
int OSSL_FUNC_decoder_export_object(void *ctx,
                                      const void *objref, size_t objref_sz,
                                      OSSL_CALLBACK *export_cb,
                                      void *export_cbarg);

描述

本手册中使用“解码”一词。这包括但不限于反序列化，因为各个解码器也可以将数据解码为中间数据格式。

DECODER 操作是一种通用方法，用于从给定的 OSSL_CORE_BIO 中读取的编码形式创建提供者本机对象引用或中间解码数据。如果调用者想要从内存中解码数据，它应该提供一个 BIO_s_mem(3) BIO。解码后的数据或对象引用与最终元数据一起作为 OSSL_PARAM(3) 参数传递给 metadata_cb。

解码器无需了解 OSSL_CORE_BIO 指针的信息，除了能够将其传递给相应的 BIO 回调（参见 provider-base(7) 中的“核心函数”）。

DECODER 实现可能是链的一部分，其中数据从一个传递到下一个。例如，可能有一个实现用于将对象从 PEM 解码为 DER，另一个实现将 DER 解码为提供者本机对象。

解码链中的最后一步通常应该创建一个由对象引用引用的提供者本机对象。要将该对象导入到不同的提供者中，可以将 OSSL_FUNC_decoder_export_object() 作为解码过程的最后一步调用。

这里提到的所有“函数”都作为函数指针在 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_decoder_decode() 具有以下内容

typedef int
    (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
                                  int selection,
                                  OSSL_CALLBACK *data_cb, void *data_cbarg,
                                  OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
static ossl_inline OSSL_FUNC_decoder_decode_fn*
    OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_decoder_get_params          OSSL_FUNC_DECODER_GET_PARAMS
OSSL_FUNC_decoder_gettable_params     OSSL_FUNC_DECODER_GETTABLE_PARAMS

OSSL_FUNC_decoder_newctx              OSSL_FUNC_DECODER_NEWCTX
OSSL_FUNC_decoder_freectx             OSSL_FUNC_DECODER_FREECTX
OSSL_FUNC_decoder_set_ctx_params      OSSL_FUNC_DECODER_SET_CTX_PARAMS
OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS

OSSL_FUNC_decoder_does_selection      OSSL_FUNC_DECODER_DOES_SELECTION

OSSL_FUNC_decoder_decode              OSSL_FUNC_DECODER_DECODE

OSSL_FUNC_decoder_export_object       OSSL_FUNC_DECODER_EXPORT_OBJECT

名称和属性

实现的名称应与其解码的目标对象类型匹配。例如，解码 RSA 密钥的实现应该命名为“RSA”。同样，从 PEM 输入解码 DER 数据的实现应该命名为“DER”。

属性可用于进一步指定实现的详细信息

输入

此属性用于指定实现可以解码的输入格式。

此属性为必需属性。

OpenSSL 提供者识别以下输入类型

pem: 具有该输入类型的实现解码 PEM 格式的数据。
der: 具有该输入类型的实现解码 DER 格式的数据。
msblob: 具有该输入类型的实现解码 MSBLOB 格式的数据。
pvk: 具有该输入类型的实现解码 PVK 格式的数据。

结构

此属性用于指定解码后的数据应具有的结构。

此属性为可选属性。

内置解码器当前识别的结构

“类型特定”: 类型特定的结构。
“pkcs8”: 根据 PKCS#8 规范的结构。
“SubjectPublicKeyInfo”: 根据 RFC 5280 的主题公钥信息对公钥进行编码。

这两个属性的可能值是开放式的。提供者可能会指定 libcrypto 不了解的输入类型和结构。

子集选择

有时，一个对象有多个数据子集，这些子集对于单独处理或一起处理很有趣。可以使用一组位 selection 来指定要解码的子集，这些位传递到 int 中。

这组位完全取决于要解码的提供者端对象的类型。例如，当对象是非对称密钥对时，假设这些位与 provider-keymgmt(7) 中使用的位相同（参见 provider-keymgmt(7) 中的“密钥对象”） - 例如，如果要解码的对象应该包含私钥组件，则为 OSSL_KEYMGMT_SELECT_PRIVATE_KEY。

OSSL_FUNC_decoder_does_selection() 应该告诉您特定实现是否支持 selection 给出的任何组合。

上下文函数

OSSL_FUNC_decoder_newctx() 返回一个用于其他函数的上下文。

OSSL_FUNC_decoder_freectx() 释放由 OSSL_FUNC_decoder_newctx() 创建的给定 ctx。

OSSL_FUNC_decoder_set_ctx_params() 根据来自 params 的参数设置上下文数据，这些参数是它识别的。未识别的参数应被忽略。将 NULL 传递给 params 应返回 true。

OSSL_FUNC_decoder_settable_ctx_params() 返回一个常量 OSSL_PARAM(3) 数组，描述 OSSL_FUNC_decoder_set_ctx_params() 可以处理的参数。

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

导出函数

当解码器创建提供者本机对象时，它不适合直接用于外部提供者。导出函数允许将对象导出到该外部提供者，如果该外部提供者支持该对象的类型并提供导入函数。

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

解码函数

OSSL_FUNC_decoder_decode() 应该解码从 OSSL_CORE_BIO in 中读取的数据以生成解码后的数据或要作为引用传递给 OSSL_PARAM(3) 数组中的对象，以及从输入解码的可能的其他元数据。然后将此 OSSL_PARAM(3) 数组传递给 data_cb 回调。如果相关，selection 位应确定输入数据应包含的内容。解码函数还带有一个 OSSL_PASSPHRASE_CALLBACK(3) 函数指针以及指向应用程序数据的指针 cbarg，当需要密码提示时应使用该指针。

重要的是要了解此函数的返回值的解释方式如下

真 (1)

这意味着“继续解码过程”，即使此函数无法将输入解码为任何内容，这也是有意义的，因为可能还有其他解码器实现可以将其解码为某些东西。

当此函数无法将输入解码为任何内容时，data_cb 回调永远不会被调用。

假 (0)

这意味着“停止解码过程”，当输入可以被解码为此函数理解的某种对象时，但对该对象的进一步处理会导致错误，而其他解码器实现无法获得不同的结果时，这是有意义的。

停止解码过程的条件由实现自行决定。

解码器操作参数

内置解码器当前没有识别任何操作参数。

内置密码回调当前识别的参数

“info” (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 字符串>: 将成为密码提示的一部分的信息字符串。这可以用于向用户提供有关正在提示的哪种对象的的信息。

返回值

OSSL_FUNC_decoder_newctx() 返回指向上下文的指针，或在失败时返回 NULL。

OSSL_FUNC_decoder_set_ctx_params() 返回 1，除非识别的参数无效或导致错误，在这种情况下返回 0。

OSSL_FUNC_decoder_settable_ctx_params() 返回指向常量 OSSL_PARAM(3) 元素数组的指针。

如果解码器实现支持任何 selection 位，则 OSSL_FUNC_decoder_does_selection() 返回 1，否则返回 0。

OSSL_FUNC_decoder_decode() 返回 1 表示解码过程应该继续，返回 0 表示解码过程应该停止。

参见

provider(7)

历史记录

DECODER 接口是在 OpenSSL 3.0 中引入的。

版权

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