OpenSSL

provider-encoder

名称

provider-encoder - OSSL_ENCODER 库 <-> 提供者函数

概要

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

/* Encoder parameter accessor and descriptor */
const OSSL_PARAM *OSSL_FUNC_encoder_gettable_params(void *provctx);
int OSSL_FUNC_encoder_get_params(OSSL_PARAM params[]);

/* Functions to construct / destruct / manipulate the encoder context */
void *OSSL_FUNC_encoder_newctx(void *provctx);
void OSSL_FUNC_encoder_freectx(void *ctx);
int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx);

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

/* Functions to encode object data */
int OSSL_FUNC_encoder_encode(void *ctx, OSSL_CORE_BIO *out,
                             const void *obj_raw,
                             const OSSL_PARAM obj_abstract[],
                             int selection,
                             OSSL_PASSPHRASE_CALLBACK *cb,
                             void *cbarg);

/* Functions to import and free a temporary object to be encoded */
void *OSSL_FUNC_encoder_import_object(void *ctx, int selection,
                                      const OSSL_PARAM params[]);
void OSSL_FUNC_encoder_free_object(void *obj);

描述

在本手册中，我们使用“编码”这个宽泛的术语。这包括但不限于序列化。

ENCODER 操作是一种通用方法，用于将提供者本机对象 (obj_raw) 或对象抽象 (object_abstract，参见 provider-object(7)) 编码为编码形式，并将结果写入给定的 OSSL_CORE_BIO。如果调用者想要将编码流获取到内存中，则应提供一个 BIO_s_mem(3) BIO。

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

ENCODER 实现可以是链的一部分，数据从一个传递到另一个。例如，可能有一个实现将对象编码为 DER（假设该对象是提供者本机的，因此通过 obj_raw 传递），以及另一个将 DER 编码为 PEM 的实现（该实现将通过 obj_abstract 接收 DER 编码）。

使用 OSSL_PARAM(3) 数组形式的编码允许编码器用于从另一个提供者导出的数据，从而使它们能够独立于彼此存在。

使用提供者端对象的编码只能安全地用于来自同一提供者的提供者数据，例如使用 KEYMGMT 提供者的密钥。

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

typedef int
    (OSSL_FUNC_encoder_encode_fn)(void *ctx, OSSL_CORE_BIO *out,
                                  const void *obj_raw,
                                  const OSSL_PARAM obj_abstract[],
                                  int selection,
                                  OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
static ossl_inline OSSL_FUNC_encoder_encode_fn
    OSSL_FUNC_encoder_encode(const OSSL_DISPATCH *opf);

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

OSSL_FUNC_encoder_get_params          OSSL_FUNC_ENCODER_GET_PARAMS
OSSL_FUNC_encoder_gettable_params     OSSL_FUNC_ENCODER_GETTABLE_PARAMS

OSSL_FUNC_encoder_newctx              OSSL_FUNC_ENCODER_NEWCTX
OSSL_FUNC_encoder_freectx             OSSL_FUNC_ENCODER_FREECTX
OSSL_FUNC_encoder_set_ctx_params      OSSL_FUNC_ENCODER_SET_CTX_PARAMS
OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS

OSSL_FUNC_encoder_does_selection      OSSL_FUNC_ENCODER_DOES_SELECTION

OSSL_FUNC_encoder_encode              OSSL_FUNC_ENCODER_ENCODE

OSSL_FUNC_encoder_import_object       OSSL_FUNC_ENCODER_IMPORT_OBJECT
OSSL_FUNC_encoder_free_object         OSSL_FUNC_ENCODER_FREE_OBJECT

名称和属性

实现的名称应与其处理的对象类型匹配。例如，对 RSA 密钥进行编码的实现应命名为“RSA”。同样，进一步对 DER 进行编码的实现应命名为“DER”。

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

输出

此属性用于指定实现产生的输出类型。

此属性为 必填。

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

文本

具有该输出类型的实现输出人类可读的文本，使其适用于各种 openssl(1) 命令中的 -text 输出。

pem

具有该输出类型的实现输出 PEM 格式的数据。

der

具有该输出类型的实现输出 DER 格式的数据。

msblob

具有该输出类型的实现输出 MSBLOB 格式的数据。

pvk

具有该输出类型的实现输出 PVK 格式的数据。

结构

此属性用于指定用于编码对象的结构。例如，可以是 pkcs8，明确指定对象（在本例中可能是非对称密钥对）将在编码过程中包装在 PKCS#8 结构中。

此属性为 可选。

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

子集选择

有时，一个对象有多个子集的数据，这些数据需要单独或一起处理。可以通过一组位 selection 来指定要编码的子集，这些位传递给一个 int。

这组位完全取决于传递的提供者端对象的类型。例如，当对象是非对称密钥对时，这些位假定与 provider-keymgmt(7)（参见 provider-keymgmt(7) 中的“密钥对象”）中使用的位相同。

ENCODER 实现可以自由地将 selection 视为一组提示，但必须谨慎操作。最终，输出必须有意义，如果存在相应的解码器，则生成的解码对象必须与编码的原始对象匹配。

OSSL_FUNC_encoder_does_selection() 应告知特定实现是否支持 selection 给出的任何组合。

上下文函数

OSSL_FUNC_encoder_newctx() 返回一个上下文，用于与其他函数一起使用。

OSSL_FUNC_encoder_freectx() 释放给定的 ctx，如果它是由 OSSL_FUNC_encoder_newctx() 创建的。

OSSL_FUNC_encoder_set_ctx_params() 根据 params 中识别的参数设置上下文数据。应忽略未识别的参数。将 NULL 传递给 params 应返回 true。

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

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

导入函数

提供者本机对象可能与外部提供者相关联，因此可能不适合直接与给定的 ENCODER 实现一起使用。只要处理该对象的外部提供者的实现具有一个函数可以将该对象以 OSSL_PARAM(3) 数组形式导出，ENCODER 实现就应该能够导入该数组并创建一个合适的对象，将其传递给 OSSL_FUNC_encoder_encode() 的 obj_raw。

OSSL_FUNC_encoder_import_object() 应导入 params 中使用 selection 给出的子集，以创建一个提供者本机对象，该对象可以作为 obj_raw 传递给 OSSL_FUNC_encoder_encode()。

OSSL_FUNC_encoder_free_object() 应释放使用 OSSL_FUNC_encoder_import_object() 创建的对象。

编码函数

OSSL_FUNC_encoder_encode() 应接受一个提供者本机对象（在 obj_raw 中）或一个对象抽象（在 obj_abstract 中），并应将该对象以编码形式输出到 OSSL_CORE_BIO。selection 位（如果相关）应更详细地确定将输出的内容。编码函数还接受一个 OSSL_PASSPHRASE_CALLBACK(3) 函数指针以及指向应用程序数据 cbarg 的指针，当需要密码提示时应使用该指针。

编码器操作参数

内置编码器当前识别的操作参数如下所示

"cipher" (OSSL_ENCODER_PARAM_CIPHER) <UTF8 字符串>

生成加密编码时要使用的加密密码的名称。这在编码私钥以及需要保护的其他对象时使用。

如果此名称对于编码实现无效，则实现应拒绝执行编码，即 OSSL_FUNC_encoder_encode_data() 和 OSSL_FUNC_encoder_encode_object() 应返回错误。

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

尝试获取使用“cipher”参数给出的算法时要查询的属性。这必须与“cipher”参数一起给出才能被视为有效。

编码实现没有义务使用此值。但是，建议不处理属性字符串的实现，除非其值为 NULL 或空字符串，否则在收到此参数时返回错误。

"save-parameters" (OSSL_ENCODER_PARAM_SAVE_PARAMETERS) <整数>

如果设置为 0，则禁用保存密钥域参数。默认值为 1。它目前仅对 DSA 密钥有影响。

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

"info" (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 字符串>

将成为密码提示一部分的信息字符串。这可用于向用户提供有关正在提示的物体类型的的信息。

返回值

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

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

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

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

OSSL_FUNC_encoder_encode() 在成功时返回 1，在失败时返回 0。

参见

provider(7)

历史

ENCODER 接口在 OpenSSL 3.0 中引入。

版权

版权所有 2019-2021 OpenSSL 项目作者。版权所有。

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