From 318a9dfa5f7bd1237d2697ad950697d241b8b49f Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Mon, 5 Dec 2022 16:59:06 +0100 Subject: [PATCH] Replace some boldened types with a corresponding man page link The types OSSL_DISPATCH, OSSL_ITEM, OSSL_ALGORITHM, OSSL_PARAM, OSSL_CALLBACK, and OSSL_PASSPHRASE_CALLBACK are described in their own manual page, so we change every mention of them to links to those pages. Reviewed-by: Hugo Landau Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/19842) --- doc/internal/man3/ossl_provider_new.pod | 2 +- doc/man3/EVP_ASYM_CIPHER_free.pod | 4 +-- doc/man3/EVP_DigestInit.pod | 17 +++++------ doc/man3/EVP_EncryptInit.pod | 19 +++++------- doc/man3/EVP_KDF.pod | 11 +++---- doc/man3/EVP_KEM_free.pod | 4 +-- doc/man3/EVP_KEYEXCH_free.pod | 4 +-- doc/man3/EVP_KEYMGMT.pod | 7 ++--- doc/man3/EVP_MAC.pod | 11 +++---- doc/man3/EVP_PKEY_CTX_set_params.pod | 3 +- doc/man3/EVP_PKEY_fromdata.pod | 3 +- doc/man3/EVP_PKEY_gettable_params.pod | 6 ++-- doc/man3/EVP_PKEY_todata.pod | 4 +-- doc/man3/EVP_RAND.pod | 15 ++++------ doc/man3/EVP_SIGNATURE.pod | 4 +-- doc/man3/OSSL_CALLBACK.pod | 4 +-- doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod | 4 +-- doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod | 2 +- doc/man3/OSSL_PARAM_allocate_from_text.pod | 2 +- doc/man3/OSSL_PARAM_dup.pod | 6 ++-- doc/man3/OSSL_PARAM_int.pod | 34 +++++++++++----------- doc/man3/OSSL_PROVIDER.pod | 9 +++--- doc/man3/OSSL_SELF_TEST_new.pod | 8 ++--- doc/man3/OSSL_SELF_TEST_set_callback.pod | 2 +- doc/man3/OSSL_STORE_open.pod | 2 +- doc/man7/crypto.pod | 2 +- doc/man7/migration_guide.pod | 4 +-- doc/man7/provider-asym_cipher.pod | 11 ++++--- doc/man7/provider-base.pod | 26 ++++++++--------- doc/man7/provider-cipher.pod | 12 ++++---- doc/man7/provider-decoder.pod | 22 +++++++------- doc/man7/provider-digest.pod | 12 ++++---- doc/man7/provider-encoder.pod | 14 ++++----- doc/man7/provider-kdf.pod | 12 ++++---- doc/man7/provider-kem.pod | 11 ++++--- doc/man7/provider-keyexch.pod | 15 +++++----- doc/man7/provider-keymgmt.pod | 24 +++++++-------- doc/man7/provider-mac.pod | 12 ++++---- doc/man7/provider-rand.pod | 4 +-- doc/man7/provider-signature.pod | 18 +++++------- doc/man7/provider-storemgmt.pod | 12 ++++---- doc/man7/provider.pod | 6 ++-- 42 files changed, 190 insertions(+), 214 deletions(-) diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod index 6ea298e0a9..e170edf343 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 72910a5599..c158ec1ae7 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 2bbd35f395..183f2e09bd 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 dafa71c9f6..1d5cb6c759 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 a8cc83324e..3b4e2b79aa 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 e77b89d3b9..575abc5f57 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 42c7e1289c..272855ccb3 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 2131694e0b..da03286a99 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 289cbda757..13482ac5e1 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 b8855c2670..c02151654c 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 158d1bf42d..2cdbced9cf 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 ba87289937..8dd0fc543e 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 14db9e6efd..c28a867b7a 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 6aae33b5fd..a187ed6625 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 9fb389e7ae..6005220853 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_CALLBACK.pod b/doc/man3/OSSL_CALLBACK.pod index 2aef06cfd1..5fa8a8f089 100644 --- a/doc/man3/OSSL_CALLBACK.pod +++ b/doc/man3/OSSL_CALLBACK.pod @@ -31,7 +31,7 @@ simply be passed back to the callback function when it's called. =item B This is a generic callback function. When calling this callback function, -the caller is expected to build an B array of data it wants or +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. @@ -43,7 +43,7 @@ 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, +Additional parameters can be passed with the L array I, =back diff --git a/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_DECODER_CTX_new_for_pkey.pod index 26c0f0ae2e..4b4443777a 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_ENCODER_CTX_new_for_pkey.pod b/doc/man3/OSSL_ENCODER_CTX_new_for_pkey.pod index 8f7d1910ca..3bf9c10e37 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_PARAM_allocate_from_text.pod b/doc/man3/OSSL_PARAM_allocate_from_text.pod index 80ba555a8f..e6dc2549fd 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 5130c9e1dc..4ae33faf1e 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 efa94c5d54..ffe7c8c76a 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 cefb4a74c0..bae0bc928e 100644 --- a/doc/man3/OSSL_PROVIDER.pod +++ b/doc/man3/OSSL_PROVIDER.pod @@ -117,11 +117,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. @@ -157,7 +156,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. @@ -183,7 +182,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 744c82e204..5fe8383519 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 ed4f261fdc..9866de0184 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 a3fe7e13ee..fe51912e84 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 e114fb226e..bcbb170007 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 64901b6388..d8c9b98107 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/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod index e14a1d9019..ac3f627196 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 af8baf6dc9..30b460cb29 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 b5bbb1b91d..429a4173d6 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 2ac56cf1d1..f279955a60 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 4c90561e31..a3d79a48b3 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 274f1456ec..f3e9ce5b16 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 58337bf3db..4221f9a0f4 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 938a25b7e8..a76466ada9 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 48d27988f5..9e146d31c7 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 17d8d4b338..74516f44d1 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 5a1659121e..6d7bd46d29 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 951f483b60..e115d845dc 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 d77979cd8e..022b52ae14 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 611f24930c..615ff7ef8e 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 fb092931c9..a061fc4709 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). -- 2.34.1