《OpenSSL3.0学习之二十一提供程序-encoder》-CFANZ编程社区

文章目录

🌺概要

 #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，参见提供程序-object)编码成一种编码形式，并将结果写入给定的OSSL_CORE_BIO。如果调用者希望将编码后的流放到内存中，它应该提供一个BIO_s_mem BIO。

编码器不需要了解更多关于OSSL_CORE_BIO指针的信息，只要能够将它传递给适当的BIO上调用即可(请参阅提供程序-base中的“内核函数”)。

ENCODER实现可能是链的一部分，在链中数据从一个传递到下一个。例如，可能有一个实现将一个对象编码到DER(假设该对象是provider-native，因此通过obj_raw传递)，另一个实现将DER编码到PEM(通过obj_abstract接收DER编码)。

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

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

这里提到的所有"函数"都作为函数指针在libcrypto和OSSL_DISPATCH数组中的提供程序之间传递，通过由提供程序的**provider_query_operation（）**函数返回的OSSL_ALGORITHM数组（参见提供程序-base中的"提供程序函数"）。

所有这些"函数"都有一个名为 OSSL_FUNC_{name}_fn 的相应函数类型定义，以及一个帮助程序函数，用于从名为 OSSL_FUNC_{name} 的 OSSL_DISPATCH元素中检索函数指针。例如，"函数"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数组由 openssl-core_dispatch.h 中作为宏提供的数字编制索引，如下所示：

 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"。

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

output

此属性用于指定实现生成的输出类型。
此属性是必需的。
OpenSSL 提供程序可识别以下输出类型：
1. text
  具有该输出类型的实现输出人类可读的文本，使该实现适合于在各种 openssl命令中输出。
2. pem
  具有该输出类型的实现将输出 PEM 格式的数据。
3. der
  具有该输出类型的实现将输出 DER 格式的数据。
4. msblob
  具有该输出类型的实现将输出 MSBLOB 格式的数据。
5. pvk
  具有该输出类型的实现将输出 PVK 格式的数据。

structure

此属性用于指定用于编码对象的结构。一个例子可以是，明确指定对象（在本例中可能是非对称密钥对）将作为编码的一部分包装在 PKCS#8 结构中。
此属性是可选的。

这两个属性的可能值都是开放式的。提供者可以很好地指定libcrypto不知道的输出类型和结构。

🌷子集选择

有时，一个对象有多个数据子集，可以单独或一起处理这些数据。通过在int中传递的一组位选择，可以指定要对哪些子集进行编码。

这组位完全取决于传递的提供者端对象的类型。例如，当对象是非对称密钥对时，假定这些位与提供程序-keymgmt 中使用的位相同（请参阅提供程序-keymgmt中的"密钥对象"）。

ENCODER实现可以自由地将选择视为一组提示，但必须小心这样做。最后，输出必须有意义，如果有相应的解码器，则解码后的结果对象必须与编码后的原始对象匹配。

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（）根据它识别的参数设置上下文数据。无法识别的参数应被忽略。为参数传递 NULL 应返回 true。

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

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

🌸导入函数

提供程序本机对象可能与外部提供程序相关联，因此可能不适合与给定的 ENCODER 实现直接使用。如果处理对象的外部提供程序的实现具有以 OSSL_PARAM数组形式导出该对象的功能，ENCODER 实现应该能够导入该数组并创建一个合适的对象以传递给OSSL_FUNC_encoder_encode（）的obj_raw。

OSSL_FUNC_encoder_import_object（）应导入通过选择给出的参数子集，以创建可作为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。如果相关，选择位应更详细地确定将输出的内容。编码函数还采用OSSL_PASSPHRASE_CALLBACK函数指针以及指向应用程序数据 cbarg 的指针，在需要密码短语提示时应使用该指针。

🍂编码器操作参数

内置编码器目前可识别的操作参数如下：

“cipher” (OSSL_ENCODER_PARAM_CIPHER) < UTF8 string >
生成加密编码时要使用的加密密码的名称。这在编码私钥以及需要保护的其他对象时使用。
如果此名称对于编码实现无效，则实现应拒绝执行编码，即OSSL_FUNC_encoder_encode_data（）和 OSSL_FUNC_encoder_encode_object（）应返回错误。
“properties” (OSSL_ENCODER_PARAM_PROPERTIES) < UTF8 string >
尝试获取使用"cipher"参数给定的算法时要查询的属性。这必须与"密码"参数一起给出，才能被视为有效。
编码实现没有义务使用此值。但是，建议不处理属性字符串的实现在接收此参数时返回错误，除非其值为 NULL 或空字符串。
“save-parameters” (OSSL_ENCODER_PARAM_SAVE_PARAMETERS) < integer >
如果设置为 0，则禁用关键域参数的保存。默认值为 1。它目前仅对 DSA 键有影响。