《OpenSSL3.0学习之二十二提供程序-decoder》-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.
  */
 
 /* 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 */
 void *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 BIO。解码后的数据或对象引用与最终元数据一起作为OSSL_PARAM参数传递给metadata_cb。

解码器不需要更多地了解OSSL_CORE_BIO指针，只需能够将其传递给相应的 BIO 调用（参见提供程序-base中的"内核函数"）。

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

解码链中的最后一个解码步骤通常应该创建由对象引用引用的提供程序本机对象。要将该对象导入到其他提供程序中，可以调用 OSSL_FUNC_decoder_export_object（）作为解码过程的最后一步。

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

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

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

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

input

此属性用于指定实现可以解码的输入格式。
此属性是必需的。
OpenSSL 提供程序可识别以下输入类型：
1. pem
  具有该输入类型的实现将解码 PEM 格式的数据。
2. der
  具有该输入类型的实现对 DER 格式的数据进行解码。
3. msblob
  具有该输入类型的实现对 MSBLOB 格式的数据进行解码。
4. pvk
  具有该输入类型的实现将解码 PVK 格式的数据。

structure

此属性用于指定解码数据预期具有的结构。
此属性是可选的。
内置解码器目前认可的结构：
1. “type-specific”
  特定于类型的结构。
2. “pkcs8”
  结构符合 PKCS#8 规范。
3. “SubjectPublicKeyInfo”
  根据 RFC 5280 的主题公钥信息对公钥进行编码。

🌷子集选择

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

这组位完全取决于要解码的提供者端对象的类型。例如,那些被认为是相同的使用提供程序-keymgmt(见“密钥对象”提供程序-keymgmt)当对象是一个非对称密钥对,例如,OSSL_KEYMGMT_SELECT_PRIVATE_KEY如果对象解码应该包含私钥组件。

OSSL_FUNC_decoder_does_selection（）应该判断一个特定的实现是否支持通过选择给出的任何组合。

🌼上下文函数

OSSL_FUNC_decoder_newctx（）返回要与其余函数一起使用的上下文。

OSSL_FUNC_decoder_freectx（）释放由 OSSL_FUNC_decoder_newctx（）创建的给定 ctx。

OSSL_FUNC_decoder_set_ctx_params（）根据它识别的参数设置上下文数据。无法识别的参数应被忽略。为参数传递 NULL 应返回 true。

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

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

🌸导出功能

当提供程序本机对象由解码器创建时，它不适合直接与外部提供程序一起使用。如果外部提供程序支持对象的类型并提供导入函数，则导出函数允许将对象导出到该外部提供程序中。

OSSL_FUNC_decoder_export_object（）应将 objref 引用的大小objref_sz对象导出为OSSL_PARAM数组，并将其传递到export_cb以及给定的export_cbarg。

💐解码函数

OSSL_FUNC_decoder_decode（）应解码从OSSL_CORE_BIO读取的数据，以生成解码后的数据或要作为OSSL_PARAM数组中的引用传递的对象，以及从输入解码的其他元数据。然后，此OSSL_PARAM数组将传递给data_cb回调。选择位（如果相关）应确定输入数据应包含的内容。解码函数还采用OSSL_PASSPHRASE_CALLBACK函数指针以及指向应用程序数据 cbarg 的指针，在需要密码短语提示时应使用该指针。

请务必了解此函数的返回值解释如下：

True (1)