diff --git a/doc/build.info b/doc/build.info index 7d3b2fe774507..a2db40e21870a 100644 --- a/doc/build.info +++ b/doc/build.info @@ -1551,6 +1551,14 @@ DEPEND[html/man3/OPENSSL_strcasecmp.html]=man3/OPENSSL_strcasecmp.pod GENERATE[html/man3/OPENSSL_strcasecmp.html]=man3/OPENSSL_strcasecmp.pod DEPEND[man/man3/OPENSSL_strcasecmp.3]=man3/OPENSSL_strcasecmp.pod GENERATE[man/man3/OPENSSL_strcasecmp.3]=man3/OPENSSL_strcasecmp.pod +DEPEND[html/man3/OSSL_ALGORITHM.html]=man3/OSSL_ALGORITHM.pod +GENERATE[html/man3/OSSL_ALGORITHM.html]=man3/OSSL_ALGORITHM.pod +DEPEND[man/man3/OSSL_ALGORITHM.3]=man3/OSSL_ALGORITHM.pod +GENERATE[man/man3/OSSL_ALGORITHM.3]=man3/OSSL_ALGORITHM.pod +DEPEND[html/man3/OSSL_CALLBACK.html]=man3/OSSL_CALLBACK.pod +GENERATE[html/man3/OSSL_CALLBACK.html]=man3/OSSL_CALLBACK.pod +DEPEND[man/man3/OSSL_CALLBACK.3]=man3/OSSL_CALLBACK.pod +GENERATE[man/man3/OSSL_CALLBACK.3]=man3/OSSL_CALLBACK.pod DEPEND[html/man3/OSSL_CMP_CTX_new.html]=man3/OSSL_CMP_CTX_new.pod GENERATE[html/man3/OSSL_CMP_CTX_new.html]=man3/OSSL_CMP_CTX_new.pod DEPEND[man/man3/OSSL_CMP_CTX_new.3]=man3/OSSL_CMP_CTX_new.pod @@ -1631,6 +1639,10 @@ DEPEND[html/man3/OSSL_DECODER_from_bio.html]=man3/OSSL_DECODER_from_bio.pod GENERATE[html/man3/OSSL_DECODER_from_bio.html]=man3/OSSL_DECODER_from_bio.pod DEPEND[man/man3/OSSL_DECODER_from_bio.3]=man3/OSSL_DECODER_from_bio.pod GENERATE[man/man3/OSSL_DECODER_from_bio.3]=man3/OSSL_DECODER_from_bio.pod +DEPEND[html/man3/OSSL_DISPATCH.html]=man3/OSSL_DISPATCH.pod +GENERATE[html/man3/OSSL_DISPATCH.html]=man3/OSSL_DISPATCH.pod +DEPEND[man/man3/OSSL_DISPATCH.3]=man3/OSSL_DISPATCH.pod +GENERATE[man/man3/OSSL_DISPATCH.3]=man3/OSSL_DISPATCH.pod DEPEND[html/man3/OSSL_ENCODER.html]=man3/OSSL_ENCODER.pod GENERATE[html/man3/OSSL_ENCODER.html]=man3/OSSL_ENCODER.pod DEPEND[man/man3/OSSL_ENCODER.3]=man3/OSSL_ENCODER.pod @@ -1667,6 +1679,10 @@ DEPEND[html/man3/OSSL_HTTP_transfer.html]=man3/OSSL_HTTP_transfer.pod GENERATE[html/man3/OSSL_HTTP_transfer.html]=man3/OSSL_HTTP_transfer.pod DEPEND[man/man3/OSSL_HTTP_transfer.3]=man3/OSSL_HTTP_transfer.pod GENERATE[man/man3/OSSL_HTTP_transfer.3]=man3/OSSL_HTTP_transfer.pod +DEPEND[html/man3/OSSL_ITEM.html]=man3/OSSL_ITEM.pod +GENERATE[html/man3/OSSL_ITEM.html]=man3/OSSL_ITEM.pod +DEPEND[man/man3/OSSL_ITEM.3]=man3/OSSL_ITEM.pod +GENERATE[man/man3/OSSL_ITEM.3]=man3/OSSL_ITEM.pod DEPEND[html/man3/OSSL_LIB_CTX.html]=man3/OSSL_LIB_CTX.pod GENERATE[html/man3/OSSL_LIB_CTX.html]=man3/OSSL_LIB_CTX.pod DEPEND[man/man3/OSSL_LIB_CTX.3]=man3/OSSL_LIB_CTX.pod @@ -3167,6 +3183,8 @@ html/man3/OPENSSL_malloc.html \ html/man3/OPENSSL_s390xcap.html \ html/man3/OPENSSL_secure_malloc.html \ html/man3/OPENSSL_strcasecmp.html \ +html/man3/OSSL_ALGORITHM.html \ +html/man3/OSSL_CALLBACK.html \ html/man3/OSSL_CMP_CTX_new.html \ html/man3/OSSL_CMP_HDR_get0_transactionID.html \ html/man3/OSSL_CMP_ITAV_set0.html \ @@ -3187,6 +3205,7 @@ html/man3/OSSL_DECODER.html \ html/man3/OSSL_DECODER_CTX.html \ html/man3/OSSL_DECODER_CTX_new_for_pkey.html \ html/man3/OSSL_DECODER_from_bio.html \ +html/man3/OSSL_DISPATCH.html \ html/man3/OSSL_ENCODER.html \ html/man3/OSSL_ENCODER_CTX.html \ html/man3/OSSL_ENCODER_CTX_new_for_pkey.html \ @@ -3196,6 +3215,7 @@ html/man3/OSSL_HPKE_CTX_new.html \ html/man3/OSSL_HTTP_REQ_CTX.html \ html/man3/OSSL_HTTP_parse_url.html \ html/man3/OSSL_HTTP_transfer.html \ +html/man3/OSSL_ITEM.html \ html/man3/OSSL_LIB_CTX.html \ html/man3/OSSL_PARAM.html \ html/man3/OSSL_PARAM_BLD.html \ @@ -3774,6 +3794,8 @@ man/man3/OPENSSL_malloc.3 \ man/man3/OPENSSL_s390xcap.3 \ man/man3/OPENSSL_secure_malloc.3 \ man/man3/OPENSSL_strcasecmp.3 \ +man/man3/OSSL_ALGORITHM.3 \ +man/man3/OSSL_CALLBACK.3 \ man/man3/OSSL_CMP_CTX_new.3 \ man/man3/OSSL_CMP_HDR_get0_transactionID.3 \ man/man3/OSSL_CMP_ITAV_set0.3 \ @@ -3794,6 +3816,7 @@ man/man3/OSSL_DECODER.3 \ man/man3/OSSL_DECODER_CTX.3 \ man/man3/OSSL_DECODER_CTX_new_for_pkey.3 \ man/man3/OSSL_DECODER_from_bio.3 \ +man/man3/OSSL_DISPATCH.3 \ man/man3/OSSL_ENCODER.3 \ man/man3/OSSL_ENCODER_CTX.3 \ man/man3/OSSL_ENCODER_CTX_new_for_pkey.3 \ @@ -3803,6 +3826,7 @@ man/man3/OSSL_HPKE_CTX_new.3 \ man/man3/OSSL_HTTP_REQ_CTX.3 \ man/man3/OSSL_HTTP_parse_url.3 \ man/man3/OSSL_HTTP_transfer.3 \ +man/man3/OSSL_ITEM.3 \ man/man3/OSSL_LIB_CTX.3 \ man/man3/OSSL_PARAM.3 \ man/man3/OSSL_PARAM_BLD.3 \ diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod index 6ea298e0a9a8c..e170edf343af7 100644 --- a/doc/internal/man3/ossl_provider_new.pod +++ b/doc/internal/man3/ossl_provider_new.pod @@ -295,7 +295,7 @@ I<*result> to 1 or 0 accorddingly. ossl_provider_init_as_child() stores in the library context I references to the necessary upcalls for managing child providers. The I and I -parameters are the B and B pointers that were +parameters are the B and L pointers that were passed to the provider's B function. ossl_provider_deinit_child() deregisters callbacks from the parent library diff --git a/doc/man3/EVP_ASYM_CIPHER_free.pod b/doc/man3/EVP_ASYM_CIPHER_free.pod index 72910a5599015..c158ec1ae74a7 100644 --- a/doc/man3/EVP_ASYM_CIPHER_free.pod +++ b/doc/man3/EVP_ASYM_CIPHER_free.pod @@ -75,7 +75,7 @@ meant for display and human consumption. The description is at the discretion of the I implementation. EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() -return a constant B array that describes the names and types of key +return a constant L array that describes the names and types of key parameters that can be retrieved or set by a key encryption algorithm using L and L. @@ -90,7 +90,7 @@ EVP_ASYM_CIPHER_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names. EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params() -return a constant B array or NULL on error. +return a constant L array or NULL on error. =head1 SEE ALSO diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index 2bbd35f395fc5..183f2e09bd82e 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -208,27 +208,24 @@ See L below for more information. =item EVP_MD_gettable_params() -Get a constant B array that describes the retrievable parameters -that can be used with EVP_MD_get_params(). See L for the -use of B as a parameter descriptor. +Get a constant L array that describes the retrievable parameters +that can be used with EVP_MD_get_params(). =item EVP_MD_gettable_ctx_params(), EVP_MD_CTX_gettable_params() -Get a constant B array that describes the retrievable parameters +Get a constant L array that describes the retrievable parameters that can be used with EVP_MD_CTX_get_params(). EVP_MD_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_MD_CTX_gettable_params() returns the parameters that can be retrieved -in the context's current state. See L for the use of -B as a parameter descriptor. +in the context's current state. =item EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() -Get a constant B array that describes the settable parameters +Get a constant L array that describes the settable parameters that can be used with EVP_MD_CTX_set_params(). EVP_MD_settable_ctx_params() returns the parameters that can be set from the algorithm, whereas EVP_MD_CTX_settable_params() returns the parameters that can be set in the -context's current state. See L for the use of B -as a parameter descriptor. +context's current state. =item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags() @@ -596,7 +593,7 @@ Returns 1 if successful or 0 for failure. =item EVP_MD_CTX_settable_params(), EVP_MD_CTX_gettable_params() -Return an array of constant Bs, or NULL if there is none +Return an array of constant Ls, or NULL if there is none to get. =item EVP_MD_CTX_dup() diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index dafa71c9f66e0..1d5cb6c7595d5 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -330,27 +330,24 @@ See L below for more information. =item EVP_CIPHER_gettable_params() -Get a constant B array that describes the retrievable parameters -that can be used with EVP_CIPHER_get_params(). See L for the -use of B as a parameter descriptor. +Get a constant L array that describes the retrievable parameters +that can be used with EVP_CIPHER_get_params(). =item EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params() -Get a constant B array that describes the retrievable parameters +Get a constant L array that describes the retrievable parameters that can be used with EVP_CIPHER_CTX_get_params(). EVP_CIPHER_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_CIPHER_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state. -See L for the use of B as a parameter descriptor. =item EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params() -Get a constant B array that describes the settable parameters +Get a constant L array that describes the settable parameters that can be used with EVP_CIPHER_CTX_set_params(). EVP_CIPHER_settable_ctx_params() returns the parameters that can be set from the algorithm, whereas EVP_CIPHER_CTX_settable_params() returns the parameters that can be set in the context's current state. -See L for the use of B as a parameter descriptor. =item EVP_EncryptInit_ex2() @@ -654,7 +651,7 @@ See L for information about passing parameters. When EVP_CIPHER_fetch() is called it internally calls EVP_CIPHER_get_params() and caches the results. -EVP_CIPHER_get_params() can be used with the following B keys: +EVP_CIPHER_get_params() can be used with the following L keys: =over 4 @@ -725,7 +722,7 @@ all other OpenSSL ciphers return 0. =head2 Gettable and Settable EVP_CIPHER_CTX parameters -The following B keys can be used with both EVP_CIPHER_CTX_get_params() +The following L keys can be used with both EVP_CIPHER_CTX_get_params() and EVP_CIPHER_CTX_set_params(). =over 4 @@ -816,7 +813,7 @@ cipher operation (either 4 or 8 records). =head2 Gettable EVP_CIPHER_CTX parameters -The following B keys can be used with EVP_CIPHER_CTX_get_params(): +The following L keys can be used with EVP_CIPHER_CTX_get_params(): =over 4 @@ -885,7 +882,7 @@ Used to pass the TLS MAC data. =head2 Settable EVP_CIPHER_CTX parameters -The following B keys can be used with EVP_CIPHER_CTX_set_params(): +The following L keys can be used with EVP_CIPHER_CTX_set_params(): =over 4 diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod index a8cc83324e427..3b4e2b79aa145 100644 --- a/doc/man3/EVP_KDF.pod +++ b/doc/man3/EVP_KDF.pod @@ -131,26 +131,23 @@ simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation. -EVP_KDF_gettable_params() returns an B array that describes +EVP_KDF_gettable_params() returns an L array that describes the retrievable and settable parameters. EVP_KDF_gettable_params() returns parameters that can be used with EVP_KDF_get_params(). -See L for the use of B as a parameter descriptor. EVP_KDF_gettable_ctx_params() and EVP_KDF_CTX_gettable_params() -return constant B arrays that describe the retrievable +return constant L arrays that describe the retrievable parameters that can be used with EVP_KDF_CTX_get_params(). EVP_KDF_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_KDF_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state. -See L for the use of B as a parameter descriptor. EVP_KDF_settable_ctx_params() and EVP_KDF_CTX_settable_params() return -constant B arrays that describe the settable parameters that +constant L arrays that describe the settable parameters that can be used with EVP_KDF_CTX_set_params(). EVP_KDF_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_KDF_CTX_settable_params() returns the parameters that can -be retrieved in the context's current state. See L -for the use of B as a parameter descriptor. +be retrieved in the context's current state. =head2 Information functions diff --git a/doc/man3/EVP_KEM_free.pod b/doc/man3/EVP_KEM_free.pod index e77b89d3b97fc..575abc5f5798c 100644 --- a/doc/man3/EVP_KEM_free.pod +++ b/doc/man3/EVP_KEM_free.pod @@ -68,7 +68,7 @@ display and human consumption. The description is at the discretion of the I implementation. EVP_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() return -a constant B array that describes the names and types of key +a constant L array that describes the names and types of key parameters that can be retrieved or set by a key encapsulation algorithm using L and L. @@ -83,7 +83,7 @@ EVP_KEM_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names. EVP_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() return -a constant B array or NULL on error. +a constant L array or NULL on error. =head1 SEE ALSO diff --git a/doc/man3/EVP_KEYEXCH_free.pod b/doc/man3/EVP_KEYEXCH_free.pod index 42c7e1289c00e..272855ccb3dd8 100644 --- a/doc/man3/EVP_KEYEXCH_free.pod +++ b/doc/man3/EVP_KEYEXCH_free.pod @@ -71,7 +71,7 @@ of the implementations, calls I with the implementation method and I as arguments. EVP_KEYEXCH_gettable_ctx_params() and EVP_KEYEXCH_settable_ctx_params() return -a constant B array that describes the names and types of key +a constant L array that describes the names and types of key parameters that can be retrieved or set by a key exchange algorithm using L and L. @@ -89,7 +89,7 @@ EVP_KEYEXCH_is_a() returns 1 of I was identifiable, otherwise 0. EVP_KEYEXCH_gettable_ctx_params() and EVP_KEYEXCH_settable_ctx_params() return -a constant B array or NULL on error. +a constant L array or NULL on error. =head1 SEE ALSO diff --git a/doc/man3/EVP_KEYMGMT.pod b/doc/man3/EVP_KEYMGMT.pod index 2131694e0b8de..da03286a996e4 100644 --- a/doc/man3/EVP_KEYMGMT.pod +++ b/doc/man3/EVP_KEYMGMT.pod @@ -88,12 +88,11 @@ of the implementations, calls I with the implementation method and I as arguments. EVP_KEYMGMT_gettable_params() and EVP_KEYMGMT_settable_params() return a -constant B array that describes the names and types of key +constant L array that describes the names and types of key parameters that can be retrieved or set. EVP_KEYMGMT_gettable_params() is used by L. -See L for the use of B as a parameter descriptor. -EVP_KEYMGMT_gen_settable_params() returns a constant B array that +EVP_KEYMGMT_gen_settable_params() returns a constant L array that describes the names and types of key generation parameters that can be set via L. @@ -128,7 +127,7 @@ EVP_KEYMGMT_get0_description() returns a pointer to a description, or NULL if there isn't one. EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and -EVP_KEYMGMT_gen_settable_params() return a constant B array or +EVP_KEYMGMT_gen_settable_params() return a constant L array or NULL on error. =head1 SEE ALSO diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index 289cbda757197..13482ac5e188e 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -187,26 +187,23 @@ simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation. -EVP_MAC_gettable_params() returns an B array that describes +EVP_MAC_gettable_params() returns an L array that describes the retrievable and settable parameters. EVP_MAC_gettable_params() returns parameters that can be used with EVP_MAC_get_params(). -See L for the use of B as a parameter descriptor. EVP_MAC_gettable_ctx_params() and EVP_MAC_CTX_gettable_params() -return constant B arrays that describe the retrievable +return constant L arrays that describe the retrievable parameters that can be used with EVP_MAC_CTX_get_params(). EVP_MAC_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_MAC_CTX_gettable_params() returns the parameters that can be retrieved in the context's current state. -See L for the use of B as a parameter descriptor. EVP_MAC_settable_ctx_params() and EVP_MAC_CTX_settable_params() return -constant B arrays that describe the settable parameters that +constant L arrays that describe the settable parameters that can be used with EVP_MAC_CTX_set_params(). EVP_MAC_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_MAC_CTX_settable_params() returns the parameters that can -be retrieved in the context's current state. See L -for the use of B as a parameter descriptor. +be retrieved in the context's current state. =head2 Information functions diff --git a/doc/man3/EVP_PKEY_CTX_set_params.pod b/doc/man3/EVP_PKEY_CTX_set_params.pod index b8855c2670fbb..c02151654c3a6 100644 --- a/doc/man3/EVP_PKEY_CTX_set_params.pod +++ b/doc/man3/EVP_PKEY_CTX_set_params.pod @@ -30,11 +30,10 @@ These methods replace the EVP_PKEY_CTX_ctrl() mechanism. (EVP_PKEY_CTX_ctrl now calls these methods internally to interact with providers). EVP_PKEY_CTX_gettable_params() and EVP_PKEY_CTX_settable_params() get a -constant B array that describes the gettable and +constant L array that describes the gettable and settable parameters for the current algorithm implementation, i.e. parameters that can be used with EVP_PKEY_CTX_get_params() and EVP_PKEY_CTX_set_params() respectively. -See L for the use of B as parameter descriptor. These functions must only be called after the EVP_PKEY_CTX has been initialised for use in an operation. diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod index 158d1bf42d5a1..2cdbced9cfdb6 100644 --- a/doc/man3/EVP_PKEY_fromdata.pod +++ b/doc/man3/EVP_PKEY_fromdata.pod @@ -48,10 +48,9 @@ and L(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 an =for comment the awful list of links above is made this way so we get nice rendering as a man-page while still getting proper links in HTML -EVP_PKEY_fromdata_settable() gets a constant B array that describes +EVP_PKEY_fromdata_settable() gets a constant L array that describes the settable parameters that can be used with EVP_PKEY_fromdata(). I is described in L. -See L for the use of B as parameter descriptor. Parameters in the I array that are not among the settable parameters for the given I are ignored. diff --git a/doc/man3/EVP_PKEY_gettable_params.pod b/doc/man3/EVP_PKEY_gettable_params.pod index ba87289937d9e..8dd0fc543e5d7 100644 --- a/doc/man3/EVP_PKEY_gettable_params.pod +++ b/doc/man3/EVP_PKEY_gettable_params.pod @@ -29,15 +29,15 @@ EVP_PKEY_get_octet_string_param =head1 DESCRIPTION +See L for information about parameters. + EVP_PKEY_get_params() retrieves parameters from the key I, according to the contents of I. -See L for information about parameters. EVP_PKEY_gettable_params() returns a constant list of I indicating the names and types of key parameters that can be retrieved. -See L for information about parameters. -An B of type B or +An L of type B or B is of arbitrary length. Such a parameter can be obtained using any of the functions EVP_PKEY_get_int_param(), EVP_PKEY_get_size_t_param() or EVP_PKEY_get_bn_param(). Attempting to diff --git a/doc/man3/EVP_PKEY_todata.pod b/doc/man3/EVP_PKEY_todata.pod index 14db9e6efdd8e..c28a867b7a9b7 100644 --- a/doc/man3/EVP_PKEY_todata.pod +++ b/doc/man3/EVP_PKEY_todata.pod @@ -16,7 +16,7 @@ EVP_PKEY_todata, EVP_PKEY_export =head1 DESCRIPTION The functions described here are used to extract B key values as an -array of B. +array of L. EVP_PKEY_todata() extracts values from a key I using the I. I is described in L. @@ -26,7 +26,7 @@ I<*params>. EVP_PKEY_export() is similar to EVP_PKEY_todata() but uses a callback I that gets passed the value of I. See L for more information about the callback. Note that the -B array that is passed to the callback is not persistent after the +L array that is passed to the callback is not persistent after the callback returns. The user must preserve the items of interest, or use EVP_PKEY_todata() if persistence is required. diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod index 6aae33b5fd949..a187ed66252b3 100644 --- a/doc/man3/EVP_RAND.pod +++ b/doc/man3/EVP_RAND.pod @@ -187,26 +187,23 @@ simply ignored. Also, what happens when a needed parameter isn't passed down is defined by the implementation. -EVP_RAND_gettable_params() returns an B array that describes +EVP_RAND_gettable_params() returns an L array that describes the retrievable and settable parameters. EVP_RAND_gettable_params() returns -parameters that can be used with EVP_RAND_get_params(). See L -for the use of B as a parameter descriptor. +parameters that can be used with EVP_RAND_get_params(). EVP_RAND_gettable_ctx_params() and EVP_RAND_CTX_gettable_params() return -constant B arrays that describe the retrievable parameters that +constant L arrays that describe the retrievable parameters that can be used with EVP_RAND_CTX_get_params(). EVP_RAND_gettable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_gettable_params() returns the parameters that can be retrieved -in the context's current state. See L for the use of -B as a parameter descriptor. +in the context's current state. EVP_RAND_settable_ctx_params() and EVP_RAND_CTX_settable_params() return -constant B arrays that describe the settable parameters that +constant L arrays that describe the settable parameters that can be used with EVP_RAND_CTX_set_params(). EVP_RAND_settable_ctx_params() returns the parameters that can be retrieved from the algorithm, whereas EVP_RAND_CTX_settable_params() returns the parameters that can be retrieved -in the context's current state. See L for the use of -B as a parameter descriptor. +in the context's current state. =head2 Information functions diff --git a/doc/man3/EVP_SIGNATURE.pod b/doc/man3/EVP_SIGNATURE.pod index 9fb389e7aeb0e..600522085398c 100644 --- a/doc/man3/EVP_SIGNATURE.pod +++ b/doc/man3/EVP_SIGNATURE.pod @@ -79,7 +79,7 @@ meant for display and human consumption. The description is at the discretion of the I implementation. EVP_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params() -return a constant B array that describes the names and types of key +return a constant L array that describes the names and types of key parameters that can be retrieved or set by a signature algorithm using L and L. @@ -94,7 +94,7 @@ EVP_SIGNATURE_names_do_all() returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names. EVP_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params() -return a constant B array or NULL on error. +return a constant L array or NULL on error. =head1 SEE ALSO diff --git a/doc/man3/OSSL_ALGORITHM.pod b/doc/man3/OSSL_ALGORITHM.pod new file mode 100644 index 0000000000000..cc9271b9a412c --- /dev/null +++ b/doc/man3/OSSL_ALGORITHM.pod @@ -0,0 +1,151 @@ +=pod + +=head1 NAME + +OSSL_ALGORITHM - OpenSSL Core type to define a fetchable algorithm + +=head1 SYNOPSIS + + #include + + typedef struct ossl_algorithm_st OSSL_ALGORITHM; + struct ossl_algorithm_st { + const char *algorithm_names; /* key */ + const char *property_definition; /* key */ + const OSSL_DISPATCH *implementation; + const char *algorithm_description; + }; + +=head1 DESCRIPTION + +The B type is a I that describes an +algorithm that a L provides. Arrays of this type are returned +by providers on demand from the OpenSSL libraries to describe what +algorithms the providers provide implementations of, and with what +properties. + +Arrays of this type must be terminated with a tuple where I +is NULL. + +This type of array is typically returned by the provider's operation querying +function, further described in L. + +=head2 B fields + +=over 4 + +=item I + +This string is a colon separated set of names / identities, and is used by +the appropriate fetching functionality (such as L, +L, etc) to find the desired algorithm. + +Multiple names / identities allow a specific algorithm implementation to be +fetched multiple ways. For example, the RSA algorithm has the following +known identities: + +=over 4 + +=item * + +C + +=item * + +C + +This is the name of the algorithm's OBJECT IDENTIFIER (OID), as given by the +L + +=item * + +C<1.2.840.113549.1.1.1> + +This is the OID itself for C, in canonical decimal text form. + +=back + +The resulting I string would look like this: + + "RSA:rsaEncryption:1.2.840.113549.1.1.1" + +The OpenSSL libraries use the first of the algorithm names as the main +or canonical name, on a per algorithm implementation basis. + +See the notes L below for a more in +depth discussion on I and how that may interact with +applications and libraries, including OpenSSL's. + +=item I + +This string defines a set of properties associated with a particular +algorithm implementation, and is used by the appropriate fetching +functionality (such as L, L, etc) for +a finer grained lookup of an algorithm implementation, which is useful in +case multiple implementations of the same algorithm are available. + +See L for a further description of the contents of this +string. + +=item I + +Pointer to an L array, containing pointers to the +functions of a particular algorithm implementation. + +=item I + +A string with a short human-readable description of the algorithm. + +=back + +=head1 NOTES + +=head2 On the subject of algorithm names + +Providers may find the need to register ASN.1 OIDs for algorithms using +L (via the B upcall described in +L, because some application or library -- possibly still +the OpenSSL libraries, even -- use NIDs to look up algorithms. + +In that scenario, you must make sure that the corresponding B's +I includes both the short and the long name. + +Most of the time, registering ASN.1 OIDs like this shouldn't be necessary, +and applications and libraries are encouraged to use L to +get a text representation of the OID, which may be a long or short name for +OIDs that are registered, or the OID itself in canonical decimal text form +if not (or if L is called with I = 1). + +It's recommended to make sure that the corresponding B's +I include known names as well as the OID itself in +canonical decimal text form. That should cover all scenarios. + +=begin comment RETURN VALUES doesn't make sense for a manual that only +describes a type, but document checkers still want that section, and +to have more than just the section title. + +=head1 RETURN VALUES + +txt + +=end comment + +=head1 SEE ALSO + +L, L, L, +L, L + +=head1 HISTORY + +B was added in OpenSSL 3.0 + +=head1 COPYRIGHT + +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man3/OSSL_CALLBACK.pod b/doc/man3/OSSL_CALLBACK.pod new file mode 100644 index 0000000000000..5fa8a8f089161 --- /dev/null +++ b/doc/man3/OSSL_CALLBACK.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +OSSL_CALLBACK, OSSL_PASSPHRASE_CALLBACK - OpenSSL Core type to define callbacks + +=head1 SYNOPSIS + + #include + typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); + typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, + size_t *pass_len, + const OSSL_PARAM params[], + void *arg); + +=head1 DESCRIPTION + +For certain events or activities, provider functionality may need help from +the application or the calling OpenSSL libraries themselves. For example, +user input or direct (possibly optional) user output could be implemented +this way. + +Callback functions themselves are always provided by or through the calling +OpenSSL libraries, along with a generic pointer to data I. As far as +the function receiving the pointer to the function pointer and I is +concerned, the data that I points at is opaque, and the pointer should +simply be passed back to the callback function when it's called. + +=over 4 + +=item B + +This is a generic callback function. When calling this callback function, +the caller is expected to build an L array of data it wants or +is expected to pass back, and pass that as I, as well as the opaque +data pointer it received, as I. + +=item B + +This is a specialised callback function, used specifically to prompt the +user for a passphrase. When calling this callback function, a buffer to +store the pass phrase needs to be given with I, and its size with +I. The length of the prompted pass phrase will be given back in +I<*pass_len>. + +Additional parameters can be passed with the L array I, + +=back + +=begin comment RETURN VALUES doesn't make sense for a manual that only +describes a type, but document checkers still want that section, and +to have more than just the section title. + +=head1 RETURN VALUES + +txt + +=end comment + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The types described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod index 26c0f0ae2e21b..4b4443777ad70 100644 --- a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod +++ b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod @@ -79,9 +79,9 @@ OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui() and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the implementation can use to prompt for a pass phrase, giving the caller the choice of preferred pass phrase callback form. These are called indirectly, -through an internal B function. +through an internal L function. -The internal B function caches the pass phrase, to +The internal L function caches the pass phrase, to be re-used in all decodings that are performed in the same decoding run (for example, within one L call). diff --git a/doc/man3/OSSL_DISPATCH.pod b/doc/man3/OSSL_DISPATCH.pod new file mode 100644 index 0000000000000..1aca4019dcbc1 --- /dev/null +++ b/doc/man3/OSSL_DISPATCH.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +OSSL_DISPATCH - OpenSSL Core type to define a dispatchable function table + +=head1 SYNOPSIS + + #include + + typedef struct ossl_dispatch_st OSSL_DISPATCH; + struct ossl_dispatch_st { + int function_id; + void (*function)(void); + }; + +=head1 DESCRIPTION + +This type is a tuple of function identity and function pointer. +Arrays of this type are passed between the OpenSSL libraries and the +providers to describe what functionality one side provides to the other. + +Arrays of this type must be terminated with a tuple having function identity +zero and function pointer NULL. + +=head2 B fields + +=over 4 + +=item I + +OpenSSL defined function identity of the implemented function. + +=item I + +Pointer to the implemented function itself. Despite the generic definition +of this field, the implemented function it points to must have a function +signature that corresponds to the I + +=back + +Available function identities and corresponding function signatures are +defined in L. +Furthermore, the chosen function identities and associated function +signature must be chosen specifically for the operation that it's intended +for, as determined by the intended L array. + +Any function identity not recognised by the recipient of this type +will be ignored. +This ensures that providers built with one OpenSSL version in mind +will work together with any other OpenSSL version that supports this +mechanism. + +=begin comment RETURN VALUES doesn't make sense for a manual that only +describes a type, but document checkers still want that section, and +to have more than just the section title. + +=head1 RETURN VALUES + +txt + +=end comment + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +B was added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod index 8f7d1910ca9ff..3bf9c10e374e5 100644 --- a/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod +++ b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod @@ -79,7 +79,7 @@ OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui() and OSSL_ENCODER_CTX_set_passphrase_cb() sets up a callback method that the implementation can use to prompt for a pass phrase, giving the caller the choice of preferred pass phrase callback form. These are called indirectly, -through an internal B function. +through an internal L function. =head2 Output types diff --git a/doc/man3/OSSL_ITEM.pod b/doc/man3/OSSL_ITEM.pod new file mode 100644 index 0000000000000..70d4bf361b75e --- /dev/null +++ b/doc/man3/OSSL_ITEM.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +OSSL_ITEM - OpenSSL Core type for generic itemized data + +=head1 SYNOPSIS + + #include + + typedef struct ossl_item_st OSSL_ITEM; + struct ossl_item_st { + unsigned int id; + void *ptr; + }; + +=head1 DESCRIPTION + +This type is a tuple of integer and pointer. +It's a generic type used as a generic descriptor, its exact meaning +being defined by how it's used. +Arrays of this type are passed between the OpenSSL libraries and the +providers, and must be terminated with a tuple where the integer is +zero and the pointer NULL. + +This is currently mainly used for the return value of the provider's error +reason strings array, see L. + +=begin comment RETURN VALUES doesn't make sense for a manual that only +describes a type, but document checkers still want that section, and +to have more than just the section title. + +=head1 RETURN VALUES + +txt + +=end comment + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +B was added in OpenSSL 3.0 + +=head1 COPYRIGHT + +Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man3/OSSL_PARAM_allocate_from_text.pod b/doc/man3/OSSL_PARAM_allocate_from_text.pod index 80ba555a8feac..e6dc2549fdb1b 100644 --- a/doc/man3/OSSL_PARAM_allocate_from_text.pod +++ b/doc/man3/OSSL_PARAM_allocate_from_text.pod @@ -102,7 +102,7 @@ I and there was no other failure, otherwise 0. The parameter descriptor array comes from functions dedicated to return them. -The following B attributes are used: +The following L attributes are used: =over 4 diff --git a/doc/man3/OSSL_PARAM_dup.pod b/doc/man3/OSSL_PARAM_dup.pod index 5130c9e1dcd9c..4ae33faf1e4e8 100644 --- a/doc/man3/OSSL_PARAM_dup.pod +++ b/doc/man3/OSSL_PARAM_dup.pod @@ -16,8 +16,8 @@ OSSL_PARAM_dup, OSSL_PARAM_merge, OSSL_PARAM_free =head1 DESCRIPTION Algorithm parameters can be exported/imported from/to providers using arrays of -B. The following utility functions allow the parameters to be -duplicated and merged with other B to assist in this process. +L. The following utility functions allow the parameters to be +duplicated and merged with other L to assist in this process. OSSL_PARAM_dup() duplicates the parameter array I. This function does a deep copy of the data. @@ -36,7 +36,7 @@ OSSL_PARAM_dup(), OSSL_PARAM_merge() or OSSL_PARAM_BLD_to_param(). =head1 RETURN VALUES The functions OSSL_PARAM_dup() and OSSL_PARAM_merge() return a newly allocated -B array, or NULL if there was an error. If both parameters are NULL +L array, or NULL if there was an error. If both parameters are NULL then NULL is returned. =head1 SEE ALSO diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod index efa94c5d54df2..ffe7c8c76a185 100644 --- a/doc/man3/OSSL_PARAM_int.pod +++ b/doc/man3/OSSL_PARAM_int.pod @@ -110,7 +110,7 @@ OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified =head1 DESCRIPTION A collection of utility functions that simplify and add type safety to the -B arrays. The following B> names are supported: +L arrays. The following B> names are supported: =over 1 @@ -161,7 +161,7 @@ unsigned long int (ulong) =back OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an -array of B structures. +array of L structures. Each of these macros defines a parameter of the specified B> with the provided I and parameter variable I
. @@ -172,46 +172,46 @@ A parameter with name I is defined. The storage for this parameter is at I
and is of I bytes. OSSL_PARAM_END provides an end of parameter list marker. -This should terminate all B arrays. +This should terminate all L arrays. The OSSL_PARAM_DEFN() macro provides the ability to construct a single -B (typically used in the construction of B arrays). The +L (typically used in the construction of B arrays). The I, I, I and I arguments correspond to the I, -I, I and I fields of the B structure as +I, I and I fields of the L structure as described on the L page. -OSSL_PARAM_construct_TYPE() are a series of functions that create B +OSSL_PARAM_construct_TYPE() are a series of functions that create L records dynamically. A parameter with name I is created. The parameter will use storage pointed to by I and return size of I. OSSL_PARAM_construct_BN() is a function that constructs a large integer -B structure. +L structure. A parameter with name I, storage I, size I and return size I is created. OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 -string B structure. +string L structure. A parameter with name I, storage I and size I is created. If I is zero, the string length is determined using strlen(3). Generally pass zero for I instead of calling strlen(3) yourself. OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET -string B structure. +string L structure. A parameter with name I, storage I and size I is created. OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8 string -pointer B structure. +pointer L structure. A parameter with name I, storage pointer I<*buf> and size I is created. OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string -pointer B structure. +pointer L structure. A parameter with name I, storage pointer I<*buf> and size I is created. OSSL_PARAM_construct_end() is a function that constructs the terminating -B structure. +L structure. OSSL_PARAM_locate() is a function that searches an I of parameters for the one matching the I name. @@ -314,10 +314,10 @@ in the array I. OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() -return a populated B structure. +return a populated L structure. OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to -the matching B object. They return NULL on error or when +the matching L object. They return NULL on error or when no object matching I exists in the I. OSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise. @@ -333,11 +333,11 @@ expected type of the parameter. OSSL_PARAM_get_BN() and OSSL_PARAM_set_BN() only support nonnegative Bs when the desired data type is B. -OSSL_PARAM_construct_BN() currently constructs an B structure +OSSL_PARAM_construct_BN() currently constructs an L structure with the data type B. For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), -I is not relevant if the purpose is to send the B array +I is not relevant if the purpose is to send the L array to a I, i.e. to get parameter data back. In that case, I can safely be given zero. See L for further information on the @@ -346,7 +346,7 @@ possible purposes. =head1 EXAMPLES Reusing the examples from L to just show how -B arrays can be handled using the macros and functions +L arrays can be handled using the macros and functions defined herein. =head2 Example 1 diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod index 715aa10b1ff45..699c7e9d5884f 100644 --- a/doc/man3/OSSL_PROVIDER.pod +++ b/doc/man3/OSSL_PROVIDER.pod @@ -110,11 +110,10 @@ See L for more information on this fallback behaviour. OSSL_PROVIDER_gettable_params() is used to get a provider parameter -descriptor set as a constant B array. -See L for more information. +descriptor set as a constant L array. OSSL_PROVIDER_get_params() is used to get provider parameter values. -The caller must prepare the B array before calling this +The caller must prepare the L array before calling this function, and the variables acting as buffers for this parameter array should be filled with data when it returns successfully. @@ -150,7 +149,7 @@ OSSL_PROVIDER_get0_name() returns the name of the given provider. OSSL_PROVIDER_get_capabilities() provides information about the capabilities supported by the provider specified in I with the capability name I. For each capability of that name supported by the provider it -will call the callback I and supply a set of Bs describing the +will call the callback I and supply a set of Ls describing the capability. It will also pass back the argument I. For more details about capabilities and what they can be used for please see L. @@ -173,7 +172,7 @@ OSSL_PROVIDER_available() returns 1 if the named provider is available, otherwise 0. OSSL_PROVIDER_gettable_params() returns a pointer to an array -of constant B, or NULL if none is provided. +of constant L, or NULL if none is provided. OSSL_PROVIDER_get_params() and returns 1 on success, or 0 on error. diff --git a/doc/man3/OSSL_SELF_TEST_new.pod b/doc/man3/OSSL_SELF_TEST_new.pod index 744c82e204fea..5fe838351908b 100644 --- a/doc/man3/OSSL_SELF_TEST_new.pod +++ b/doc/man3/OSSL_SELF_TEST_new.pod @@ -36,7 +36,7 @@ OSSL_SELF_TEST_free() frees the space allocated by OSSL_SELF_TEST_new(). OSSL_SELF_TEST_onbegin() may be inserted at the start of a block of self test code. It can be used for diagnostic purposes. If this method is called the callback I will receive the following -B object. +L object. =over 4 @@ -53,7 +53,7 @@ otherwise it leaves the array unaltered. It can be used for failure testing. The I and I can be used to identify an individual self test to target for failure testing. If this method is called the callback I will receive the following -B object. +L object. =over 4 @@ -67,7 +67,7 @@ OSSL_SELF_TEST_onend() may be inserted at the end of a block of self test code just before cleanup to indicate if the test passed or failed. It can be used for diagnostic purposes. If this method is called the callback I will receive the following -B object. +L object. =over 4 @@ -82,7 +82,7 @@ After the callback I has been called the values that were set by OSSL_SELF_TEST_onbegin() for I and I are set to the value "None". If OSSL_SELF_TEST_onbegin(), OSSL_SELF_TEST_oncorrupt_byte() or -OSSL_SELF_TEST_onend() is called the following additional B are +OSSL_SELF_TEST_onend() is called the following additional L are passed to the callback. =over 4 diff --git a/doc/man3/OSSL_SELF_TEST_set_callback.pod b/doc/man3/OSSL_SELF_TEST_set_callback.pod index ed4f261fdc488..9866de0184941 100644 --- a/doc/man3/OSSL_SELF_TEST_set_callback.pod +++ b/doc/man3/OSSL_SELF_TEST_set_callback.pod @@ -16,7 +16,7 @@ OSSL_SELF_TEST_get_callback - specify a callback for processing self tests Set or gets the optional application callback (and the callback argument) that is called during self testing. -The application callback B is associated with a B. +The application callback L is associated with a B. The application callback function receives information about a running self test, and may return a result to the calling self test. See L for further information on the callback. diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod index a3fe7e13eed12..fe51912e84c05 100644 --- a/doc/man3/OSSL_STORE_open.pod +++ b/doc/man3/OSSL_STORE_open.pod @@ -69,7 +69,7 @@ B with all necessary internal information. The given I and I will be reused by all functions that use B when interaction is needed, for instance to provide a password. -The auxiliary B parameters in I can be set to further +The auxiliary L parameters in I can be set to further modify the store operation. The given I and I will be reused by OSSL_STORE_load() to manipulate or drop the value to be returned. diff --git a/doc/man7/crypto.pod b/doc/man7/crypto.pod index e114fb226e8e5..bcbb170007869 100644 --- a/doc/man7/crypto.pod +++ b/doc/man7/crypto.pod @@ -367,7 +367,7 @@ Most of these follow a common pattern. A "context" object is first created. For example for a digest operation you would use an B, and for an encryption/decryption operation you would use an B. The operation is then initialised ready for use via an "init" function - optionally -passing in a set of parameters (using the B type) to configure how +passing in a set of parameters (using the L type) to configure how the operation should behave. Next data is fed into the operation in a series of "update" calls. The operation is finalised using a "final" call which will typically provide some kind of output. Finally the context is cleaned up and diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod index 64901b6388240..d8c9b98107ba4 100644 --- a/doc/man7/migration_guide.pod +++ b/doc/man7/migration_guide.pod @@ -957,7 +957,7 @@ See also L. Implicit and Explicit Fetching is described in detail here L. -=head3 Mapping EVP controls and flags to provider B parameters +=head3 Mapping EVP controls and flags to provider L parameters The existing functions for controls (such as L) and manipulating flags (such as L)internally use @@ -1459,7 +1459,7 @@ See L. ECDH_KDF_X9_62() Applications may either set this using the helper function -L or by setting an B using the +L or by setting an L using the "kdf-type" as shown in L =item * diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod index 3d1eca3e649ab..568bf397b4a7b 100644 --- a/doc/man7/openssl-core.h.pod +++ b/doc/man7/openssl-core.h.pod @@ -20,95 +20,17 @@ The types are: =over 4 -=item B +=item L -This type is a tuple of function identity and function pointer. -Arrays of this type are passed between the OpenSSL libraries and the -providers to describe what functionality one side provides to the -other. -Arrays of this type must be terminated with a tuple having function -identity zero and function pointer NULL. +=item L -The available function identities and corresponding function -signatures are defined in L. +=item L -Any function identity not recognised by the recipient of this type -will be ignored. -This ensures that providers built with one OpenSSL version in mind -will work together with any other OpenSSL version that supports this -mechanism. +=item L -=item B +=item L -This type is a tuple of integer and pointer. -It's a generic type used as a generic descriptor, its exact meaning -being defined by how it's used. -Arrays of this type are passed between the OpenSSL libraries and the -providers, and must be terminated with a tuple where the integer is -zero and the pointer NULL. - -=item B - -This type is a tuple of an algorithm name (string), a property -definition (string) and a dispatch table (array of B). -Arrays of this type are passed on demand from the providers to the -OpenSSL libraries to describe what algorithms the providers provide -implementations of, and with what properties. -Arrays of this type must be terminated with a tuple having function -identity zero and function pointer NULL. - -The algorithm names and property definitions are defined by the -providers. - -The OpenSSL libraries use the first of the algorithm names as the main -or canonical name, on a per algorithm implementation basis. - -=item B - -This type is a structure that allows passing arbitrary object data -between two parties that have no or very little shared knowledge about -their respective internal structures for that object. -It's normally passed in arrays, where the array is terminated with an -element where all fields are zero (for non-pointers) or NULL (for -pointers). - -These arrays can be used to set parameters for some object, to request -parameters, and to describe parameters. - -B is further described in L - -=item B - -This is a function type for a generic feedback callback function: - - typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); - -A function that takes a pointer of this type should also take a -pointer to caller data. When calling this callback, the function is -expected to build an B array of data it wants or is -expected to pass back, and pass that as I, as well as -the caller data pointer it received, as I. - -=item B - -This is a function type for a generic pass phrase callback function: - - typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, - size_t *pass_len, - const OSSL_PARAM params[], - void *arg); - -This callback can be used to prompt the user for a passphrase. When -calling it, a buffer to store the pass phrase needs to be given with -I, and its size with I. The length of the prompted -pass phrase will be given back in I<*pass_len>. - -Additional parameters can be passed with the B array -I. - -A function that takes a pointer of this type should also take a -pointer to caller data, which should be passed as I to this -callback. +=item L =back diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod index e14a1d90199b8..ac3f6271969de 100644 --- a/doc/man7/provider-asym_cipher.pod +++ b/doc/man7/provider-asym_cipher.pod @@ -54,14 +54,14 @@ L and other related functions). All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_asym_cipher_newctx() has these: @@ -69,7 +69,7 @@ For example, the "function" OSSL_FUNC_asym_cipher_newctx() has these: static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn OSSL_FUNC_asym_cipher_newctx(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_asym_cipher_newctx OSSL_FUNC_ASYM_CIPHER_NEWCTX @@ -238,10 +238,9 @@ The negotiated TLS protocol version. =back OSSL_FUNC_asym_cipher_gettable_ctx_params() and OSSL_FUNC_asym_cipher_settable_ctx_params() -get a constant B array that describes the gettable and settable +get a constant L array that describes the gettable and settable parameters, i.e. parameters that can be used with OSSL_FUNC_asym_cipherget_ctx_params() and OSSL_FUNC_asym_cipher_set_ctx_params() respectively. -See L for the use of B as parameter descriptor. =head1 RETURN VALUES diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index af8baf6dc96ba..30b460cb29158 100644 --- a/doc/man7/provider-base.pod +++ b/doc/man7/provider-base.pod @@ -116,13 +116,13 @@ provider-base =head1 DESCRIPTION All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays, in the call +F and the provider in L arrays, in the call of the provider initialization function. See L for a description of the initialization function. They are known as "upcalls". All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from a B element named +function pointer from a L element named B. For example, the "function" core_gettable_params() has these: @@ -131,10 +131,10 @@ For example, the "function" core_gettable_params() has these: static ossl_inline OSSL_NAME_core_gettable_params_fn OSSL_FUNC_core_gettable_params(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: -For I (the B array passed from F to the +For I (the L array passed from F to the provider): core_gettable_params OSSL_FUNC_CORE_GETTABLE_PARAMS @@ -182,7 +182,7 @@ provider): provider_up_ref OSSL_FUNC_PROVIDER_UP_REF provider_free OSSL_FUNC_PROVIDER_FREE -For I<*out> (the B array passed from the provider to +For I<*out> (the L array passed from the provider to F): provider_teardown OSSL_FUNC_PROVIDER_TEARDOWN @@ -197,7 +197,7 @@ F): =head2 Core functions core_gettable_params() returns a constant array of descriptor -B, for parameters that core_get_params() can handle. +L, for parameters that core_get_params() can handle. core_get_params() retrieves parameters from the core for the given I. See L below for a description of currently known @@ -288,7 +288,7 @@ BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_write_ex(), BIO_up_ref(), BIO_free(), BIO_vprintf(), BIO_vsnprintf(), BIO_gets(), BIO_puts(), BIO_ctrl(), OPENSSL_cleanse() and OPENSSL_hexstr2buf() correspond exactly to the public functions with -the same name. As a matter of fact, the pointers in the B +the same name. As a matter of fact, the pointers in the L array are typically direct pointers to those public functions. Note that the BIO functions take an B type rather than the standard B type. This is to ensure that a provider does not mix BIOs from the core @@ -370,13 +370,13 @@ from the core's provider store. It must free the passed I. provider_gettable_params() should return a constant array of -descriptor B, for parameters that provider_get_params() +descriptor L, for parameters that provider_get_params() can handle. -provider_get_params() should process the B array +provider_get_params() should process the L array I, setting the values of the parameters it understands. -provider_query_operation() should return a constant B +provider_query_operation() should return a constant L that corresponds to the given I. It should indicate if the core may store a reference to this array by setting I<*no_store> to 0 (core may store a reference) or 1 (core may @@ -387,13 +387,13 @@ provider_query_operation() is no longer directly required and that the function pointers have been copied. The I should match that passed to provider_query_operation() and I should be its return value. -provider_get_reason_strings() should return a constant B +provider_get_reason_strings() should return a constant L array that provides reason strings for reason codes the provider may use when reporting errors using core_put_error(). The provider_get_capabilities() function should call the callback I passing -it a set of Bs and the caller supplied argument I. The -Bs should provide details about the capability with the name given +it a set of Ls and the caller supplied argument I. The +Ls should provide details about the capability with the name given in the I argument relevant for the provider context I. If a provider supports multiple capabilities with the given name then it may call the callback multiple times (one for each capability). Capabilities can be useful for diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index b5bbb1b91d083..429a4173d68ea 100644 --- a/doc/man7/provider-cipher.pod +++ b/doc/man7/provider-cipher.pod @@ -63,14 +63,14 @@ L and L (as well as the decrypt equivalents and other related functions). All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_cipher_newctx() has these: @@ -78,7 +78,7 @@ For example, the "function" OSSL_FUNC_cipher_newctx() has these: static ossl_inline OSSL_FUNC_cipher_newctx_fn OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX @@ -193,7 +193,7 @@ the given provider side cipher context I and stores them in I. Passing NULL for I should return true. OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params(), -and OSSL_FUNC_cipher_settable_ctx_params() all return constant B +and OSSL_FUNC_cipher_settable_ctx_params() all return constant L arrays as descriptors of the parameters that OSSL_FUNC_cipher_get_params(), OSSL_FUNC_cipher_get_ctx_params(), and OSSL_FUNC_cipher_set_ctx_params() can handle, respectively. OSSL_FUNC_cipher_gettable_ctx_params() and @@ -217,7 +217,7 @@ OSSL_FUNC_cipher_get_ctx_params() and OSSL_FUNC_cipher_set_ctx_params() should r success or 0 on error. OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params() and -OSSL_FUNC_cipher_settable_ctx_params() should return a constant B +OSSL_FUNC_cipher_settable_ctx_params() should return a constant L array, or NULL if none is offered. =head1 SEE ALSO diff --git a/doc/man7/provider-decoder.pod b/doc/man7/provider-decoder.pod index 2ac56cf1d125c..f279955a6088c 100644 --- a/doc/man7/provider-decoder.pod +++ b/doc/man7/provider-decoder.pod @@ -50,7 +50,7 @@ object reference or intermediate decoded data from an encoded form read from the given B. If the caller wants to decode data from memory, it should provide a L B. The decoded data or object reference is passed along with eventual metadata -to the I as B parameters. +to the I as L parameters. The decoder doesn't need to know more about the B pointer than being able to pass it to the appropriate BIO upcalls (see @@ -67,14 +67,14 @@ that object into a different provider the OSSL_FUNC_decoder_export_object() can be called as the final step of the decoding process. All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_decoder_decode() has these: @@ -86,7 +86,7 @@ For example, the "function" OSSL_FUNC_decoder_decode() has these: static ossl_inline OSSL_FUNC_decoder_decode_fn OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_decoder_get_params OSSL_FUNC_DECODER_GET_PARAMS @@ -202,7 +202,7 @@ from I that it recognises. Unrecognised parameters should be ignored. Passing NULL for I should return true. -OSSL_FUNC_decoder_settable_ctx_params() returns a constant B +OSSL_FUNC_decoder_settable_ctx_params() returns a constant L array describing the parameters that OSSL_FUNC_decoder_set_ctx_params() can handle. @@ -217,18 +217,18 @@ exporting the object into that foreign provider if the foreign provider supports the type of the object and provides an import function. OSSL_FUNC_decoder_export_object() should export the object of size I -referenced by I as an B array and pass that into the +referenced by I as an L array and pass that into the I as well as the given I. =head2 Decoding functions OSSL_FUNC_decoder_decode() should decode the data as read from the B I to produce decoded data or an object to be -passed as reference in an B array along with possible other -metadata that was decoded from the input. This B array is +passed as reference in an L array along with possible other +metadata that was decoded from the input. This L array is then passed to the I callback. The I bits, if relevant, should determine what the input data should contain. -The decoding functions also take an B function +The decoding functions also take an L function pointer along with a pointer to application data I, which should be used when a pass phrase prompt is needed. @@ -284,7 +284,7 @@ OSSL_FUNC_decoder_set_ctx_params() returns 1, unless a recognised parameter was invalid or caused an error, for which 0 is returned. OSSL_FUNC_decoder_settable_ctx_params() returns a pointer to an array of -constant B elements. +constant L elements. OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation supports any of the I bits, otherwise 0. diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index 4c90561e31645..a3d79a48b3b10 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -55,14 +55,14 @@ them available to applications via the API functions L, L and L (and other related functions). All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_digest_newctx() has these: @@ -70,7 +70,7 @@ For example, the "function" OSSL_FUNC_digest_newctx() has these: static ossl_inline OSSL_FUNC_digest_newctx_fn OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_digest_newctx OSSL_FUNC_DIGEST_NEWCTX @@ -158,13 +158,13 @@ OSSL_FUNC_digest_get_ctx_params() gets digest operation details details from the given provider side digest context I and stores them in I. Passing NULL for I should return true. -OSSL_FUNC_digest_gettable_params() returns a constant B array +OSSL_FUNC_digest_gettable_params() returns a constant L array containing descriptors of the parameters that OSSL_FUNC_digest_get_params() can handle. OSSL_FUNC_digest_gettable_ctx_params() and OSSL_FUNC_digest_settable_ctx_params() both return constant -B arrays as descriptors of the parameters that +L arrays as descriptors of the parameters that OSSL_FUNC_digest_get_ctx_params() and OSSL_FUNC_digest_set_ctx_params() can handle, respectively. The array is based on the current state of the provider side context if I is not NULL and on the provider diff --git a/doc/man7/provider-encoder.pod b/doc/man7/provider-encoder.pod index 274f1456ec9e2..f3e9ce5b16327 100644 --- a/doc/man7/provider-encoder.pod +++ b/doc/man7/provider-encoder.pod @@ -83,14 +83,14 @@ with provider data coming from the same provider, for example keys with the L provider. All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_encoder_encode() has these: @@ -103,7 +103,7 @@ For example, the "function" OSSL_FUNC_encoder_encode() has these: static ossl_inline OSSL_FUNC_encoder_encode_fn OSSL_FUNC_encoder_encode(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_encoder_get_params OSSL_FUNC_ENCODER_GET_PARAMS @@ -213,7 +213,7 @@ from I that it recognises. Unrecognised parameters should be ignored. Passing NULL for I should return true. -OSSL_FUNC_encoder_settable_ctx_params() returns a constant B +OSSL_FUNC_encoder_settable_ctx_params() returns a constant L array describing the parameters that OSSL_FUNC_encoder_set_ctx_params() can handle. @@ -242,7 +242,7 @@ OSSL_FUNC_encoder_encode() should take a provider-native object (in I) or an object abstraction (in I), and should output the object in encoded form to the B. The I bits, if relevant, should determine in greater detail what will be output. -The encoding functions also take an B function +The encoding functions also take an L function pointer along with a pointer to application data I, which should be used when a pass phrase prompt is needed. @@ -304,7 +304,7 @@ OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised parameter was invalid or caused an error, for which 0 is returned. OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of -constant B elements. +constant L elements. OSSL_FUNC_encoder_does_selection() returns 1 if the encoder implementation supports any of the I bits, otherwise 0. diff --git a/doc/man7/provider-kdf.pod b/doc/man7/provider-kdf.pod index 58337bf3db1fe..4221f9a0f401c 100644 --- a/doc/man7/provider-kdf.pod +++ b/doc/man7/provider-kdf.pod @@ -47,14 +47,14 @@ them available to applications via the API functions L, and L. All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_kdf_newctx() has these: @@ -62,7 +62,7 @@ For example, the "function" OSSL_FUNC_kdf_newctx() has these: static ossl_inline OSSL_FUNC_kdf_newctx_fn OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf); -B array entries are identified by numbers that are provided as +L array entries are identified by numbers that are provided as macros in L, as follows: OSSL_FUNC_kdf_newctx OSSL_FUNC_KDF_NEWCTX @@ -134,7 +134,7 @@ with the given provider side KDF context I and stores them in I. Passing NULL for I should return true. OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params(), -and OSSL_FUNC_kdf_settable_ctx_params() all return constant B +and OSSL_FUNC_kdf_settable_ctx_params() all return constant L arrays as descriptors of the parameters that OSSL_FUNC_kdf_get_params(), OSSL_FUNC_kdf_get_ctx_params(), and OSSL_FUNC_kdf_set_ctx_params() can handle, respectively. OSSL_FUNC_kdf_gettable_ctx_params() and @@ -330,7 +330,7 @@ OSSL_FUNC_kdf_get_ctx_params() and OSSL_FUNC_kdf_set_ctx_params() should return success or 0 on error. OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params() and -OSSL_FUNC_kdf_settable_ctx_params() should return a constant B +OSSL_FUNC_kdf_settable_ctx_params() should return a constant L array, or NULL if none is offered. =head1 NOTES diff --git a/doc/man7/provider-kem.pod b/doc/man7/provider-kem.pod index 938a25b7e8eb1..a76466ada90dc 100644 --- a/doc/man7/provider-kem.pod +++ b/doc/man7/provider-kem.pod @@ -56,14 +56,14 @@ via the API functions L, L and other related functions. All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_kem_newctx() has these: @@ -71,7 +71,7 @@ For example, the "function" OSSL_FUNC_kem_newctx() has these: static ossl_inline OSSL_FUNC_kem_newctx_fn OSSL_FUNC_kem_newctx(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_kem_newctx OSSL_FUNC_KEM_NEWCTX @@ -199,10 +199,9 @@ Passing NULL for I should return true. No parameters are currently recognised by built-in asymmetric kem algorithms. OSSL_FUNC_kem_gettable_ctx_params() and OSSL_FUNC_kem_settable_ctx_params() -get a constant B array that describes the gettable and settable +get a constant L array that describes the gettable and settable parameters, i.e. parameters that can be used with OSSL_FUNC_kem_get_ctx_params() and OSSL_FUNC_kem_set_ctx_params() respectively. -See L for the use of B as parameter descriptor. =head1 RETURN VALUES diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index 48d27988f5394..9e146d31c719b 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -48,14 +48,14 @@ L and other related functions). All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_keyexch_newctx() has these: @@ -63,7 +63,7 @@ For example, the "function" OSSL_FUNC_keyexch_newctx() has these: static ossl_inline OSSL_FUNC_keyexch_newctx_fn OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_keyexch_newctx OSSL_FUNC_KEYEXCH_NEWCTX @@ -146,17 +146,16 @@ given provider side key exchange context I into I, see L. Passing NULL for I should return true. -OSSL_FUNC_keyexch_settable_ctx_params() yields a constant B array that +OSSL_FUNC_keyexch_settable_ctx_params() yields a constant L array that describes the settable parameters, i.e. parameters that can be used with OP_signature_set_ctx_params(). If OSSL_FUNC_keyexch_settable_ctx_params() is present, OSSL_FUNC_keyexch_set_ctx_params() must also be present, and vice versa. -Similarly, OSSL_FUNC_keyexch_gettable_ctx_params() yields a constant B +Similarly, OSSL_FUNC_keyexch_gettable_ctx_params() yields a constant L array that describes the gettable parameters, i.e. parameters that can be handled by OP_signature_get_ctx_params(). If OSSL_FUNC_keyexch_gettable_ctx_params() is present, OSSL_FUNC_keyexch_get_ctx_params() must also be present, and vice versa. -See L for the use of B as parameter descriptor. Notice that not all settable parameters are also gettable, and vice versa. @@ -217,7 +216,7 @@ OSSL_FUNC_keyexch_set_params(), and OSSL_FUNC_keyexch_get_params() should return or 0 on error. OSSL_FUNC_keyexch_settable_ctx_params() and OSSL_FUNC_keyexch_gettable_ctx_params() should -always return a constant B array. +always return a constant L array. =head1 SEE ALSO diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod index 17d8d4b3380ad..74516f44d1faf 100644 --- a/doc/man7/provider-keymgmt.pod +++ b/doc/man7/provider-keymgmt.pod @@ -72,14 +72,14 @@ The primary responsibility of the KEYMGMT operation is to hold the provider side key data for the OpenSSL library EVP_PKEY structure. All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from a B element named +function pointer from a L element named B. For example, the "function" OSSL_FUNC_keymgmt_new() has these: @@ -87,7 +87,7 @@ For example, the "function" OSSL_FUNC_keymgmt_new() has these: static ossl_inline OSSL_FUNC_keymgmt_new_fn OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_keymgmt_new OSSL_FUNC_KEYMGMT_NEW @@ -236,7 +236,7 @@ OSSL_FUNC_keymgmt_gen_set_params() should set additional parameters from I in the key object generation context I. OSSL_FUNC_keymgmt_gen_settable_params() should return a constant array of -descriptor B, for parameters that OSSL_FUNC_keymgmt_gen_set_params() +descriptor L, for parameters that OSSL_FUNC_keymgmt_gen_set_params() can handle. OSSL_FUNC_keymgmt_gen() should perform the key object generation itself, and @@ -264,7 +264,7 @@ OSSL_FUNC_keymgmt_get_params() should extract information data associated with the given I, see L. OSSL_FUNC_keymgmt_gettable_params() should return a constant array of -descriptor B, for parameters that OSSL_FUNC_keymgmt_get_params() +descriptor L, for parameters that OSSL_FUNC_keymgmt_get_params() can handle. If OSSL_FUNC_keymgmt_gettable_params() is present, OSSL_FUNC_keymgmt_get_params() @@ -274,7 +274,7 @@ OSSL_FUNC_keymgmt_set_params() should update information data associated with the given I, see L. OSSL_FUNC_keymgmt_settable_params() should return a constant array of -descriptor B, for parameters that OSSL_FUNC_keymgmt_set_params() +descriptor L, for parameters that OSSL_FUNC_keymgmt_set_params() can handle. If OSSL_FUNC_keymgmt_settable_params() is present, OSSL_FUNC_keymgmt_set_params() @@ -323,18 +323,18 @@ by the implementation of this function. =head2 Key Object Import, Export and Duplication Functions OSSL_FUNC_keymgmt_import() should import data indicated by I into -I with values taken from the B array I. +I with values taken from the L array I. OSSL_FUNC_keymgmt_export() should extract values indicated by I -from I, create an B array with them and call +from I, create an L array with them and call I with that array as well as the given I. OSSL_FUNC_keymgmt_import_types() should return a constant array of descriptor -B for data indicated by I, for parameters that +L for data indicated by I, for parameters that OSSL_FUNC_keymgmt_import() can handle. OSSL_FUNC_keymgmt_export_types() should return a constant array of descriptor -B for data indicated by I, that the +L for data indicated by I, that the OSSL_FUNC_keymgmt_export() callback can expect to receive. OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by @@ -397,7 +397,7 @@ applies. OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params() OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_export_types() should -always return a constant B array. +always return a constant L array. =head1 SEE ALSO diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod index 5a1659121eba9..6d7bd46d299e9 100644 --- a/doc/man7/provider-mac.pod +++ b/doc/man7/provider-mac.pod @@ -48,14 +48,14 @@ them available to applications via the API functions L, L and L. All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_mac_newctx() has these: @@ -63,7 +63,7 @@ For example, the "function" OSSL_FUNC_mac_newctx() has these: static ossl_inline OSSL_FUNC_mac_newctx_fn OSSL_FUNC_mac_newctx(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_mac_newctx OSSL_FUNC_MAC_NEWCTX @@ -145,7 +145,7 @@ in I. Passing NULL for I should return true. OSSL_FUNC_mac_gettable_params(), OSSL_FUNC_mac_gettable_ctx_params(), -and OSSL_FUNC_mac_settable_ctx_params() all return constant B +and OSSL_FUNC_mac_settable_ctx_params() all return constant L arrays as descriptors of the parameters that OSSL_FUNC_mac_get_params(), OSSL_FUNC_mac_get_ctx_params(), and OSSL_FUNC_mac_set_ctx_params() can handle, respectively. OSSL_FUNC_mac_gettable_ctx_params() and @@ -209,7 +209,7 @@ OSSL_FUNC_mac_get_ctx_params() and OSSL_FUNC_mac_set_ctx_params() should return success or 0 on error. OSSL_FUNC_mac_gettable_params(), OSSL_FUNC_mac_gettable_ctx_params() and -OSSL_FUNC_mac_settable_ctx_params() should return a constant B +OSSL_FUNC_mac_settable_ctx_params() should return a constant L array, or NULL if none is offered. =head1 SEE ALSO diff --git a/doc/man7/provider-rand.pod b/doc/man7/provider-rand.pod index 951f483b60ab0..e115d845dcd90 100644 --- a/doc/man7/provider-rand.pod +++ b/doc/man7/provider-rand.pod @@ -168,7 +168,7 @@ in I. Passing NULL for I should return true. OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params(), -and OSSL_FUNC_rand_settable_ctx_params() all return constant B +and OSSL_FUNC_rand_settable_ctx_params() all return constant L arrays as descriptors of the parameters that OSSL_FUNC_rand_get_params(), OSSL_FUNC_rand_get_ctx_params(), and OSSL_FUNC_rand_set_ctx_params() can handle, respectively. OSSL_FUNC_rand_gettable_ctx_params() @@ -262,7 +262,7 @@ OSSL_FUNC_rand_newctx() should return the newly created provider side rand context, or NULL on failure. OSSL_FUNC_rand_gettable_params(), OSSL_FUNC_rand_gettable_ctx_params() and -OSSL_FUNC_rand_settable_ctx_params() should return a constant B +OSSL_FUNC_rand_settable_ctx_params() should return a constant L array, or NULL if none is offered. OSSL_FUNC_rand_nonce() returns the size of the generated nonce, or 0 on error. diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index d77979cd8e165..022b52ae14a30 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -93,14 +93,14 @@ and L (as well as other related functions). All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the -function pointer from an B element named +function pointer from an L element named B. For example, the "function" OSSL_FUNC_signature_newctx() has these: @@ -108,7 +108,7 @@ For example, the "function" OSSL_FUNC_signature_newctx() has these: static ossl_inline OSSL_FUNC_signature_newctx_fn OSSL_FUNC_signature_newctx(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_signature_newctx OSSL_FUNC_SIGNATURE_NEWCTX @@ -388,10 +388,9 @@ supply known values that either pass or fail. =back OSSL_FUNC_signature_gettable_ctx_params() and OSSL_FUNC_signature_settable_ctx_params() get a -constant B array that describes the gettable and settable parameters, +constant L array that describes the gettable and settable parameters, i.e. parameters that can be used with OSSL_FUNC_signature_get_ctx_params() and OSSL_FUNC_signature_set_ctx_params() respectively. -See L for the use of B as parameter descriptor. =head2 MD parameters @@ -413,11 +412,10 @@ as those for built-in digest algorithms. See L for further information. OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params() -get a constant B array that describes the gettable and settable +get a constant L array that describes the gettable and settable digest parameters, i.e. parameters that can be used with OSSL_FUNC_signature_get_md_ctx_params() and OSSL_FUNC_signature_set_md_ctx_params() -respectively. See L for the use of B as parameter -descriptor. +respectively. =head1 RETURN VALUES @@ -426,7 +424,7 @@ provider side signature, or NULL on failure. OSSL_FUNC_signature_gettable_ctx_params(), OSSL_FUNC_signature_settable_ctx_params(), OSSL_FUNC_signature_gettable_md_ctx_params() and OSSL_FUNC_signature_settable_md_ctx_params(), -return the gettable or settable parameters in a constant B array. +return the gettable or settable parameters in a constant L array. All other functions should return 1 for success or 0 on error. diff --git a/doc/man7/provider-storemgmt.pod b/doc/man7/provider-storemgmt.pod index 611f24930c0ad..615ff7ef8e552 100644 --- a/doc/man7/provider-storemgmt.pod +++ b/doc/man7/provider-storemgmt.pod @@ -44,14 +44,14 @@ OSSL_FUNC_store_export_object() (which exports the object in parameterized form). All "functions" mentioned here are passed as function pointers between -F and the provider in B arrays via -B arrays that are returned by the provider's +F and the provider in L arrays via +L arrays that are returned by the provider's provider_query_operation() function (see L). All these "functions" have a corresponding function type definition named B, and a helper function to retrieve the function pointer -from a B element named B. +from a L element named B. For example, the "function" OSSL_FUNC_store_attach() has these: typedef void *(OSSL_FUNC_store_attach_fn)(void *provctx, @@ -59,7 +59,7 @@ For example, the "function" OSSL_FUNC_store_attach() has these: static ossl_inline OSSL_FUNC_store_attach_fn OSSL_FUNC_store_attach(const OSSL_DISPATCH *opf); -B arrays are indexed by numbers that are provided as macros +L arrays are indexed by numbers that are provided as macros in L, as follows: OSSL_FUNC_store_open OSSL_FUNC_STORE_OPEN @@ -82,7 +82,7 @@ B I attached. This is an alternative to using a URI to find storage, supporting L. OSSL_FUNC_store_settable_ctx_params() should return a constant array of -descriptor B, for parameters that OSSL_FUNC_store_set_ctx_params() +descriptor L, for parameters that OSSL_FUNC_store_set_ctx_params() can handle. OSSL_FUNC_store_set_ctx_params() should set additional parameters, such as what @@ -111,7 +111,7 @@ exporting the object to that foreign provider if the foreign provider supports the type of the object and provides an import function. OSSL_FUNC_store_export_object() should export the object of size I -referenced by I as an B array and pass that to the +referenced by I as an L array and pass that to the I as well as the given I. =head2 Load Parameters diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index fb092931c92db..a061fc4709d0b 100644 --- a/doc/man7/provider.pod +++ b/doc/man7/provider.pod @@ -34,8 +34,8 @@ See L for further details. =head2 Provider A I offers an initialization function, as a set of base -functions in the form of an B array, and by extension, -a set of Bs (see L). +functions in the form of an L array, and by extension, +a set of Ls (see L). It may be a dynamically loadable module, or may be built-in, in OpenSSL libraries or in the application. If it's a dynamically loadable module, the initialization function @@ -92,7 +92,7 @@ nonzero, signifies that the OpenSSL libraries will not store a reference to the returned data in their internal store of implementations. -The returned B is the foundation of any OpenSSL +The returned L is the foundation of any OpenSSL library API that uses providers for their implementation, most commonly in the I type of functions (see L). diff --git a/util/other.syms b/util/other.syms index a35f6fd54a3fd..94bc79e9eec99 100644 --- a/util/other.syms +++ b/util/other.syms @@ -53,23 +53,28 @@ EVP_RAND datatype EVP_RAND_CTX datatype EVP_SIGNATURE datatype GEN_SESSION_CB datatype -OPENSSL_Applink external -OSSL_LIB_CTX datatype NAMING_AUTHORITY datatype +OPENSSL_Applink external +OSSL_ALGORITHM datatype +OSSL_CALLBACK datatype OSSL_DECODER datatype OSSL_DECODER_CTX datatype OSSL_DECODER_CONSTRUCT datatype OSSL_DECODER_CLEANUP datatype OSSL_DECODER_INSTANCE datatype -OSSL_HTTP_bio_cb_t datatype -OSSL_PARAM datatype -OSSL_PROVIDER datatype +OSSL_DISPATCH datatype OSSL_ENCODER datatype OSSL_ENCODER_CTX datatype OSSL_ENCODER_CONSTRUCT datatype OSSL_ENCODER_CLEANUP datatype OSSL_ENCODER_INSTANCE datatype +OSSL_HTTP_bio_cb_t datatype OSSL_HTTP_REQ_CTX datatype +OSSL_ITEM datatype +OSSL_LIB_CTX datatype +OSSL_PARAM datatype +OSSL_PASSPHRASE_CALLBACK datatype +OSSL_PROVIDER datatype OSSL_STORE_CTX datatype OSSL_STORE_INFO datatype OSSL_STORE_LOADER datatype