📒 Blog home page: Actor's blog
🎉 Welcome to pay attention 🔎 give the thumbs-up 👍 Collection ⭐ Leave a message 📝
❤️ Look forward to communicating together!
🙏 The author's level is very limited. If you find an error, please let me know. Thank you!
🌺 If you have any questions, you can communicate by private letter!!!

🌺 outline

 #include <openssl/core_dispatch.h>
 #include <openssl/core_names.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.
  */
 
 /* Context management */
 void *OSSL_FUNC_kem_newctx(void *provctx);
 void OSSL_FUNC_kem_freectx(void *ctx);
 void *OSSL_FUNC_kem_dupctx(void *ctx);
 
 /* Encapsulation */
 int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey, const char *name,
                                    const OSSL_PARAM params[]);
 int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen,
                               unsigned char *secret, size_t *secretlen);
 
 /* Decapsulation */
 int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey, const char *name);
 int OSSL_FUNC_kem_decapsulate(void *ctx, unsigned char *out, size_t *outlen,
                               const unsigned char *in, size_t inlen);
 
 /* KEM parameters */
 int OSSL_FUNC_kem_get_ctx_params(void *ctx, OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_kem_gettable_ctx_params(void *ctx, void *provctx);
 int OSSL_FUNC_kem_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_kem_settable_ctx_params(void *ctx, void *provctx);

🌻 describe

This document is mainly for provider authors. For more information, see provider.

The asymmetric KEM (OSSL_OP_KEM) operation enables the provider to implement the asymmetric KEM algorithm through the API function EVP_PKEY_encapsulate,EVP_PKEY_decapsulate and other related functions provide them to the application.

All the "functions" mentioned here are used as function pointers in libcrypto and ossl_ It is passed between providers in the dispatch array through the * * provider provided by the provider_ query_ Ossl returned by operation() * * function_ Algorithm array (see "provider functions" in provider base).

All of these "functions" have a name called OSSL_FUNC_{name}_fn, and a helper function, which is used to_ FUNC_ Ossl for {name}_ Retrieves a function pointer from the dispatch element. For example, "function" OSSL_FUNC_kem_newctx() has the following functions:

 typedef void *(OSSL_FUNC_kem_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_kem_newctx_fn
     OSSL_FUNC_kem_newctx(const OSSL_DISPATCH *opf);

OSSL_ The dispatch array is created by OpenSSL core_ dispatch. The numbers provided as macros in H are indexed as follows:

 OSSL_FUNC_kem_newctx               OSSL_FUNC_KEM_NEWCTX
 OSSL_FUNC_kem_freectx              OSSL_FUNC_KEM_FREECTX
 OSSL_FUNC_kem_dupctx               OSSL_FUNC_KEM_DUPCTX

 OSSL_FUNC_kem_encapsulate_init     OSSL_FUNC_KEM_ENCAPSULATE_INIT
 OSSL_FUNC_kem_encapsulate          OSSL_FUNC_KEM_ENCAPSULATE

 OSSL_FUNC_kem_decapsulate_init     OSSL_FUNC_KEM_DECAPSULATE_INIT
 OSSL_FUNC_kem_decapsulate          OSSL_FUNC_KEM_DECAPSULATE

 OSSL_FUNC_kem_get_ctx_params       OSSL_FUNC_KEM_GET_CTX_PARAMS
 OSSL_FUNC_kem_gettable_ctx_params  OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS
 OSSL_FUNC_kem_set_ctx_params       OSSL_FUNC_KEM_SET_CTX_PARAMS
 OSSL_FUNC_kem_settable_ctx_params  OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS

Asymmetric KEM algorithm may not be able to achieve all these functions. In order to be a consistent set of functions, the provider must implement ossl_ FUNC_ kem_ Osctx and osctx_ FUNC_ kem_ freectx. It must also implement ossl at the same time_ FUNC_ kem_ encapsulate_ Init and OSSL_FUNC_kem_encapsulate, or implement ossl at the same time_ FUNC_ kem_ decapsulate_ Init and OSSL_FUNC_kem_decapsulate. OSSL_FUNC_kem_get_ctx_params is optional, but if it exists, there must be OSSL_FUNC_kem_gettable_ctx_params. Similarly, OSSL_FUNC_kem_set_ctx_params is optional, but if it exists, then OSSL_FUNC_kem_settable_ctx_params must also exist.

Asymmetric kem algorithm must also implement some mechanisms to generate, load or import keys through key management (OSSL_OP_KEYMGMT). For more information, see provider - keymgmt.

🌹 Context management function

OSSL_FUNC_kem_newctx () should create and return a pointer to the provider side structure to hold context information during asymmetric KEM operations. A pointer to this context will be passed back in many other asymmetric KEM operator function calls. The parameter provctx is the provider context generated during provider initialization (see provider).

OSSL_FUNC_kem_freectx () passes a pointer to the asymmetric KEM context on the provider side in the ctx parameter. This function should free any resources associated with the context.

OSSL_FUNC_kem_dupctx() should replicate the provider side asymmetric KEM context in the ctx parameter and return a duplicate copy.

🌷 Asymmetric key encapsulation function

OSSL_FUNC_kem_encapsulate_init() initializes the context of asymmetric encapsulation, and gives the asymmetric KEM context of the provider side in the CTX parameter, the pointer to the provider key object in the provkey parameter, and the name of the algorithm. Parameter (if not NULL), it should be used in a similar way to using OSSL_FUNC_kem_set_ctx_params() is set in the context. Key objects should have been generated, loaded, or imported into the provider previously using key management (OSSL_OP_KEYMGMT) operations (see provider keymgmt).

OSSL_FUNC_kem_encapsulate () performs the actual encapsulation itself. Pass the previously initialized asymmetric KEM context in the ctx parameter. Unless out is NULL, the data to be encapsulated will be generated internally and returned to the buffer pointed to by the secret parameter, and the encapsulated data should also be written to the location pointed to by the out parameter. The length of the encapsulated data should be written into * outlen, and the length of the generated key should be written into * secret.

If out is NULL, the maximum length of the encapsulated data should be written to * outlen, and the maximum length of the generated key should be written to * secret.

🌼 Unsealing function

OSSL_FUNC_kem_decapsulate_init() initializes the context of asymmetric unpacking, and gives the asymmetric KEM context of the provider side in the ctx parameter, the pointer to the provider key object in the provkey parameter, and the name of the algorithm. The key object should have been generated, loaded or imported into the provider previously using the key management (OSSL_OP_KEYMGMT) operation (see provider keymgmt).

OSSL_FUNC_kem_decapsulate () performs the actual unpacking itself. Pass the previously initialized asymmetric KEM context in the ctx parameter. The data to be unsealed is pointed to by the in parameter, which is inlen bytes in length. Unless out is NULL, the unsealed data should be written to the location pointed to by the out parameter. The length of unsealed data should be written to * outlen. If out is NULL, the maximum length of unsealed data should be written to * outlen.

🌸 Asymmetric key encapsulation parameters

About OSSL_FUNC_kem_get_ctx_params() and ossl_ FUNC_ kem_ set_ ctx_ For more details on the parameter structure used by the params() function, see OSSL_PARAM.

OSSL_FUNC_kem_get_ctx_params () gets the asymmetric KEM parameters associated with the given provider-side asymmetric KEM context CTX and stores them in the parameters. Passing NULL for parameter should return true.

OSSL_FUNC_kem_set_ctx_params() sets the asymmetric KEM parameter associated with the given provider-side asymmetric KEM context CTX as a parameter. Any parameter setting is an additional setting to any previously set parameter setting. Passing NULL for parameter should return true.

The built-in asymmetric kem algorithm can not recognize any parameters at present.

OSSL_FUNC_kem_gettable_ctx_params() and OSSL_FUNC_kem_settable_ctx_params() gets a constant OSSL_PARAM array, which describes the obtainable parameters and settable parameters, that is, it can be connected with ossl respectively_ FUNC_ kem_ get_ ctx_ Params() and ossl_ FUNC_ kem_ set_ ctx_ Parameters used with params(). See OSSL_PARAM to use OSSL_PARAM as parameter descriptor.

💐 Return value

OSSL_FUNC_kem_newctx() and OSSL_FUNC_kem_dupctx() should return the newly created provider side asymmetric KEM context or NULL on failure.

All other functions should return 1 for success or 0 for errors.