Openssl3.0 learning XXI provider encoder

Blog's front page ： Actor's blog
Welcome to focus on the likes collection ️ Leaving a message.
️ Looking forward to communication ！
The author's level is very limited , If an error is found , Please let me know , Thank you very much ！
If you have any questions, you can communicate by private letter ！！！

Summary

 #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);

describe

In this manual , Use broad terms “ code ”. This includes but is not limited to serialization .

ENCODER Operation is a general method , It will provide a provider native object (obj_raw) Or an object abstraction (object_abstract, See Provider -object) Code into a coding form , And write the result to the given OSSL_CORE_BIO. If the caller wants to put the encoded stream into memory , It should provide a BIO_s_mem BIO.

Encoder does not need to know more about OSSL_CORE_BIO Pointer information , As long as it can be passed to the appropriate BIO Just use it up ( see also Provider -base Medium “ Kernel functions ”).

ENCODER Implementation may be part of the chain , In the chain, data is passed from one to the next . for example , There may be an implementation that encodes an object into DER( Suppose the object is provider-native, So by obj_raw Pass on ), Another implementation would DER Code to PEM( adopt obj_abstract receive DER code ).

Use OSSL_PARAM Encoding in the form of an array allows the encoder to use data exported from another provider , Thus allowing them to exist independently of each other .

Encoding using provider side objects can only be safely used for provider data from the same provider , for example KEYMGMT Provider key .

All the things mentioned here " function " As function pointers in libcrypto and OSSL_DISPATCH Pass... Between providers in the array , By the provider **provider_query_operation（）** Function return OSSL_ALGORITHM Array （ See Provider -base Medium " Provider functions "）.

All of these " function " All have a name of OSSL_FUNC_{name}_fn The corresponding function type definition of , And a helper function , Used from a file named OSSL_FUNC_{name} Of OSSL_DISPATCH Element to retrieve the function pointer . for example ," function "OSSL_FUNC_encoder_encode（） Has the following functions ：

 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 The array consists of openssl-core_dispatch.h Index the numbers provided as macros in , As shown below ：

 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

Names and properties

The name of the implementation should match the object type it handles . for example , Yes RSA The implementation of key encoding should be named "RSA". Again , Further coding DER The implementation of should be named "DER".

Property can be used to further specify implementation details ：

output

• This attribute is used to specify the output type generated by the implementation .

• This property is required .

• OpenSSL The provider recognizes the following output types ：

  1. text
     The implementation with this output type outputs human readable text , Make the implementation suitable for various openssl Output in the command .

  2. pem
     An implementation with this output type will output PEM Formatted data .

  3. der
     An implementation with this output type will output DER Formatted data .

  4. msblob
     An implementation with this output type will output MSBLOB Formatted data .

  5. pvk
     An implementation with this output type will output PVK Formatted data .

structure

• This attribute is used to specify the structure used to encode the object . An example could be , Specify the object explicitly （ In this case, it may be an asymmetric key pair ） Package as part of the code in PKCS#8 In structure .

• This property is optional .

The possible values of these two attributes are open . Providers can well specify libcrypto Unknown output type and structure .

Subset selection

Sometimes , An object has multiple data subsets , These data can be processed individually or together . By means of int A set of bit selections passed in , You can specify which subsets to encode .

This set of bits depends entirely on the type of provider-side object passed . for example , When the object is an asymmetric key pair , Assume that these bits are related to Provider -keymgmt The bits used in are the same （ see also Provider -keymgmt Medium " The key object "）.

ENCODER Implementations are free to treat choices as a set of prompts , But you must be careful . Last , The output must be meaningful , If there is a corresponding decoder , Then the decoded result object must match the encoded original object .

OSSL_FUNC_encoder_does_selection() You should tell a specific implementation whether it supports selection Any combination given .

Context function

OSSL_FUNC_encoder_newctx（） Returns the context to use with the rest of the functions .

OSSL_FUNC_encoder_freectx（） Release given ctx（, If it is by OSSL_FUNC_encoder_newctx（） Created .

OSSL_FUNC_encoder_set_ctx_params（） Set the context data according to the parameters it recognizes . Unrecognized parameters should be ignored . Pass... For parameters NULL Should return true.

OSSL_FUNC_encoder_settable_ctx_params（） Returns a constant OSSL_PARAM Array , describe OSSL_FUNC_encoder_set_ctx_params（） Parameters that can be processed .

of OSSL_FUNC_encoder_set_ctx_params（） and OSSL_FUNC_encoder_settable_ctx_params（） More details about the parameter structure used , Please see the OSSL_PARAM.

Import function

Provider native objects may be associated with external providers , Therefore, it may not be suitable for a given ENCODER Realize direct use . If the implementation of the external provider of the processing object has OSSL_PARAM The function of exporting this object in the form of array ,ENCODER The implementation should be able to import the array and create a suitable object to pass to OSSL_FUNC_encoder_encode（） Of obj_raw.

OSSL_FUNC_encoder_import_object（） The subset of parameters given by selection should be imported , To create something that can be used as obj_raw Pass to OSSL_FUNC_encoder_encode（） Provider native object for .

OSSL_FUNC_encoder_free_object（） Use should be released OSSL_FUNC_encoder_import_object（） Objects created .

Coding function

OSSL_FUNC_encoder_encode（） Provider native objects should be used （obj_raw） Or object abstraction （obj_abstract）, And the object should be output to OSSL_CORE_BIO. If relevant , The selection bit should determine in more detail what will be output . The encoding function also adopts OSSL_PASSPHRASE_CALLBACK Function pointers and pointing to application data cbarg The pointer to , This pointer should be used when a passphrase prompt is required .

Encoder operating parameters

The operating parameters recognized by the built-in encoder at present are as follows ：

• “cipher” (OSSL_ENCODER_PARAM_CIPHER) < UTF8 string >
  The name of the encryption password to be used when generating the encryption code . This is used when encoding private keys and other objects that need to be protected .
  If this name is invalid for encoding implementation , Then the implementation should refuse to execute the coding , namely OSSL_FUNC_encoder_encode_data（） and OSSL_FUNC_encoder_encode_object（） An error should be returned .

• “properties” (OSSL_ENCODER_PARAM_PROPERTIES) < UTF8 string >
  Try to get use "cipher" The attribute to be queried when the algorithm given by the parameter . This must be consistent with " password " Parameters are given together , Can be considered effective .
  The encoding implementation has no obligation to use this value . however , It is recommended that implementations that do not handle attribute strings return an error when receiving this parameter , Unless its value is NULL Or empty string .

• “save-parameters” (OSSL_ENCODER_PARAM_SAVE_PARAMETERS) < integer >
  If set to 0, Then disable the saving of key domain parameters . The default value is 1. It is currently only for DSA Key has influence .

Built in passphrase callback for currently recognized parameters ：

• “info” (OSSL_PASSPHRASE_PARAM_INFO) < UTF8 string >
  A string of messages that will be part of the passphrase prompt . This can be used to provide the user with information about the type of object it is prompted to enter .

Return value

OSSL_FUNC_encoder_newctx（） Returns a pointer to the context , Or return... In case of failure NULL.

OSSL_FUNC_encoder_set_ctx_params（） return 1, Unless the identified parameter is invalid or causes an error , Otherwise return to 0.

OSSL_FUNC_encoder_settable_ctx_params（） Returns a pointer to a constant OSSL_PARAM Pointer to element array .

If the encoder implementation supports any selection bits , be OSSL_FUNC_encoder_does_selection（） return 1, Otherwise 0.

OSSL_FUNC_encoder_encode（） Return on success 1, Return on failure 0.