Openssl3.0 learning 20 provider KDF

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>
 #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_kdf_newctx(void *provctx);
 void OSSL_FUNC_kdf_freectx(void *kctx);
 void *OSSL_FUNC_kdf_dupctx(void *src);
 
 /* Encryption/decryption */
 int OSSL_FUNC_kdf_reset(void *kctx);
 int OSSL_FUNC_kdf_derive(void *kctx, unsigned char *key, size_t keylen,
                          const OSSL_PARAM params[]);
 
 /* KDF parameter descriptors */
 const OSSL_PARAM *OSSL_FUNC_kdf_gettable_params(void *provctx);
 const OSSL_PARAM *OSSL_FUNC_kdf_gettable_ctx_params(void *kcxt, void *provctx);
 const OSSL_PARAM *OSSL_FUNC_kdf_settable_ctx_params(void *kcxt, void *provctx);
 
 /* KDF parameters */
 int OSSL_FUNC_kdf_get_params(OSSL_PARAM params[]);
 int OSSL_FUNC_kdf_get_ctx_params(void *kctx, OSSL_PARAM params[]);
 int OSSL_FUNC_kdf_set_ctx_params(void *kctx, const OSSL_PARAM params[]);

describe

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

KDF Operations enable providers to implement KDF Algorithm , And pass API function EVP_KDF_CTX_reset and EVP_KDF_derive Provide it to the application .

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_kdf_newctx（） Has the following functions ：

 typedef void *(OSSL_OSSL_FUNC_kdf_newctx_fn)(void *provctx);
 static ossl_inline OSSL_OSSL_FUNC_kdf_newctx_fn
     OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf);

OSSL_DISPATCH Array entries are composed of openssl-core_dispatch.h The digital ID provided as a macro in , As shown below ：

 OSSL_FUNC_kdf_newctx               OSSL_FUNC_KDF_NEWCTX
 OSSL_FUNC_kdf_freectx              OSSL_FUNC_KDF_FREECTX
 OSSL_FUNC_kdf_dupctx               OSSL_FUNC_KDF_DUPCTX

 OSSL_FUNC_kdf_reset                OSSL_FUNC_KDF_RESET
 OSSL_FUNC_kdf_derive               OSSL_FUNC_KDF_DERIVE

 OSSL_FUNC_kdf_get_params           OSSL_FUNC_KDF_GET_PARAMS
 OSSL_FUNC_kdf_get_ctx_params       OSSL_FUNC_KDF_GET_CTX_PARAMS
 OSSL_FUNC_kdf_set_ctx_params       OSSL_FUNC_KDF_SET_CTX_PARAMS

 OSSL_FUNC_kdf_gettable_params      OSSL_FUNC_KDF_GETTABLE_PARAMS
 OSSL_FUNC_kdf_gettable_ctx_params  OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS
 OSSL_FUNC_kdf_settable_ctx_params  OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS

KDF Algorithm implementation may not be able to achieve all these functions . In order to be a consistent set of functions , At least the following functions must be implemented ：OSSL_FUNC_kdf_newctx（）,OSSL_FUNC_kdf_freectx（）,OSSL_FUNC_kdf_set_ctx_params（）,OSSL_FUNC_kdf_derive（）. All other functions are optional .

Context management function

OSSL_FUNC_kdf_newctx（） A pointer to the provider side structure should be created and returned , In order to be in KDF Save context information during operation . The pointer to this context will be in many other KDF The operation function is passed back in the call . Parameters provctx Is the provider context generated during provider initialization （ See Provider ）.

OSSL_FUNC_kdf_freectx（） stay kctx Parameters are passed to the provider side KDF Pointer to context . If it receives NULL As kctx value , Then in addition to returning , It should not perform any other operations . This function should release any resources associated with this context .

OSSL_FUNC_kdf_dupctx（） Should be in kctx Parameter to copy the provider side KDF Context and return duplicate copies .

encryption / Decryption function

OSSL_FUNC_kdf_reset（） stay kctx The provider side is given in the parameter KDF Initialize in context KDF operation .

OSSL_FUNC_kdf_derive（） In accordance with OSSL_FUNC_kdf_set_ctx_params（） Execute after processing parameters KDF operation .kctx The parameter contains a pointer to the provider side context . The generated key of the required key should be written into the key . If the algorithm does not support the requested key , Then the function must return an error .

KDF Parameters

More details about the parameter structures used by these functions , Please see the OSSL_PARAM.

OSSL_FUNC_kdf_get_params（） Get the details of the parameter values associated with the provider Algorithm , And store them in params in .

OSSL_FUNC_kdf_set_ctx_params（） Will work with the given provider side KDF Context kctx The associated KDF Parameter set to params. Any parameter setting is an additional setting to any parameter setting previously set . by params Pass on NULL Should return true.

OSSL_FUNC_kdf_get_ctx_params（） Retrieve with the given provider side KDF Context kctx Associated obtainable parameter values , And store them in params in . by params Pass on NULL Should return true.

OSSL_FUNC_kdf_gettable_params（）、OSSL_FUNC_kdf_gettable_ctx_params（） and OSSL_FUNC_kdf_settable_ctx_params（） Both return constants OSSL_PARAM Array , As OSSL_FUNC_kdf_get_params（）、OSSL_FUNC_kdf_get_ctx_params（） and OSSL_FUNC_kdf_set_ctx_params（） Descriptors of parameters that can be processed separately .OSSL_FUNC_kdf_gettable_ctx_params（） and OSSL_FUNC_kdf_settable_ctx_params（） Will return the provider side context with the current state kctx Associated parameters （ If it's not NULL）. otherwise , They will return with the provider side Algorithm provctx Associated parameters .

built-in KDF The currently recognized parameters are as follows . Not all parameters are related to all KDF Related to or owned by KDF understand ：

• “size” (OSSL_KDF_PARAM_SIZE) < unsigned integer >
  From associated KDF ctx Get the output size . If the algorithm generates a variable output , Then return to SIZE_MAX. If the input parameters required to calculate the fixed output size have not been provided , Then return to 0 To indicate an error .

• “key” （OSSL_KDF_PARAM_KEY） < octet string >
  In the related KDF ctx Set the key in .

• “secret” (OSSL_KDF_PARAM_SECRET) < octet string >
  In the related KDF ctx Set the key in .

• “pass” (OSSL_KDF_PARAM_PASSWORD) < octet string >
  In the related KDF ctx Set the password in .

• “cipher” (OSSL_KDF_PARAM_CIPHER) < UTF8 string >
  “digest” (OSSL_KDF_PARAM_DIGEST) < UTF8 string >
  “mac” (OSSL_KDF_PARAM_MAC) < UTF8 string >
  Set the basic password to use 、 Summary or MAC The name of . It must be in use KDF Name the appropriate algorithm .

• “maclen” (OSSL_KDF_PARAM_MAC_SIZE) < octet string >
  In the related KDF ctx Set in MAC The length of .

• “properties” (OSSL_KDF_PARAM_PROPERTIES) < UTF8 string >
  Set the properties to be queried when trying to get the basic algorithm . This must be given together with the algorithm naming parameters , Can be considered effective .

• “iter” (OSSL_KDF_PARAM_ITER) < unsigned integer >
  Set the associated KDF ctx The number of iterations in .

• “mode” (OSSL_KDF_PARAM_MODE) < UTF8 string >
  In the related KDF ctx Set the mode in .

• “pkcs5” (OSSL_KDF_PARAM_PKCS5) < integer >
  Enable or disable SP800-132 Compliance check . Pattern 0 Compliance checking will be enabled .
  The checks performed include ：

  1. The iteration count is at least 1000.
  2. The length of salt is at least 128 position .
  3. The derived key length is at least 112 position .

• “ukm” (OSSL_KDF_PARAM_UKM) < octet string >
  Set the name provided by the sender to "partyAInfo" Optional random string . stay CMS in , This is the user key material .

• “cekalg” (OSSL_KDF_PARAM_CEK_ALG) < UTF8 string >
  In the related KDF ctx Set in CEK Packing algorithm name .

• “n” (OSSL_KDF_PARAM_SCRYPT_N) < unsigned integer >
  In the related KDF ctx Set in scrypt Working factor parameters N.

• “r” (OSSL_KDF_PARAM_SCRYPT_R) < unsigned integer >
  In the related KDF ctx Set the concealed work factor parameter in r.

• “p” (OSSL_KDF_PARAM_SCRYPT_P) < unsigned integer >
  In the related KDF ctx Set in scrypt Working factor parameters p.

• “maxmem_bytes” (OSSL_KDF_PARAM_SCRYPT_MAXMEM) < unsigned integer >
  In the related KDF ctx Set in scrypt Working factor parameters maxmem.

• “prefix” (OSSL_KDF_PARAM_PREFIX) < octet string >
  Set by TLS 1.3 Version of HKDF In the related KDF ctx Prefix string used in .

• “label” (OSSL_KDF_PARAM_LABEL) < octet string >
  Set by TLS 1.3 Version of HKDF In the related KDF ctx Label string used in .

• “data” (OSSL_KDF_PARAM_DATA) < octet string >
  In the related KDF ctx Used by TLS 1.3 Version of HKDF Context string used .

• “info” (OSSL_KDF_PARAM_INFO) < octet string >
  In the related KDF ctx Set optional shared information in .

• “seed” (OSSL_KDF_PARAM_SEED) < octet string >
  In the related KDF ctx Set in IV.

• “xcghash” (OSSL_KDF_PARAM_SSHKDF_XCGHASH) < octet string >
  In the related KDF ctx Set in xcghash.

• “session_id” (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) < octet string >
  In the related KDF ctx Set up session ID.

• “type” (OSSL_KDF_PARAM_SSHKDF_TYPE) < UTF8 string >
  In the related KDF ctx Set in SSH KDF Type parameter . There are six supported types ：

  1. EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
     Initial from client to server IV. The value is 65 A single character of （ASCII character "A"）.

  2. EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
     Initial from server to client IV The value is 66 A single character of （ASCII character "B"）.

  3. EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV
     Encryption key from client to server The value is 67 A single character of （ASCII character "C"）.

  4. EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI
     Encryption key from server to client The value is 68 A single character of （ASCII character "D"）.

  5. EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV
     Integrity key from client to server The value is 69 A single character of （ASCII character "E"）.

  6. EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI
     Integrity key from client to server The value is 70 A single character of （ASCII character "F"）.

• “constant” (OSSL_KDF_PARAM_CONSTANT) < octet string >
  In the related KDF ctx Set constant value in .

• “id” (OSSL_KDF_PARAM_PKCS12_ID) < integer >
  Set correlation KDF ctx Expected usage of the output bit in . It is based on RFC 7292 B.3 Section .

Return value

OSSL_FUNC_kdf_newctx（） and OSSL_FUNC_kdf_dupctx（） The newly created provider side should be returned KDF Context , Or return... In case of failure NULL.

OSSL_FUNC_kdf_derive（）、OSSL_FUNC_kdf_get_params（）、OSSL_FUNC_kdf_get_ctx_params（） and OSSL_FUNC_kdf_set_ctx_params（） Should return 1 It means success , Or return when there is an error 0.

OSSL_FUNC_kdf_gettable_params（）、OSSL_FUNC_kdf_gettable_ctx_params（） and OSSL_FUNC_kdf_settable_ctx_params（） Should return a constant OSSL_PARAM Array , If not provided , Then return to NULL.

Be careful

KDF Life cycle in life_cycle-kdf Described in . The provider should ensure that the various transformations listed therein are supported . At some point ,EVP The layer will begin to enforce the listed transformations .