diff options
31 files changed, 226 insertions, 226 deletions
diff --git a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod index b36084dc46..8afd48ec4d 100644 --- a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod +++ b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod @@ -37,38 +37,38 @@ SPARSE_ARRAY_OF() returns the name for a sparse array of the specified B<TYPE>. DEFINE_STACK_OF() creates set of functions for a sparse array of B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and -each function name begins with I<ossl_sa_TYPE_>. For example: +each function name begins with B<ossl_sa_TYPE_>. For example: TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx); -ossl_sa_TYPE_num() returns the number of elements in B<sa> or 0 if B<sa> is -B<NULL>. +ossl_sa_TYPE_num() returns the number of elements in I<sa> or 0 if I<sa> is +NULL. -ossl_sa_TYPE_get() returns element B<idx> in B<sa>, where B<idx> starts at -zero. If B<idx> refers to a value that has not been set then B<NULL> is +ossl_sa_TYPE_get() returns element I<idx> in I<sa>, where I<idx> starts at +zero. If I<idx> refers to a value that has not been set then NULL is returned. -ossl_sa_TYPE_set() sets element B<idx> in B<sa> to B<value>, where B<idx> +ossl_sa_TYPE_set() sets element I<idx> in I<sa> to I<value>, where I<idx> starts at zero. The sparse array will be resized as required. ossl_sa_TYPE_new() allocates a new empty sparse array. -ossl_sa_TYPE_free() frees up the B<sa> structure. It does B<not> free up any -elements of B<sa>. After this call B<sa> is no longer valid. +ossl_sa_TYPE_free() frees up the I<sa> structure. It does I<not> free up any +elements of I<sa>. After this call I<sa> is no longer valid. -ossl_sa_TYPE_free_leaves() frees up the B<sa> structure and all of its -elements. After this call B<sa> is no longer valid. +ossl_sa_TYPE_free_leaves() frees up the I<sa> structure and all of its +elements. After this call I<sa> is no longer valid. -ossl_sa_TYPE_doall() calls the function B<leaf> for each element in B<sa> +ossl_sa_TYPE_doall() calls the function I<leaf> for each element in I<sa> in ascending index order. The index position, within the sparse array, of each item is passed as the first argument to the leaf function and a pointer to the associated value is is passed as the second argument. -ossl_sa_TYPE_doall_arg() calls the function B<leaf> for each element in -B<sa> in ascending index order. The index position, within the sparse +ossl_sa_TYPE_doall_arg() calls the function I<leaf> for each element in +I<sa> in ascending index order. The index position, within the sparse array, of each item is passed as the first argument to the leaf function, a pointer to the associated value is passed as the second argument and -the third argument is the user supplied B<arg>. +the third argument is the user supplied I<arg>. =head1 NOTES @@ -91,16 +91,16 @@ OPENSSL_SA_num and OPENSSL_SA_set. =head1 RETURN VALUES ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0> -if the passed sparse array is B<NULL>. +if the passed sparse array is NULL. -ossl_sa_TYPE_get() returns a pointer to a sparse array element or B<NULL> if +ossl_sa_TYPE_get() returns a pointer to a sparse array element or NULL if the element has not be set. ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter case, the elements of the sparse array remain unchanged, although the internal structures might have. -ossl_sa_TYPE_new() returns an empty sparse array or B<NULL> if an error +ossl_sa_TYPE_new() returns an empty sparse array or NULL if an error occurs. ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and diff --git a/doc/internal/man3/OSSL_METHOD_STORE.pod b/doc/internal/man3/OSSL_METHOD_STORE.pod index f178a0ee75..2ffe820100 100644 --- a/doc/internal/man3/OSSL_METHOD_STORE.pod +++ b/doc/internal/man3/OSSL_METHOD_STORE.pod @@ -53,52 +53,52 @@ separately (see L</Cache Functions> below). =head2 Store Functions ossl_method_store_init() initialises the method store subsystem in the scope of -the library context B<ctx>. +the library context I<ctx>. ossl_method_store_cleanup() cleans up and shuts down the implementation method -store subsystem in the scope of the library context B<ctx>. +store subsystem in the scope of the library context I<ctx>. ossl_method_store_new() create a new empty method store using the supplied -B<ctx> to allow access to the required underlying property data. +I<ctx> to allow access to the required underlying property data. -ossl_method_store_free() frees resources allocated to B<store>. +ossl_method_store_free() frees resources allocated to I<store>. -ossl_method_store_add() adds the B<method> constructed from an implementation in -the provider B<prov> to the B<store> as an instance of an algorithm indicated by -B<nid> and the property definition B<properties>, unless the B<store> already -has a method from the same provider with the same B<nid> and B<properties>. -If the B<method_up_ref> function is given, it's called to increment the +ossl_method_store_add() adds the I<method> constructed from an implementation in +the provider I<prov> to the I<store> as an instance of an algorithm indicated by +I<nid> and the property definition I<properties>, unless the I<store> already +has a method from the same provider with the same I<nid> and I<properties>. +If the I<method_up_ref> function is given, it's called to increment the reference count of the method. -If the B<method_destruct> function is given, it's called when this function +If the I<method_destruct> function is given, it's called when this function fails to add the method to the store, or later on when it is being released from -the B<store>. +the I<store>. -ossl_method_store_remove() removes the B<method> identified by B<nid> from the -B<store>. +ossl_method_store_remove() removes the I<method> identified by I<nid> from the +I<store>. -ossl_method_store_fetch() queries B<store> for a method identified by B<nid> -that matches the property query B<prop_query>. -The result, if any, is returned in B<method>. +ossl_method_store_fetch() queries I<store> for a method identified by I<nid> +that matches the property query I<prop_query>. +The result, if any, is returned in I<method>. -ossl_method_store_set_global_properties() sets method B<store> wide query -properties to B<prop_query>. +ossl_method_store_set_global_properties() sets method I<store> wide query +properties to I<prop_query>. All subsequent fetches will need to meet both these global query properties and the ones passed to the ossl_method_store_free(). =head2 Cache Functions -ossl_method_store_cache_get() queries the cache associated with the B<store> -for a method identified by B<nid> that matches the property query -B<prop_query>. -The result, if any, is returned in B<method>. +ossl_method_store_cache_get() queries the cache associated with the I<store> +for a method identified by I<nid> that matches the property query +I<prop_query>. +The result, if any, is returned in I<method>. -ossl_method_store_cache_set() sets a cache entry identified by B<nid> with the -property query B<prop_query> in the B<store>. -Future calls to ossl_method_store_cache_get() will return the specified B<method>. +ossl_method_store_cache_set() sets a cache entry identified by I<nid> with the +property query I<prop_query> in the I<store>. +Future calls to ossl_method_store_cache_get() will return the specified I<method>. =head1 RETURN VALUES -ossl_method_store_new() returns a new method store object or B<NULL> on failure. +ossl_method_store_new() returns a new method store object or NULL on failure. ossl_method_store_free(), ossl_method_store_add(), ossl_method_store_remove(), ossl_method_store_fetch(), diff --git a/doc/internal/man3/cms_add1_signing_cert.pod b/doc/internal/man3/cms_add1_signing_cert.pod index a825c07190..ac7f813e84 100644 --- a/doc/internal/man3/cms_add1_signing_cert.pod +++ b/doc/internal/man3/cms_add1_signing_cert.pod @@ -16,10 +16,10 @@ CMS_SignerInfo data structure =head1 DESCRIPTION -cms_add1_signing_cert() adds an ESS Signing Certificate B<sc> (version 1) signed -attribute to the CMS_SignerInfo B<si>. -cms_add1_signing_cert_v2() adds an ESS Signing Certificate B<sc2> (version 2) signed -attribute to the CMS_SignerInfo B<si>. +cms_add1_signing_cert() adds an ESS Signing Certificate I<sc> (version 1) signed +attribute to the CMS_SignerInfo I<si>. +cms_add1_signing_cert_v2() adds an ESS Signing Certificate I<sc2> (version 2) signed +attribute to the CMS_SignerInfo I<si>. The ESS Signing Certificate attributes version 1 and 2 are defined in RFC 5035 which updates Section 5.4 of RFC 2634. diff --git a/doc/internal/man3/evp_generic_fetch.pod b/doc/internal/man3/evp_generic_fetch.pod index 6fe7bccba3..738c501560 100644 --- a/doc/internal/man3/evp_generic_fetch.pod +++ b/doc/internal/man3/evp_generic_fetch.pod @@ -70,7 +70,7 @@ frees the given method. =head1 RETURN VALUES -evp_generic_fetch() returns a method on success, or B<NULL> on error. +evp_generic_fetch() returns a method on success, or NULL on error. =head1 EXAMPLES diff --git a/doc/internal/man3/openssl_ctx_get_data.pod b/doc/internal/man3/openssl_ctx_get_data.pod index 3d821b5fba..11eb1484d7 100644 --- a/doc/internal/man3/openssl_ctx_get_data.pod +++ b/doc/internal/man3/openssl_ctx_get_data.pod @@ -24,8 +24,8 @@ openssl_ctx_get_data, openssl_ctx_run_once, openssl_ctx_onfree =head1 DESCRIPTION -Internally, the OpenSSL library context C<OPENSSL_CTX> is implemented -as a C<CRYPTO_EX_DATA>, which allows data from diverse parts of the +Internally, the OpenSSL library context B<OPENSSL_CTX> is implemented +as a B<CRYPTO_EX_DATA>, which allows data from diverse parts of the library to be added and removed dynamically. Each such data item must have a corresponding CRYPTO_EX_DATA index associated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes @@ -34,8 +34,8 @@ indexes internally to the implementation. See the example further down to see how that's done. openssl_ctx_get_data() is used to retrieve a pointer to the data in -the library context C<ctx> associated with the given C<index>. An -OPENSSL_CTX_METHOD must be defined and given in the C<meth> parameter. The index +the library context I<ctx> associated with the given I<index>. An +OPENSSL_CTX_METHOD must be defined and given in the I<meth> parameter. The index for it should be defined in cryptlib.h. The functions through the method are used to create or free items that are stored at that index whenever a library context is created or freed, meaning that the code that use a data item of that @@ -44,18 +44,18 @@ index doesn't have to worry about that, just use the data available. Deallocation of an index happens automatically when the library context is freed. -openssl_ctx_run_once is used to run some initialisation routine C<run_once_fn> -exactly once per library context C<ctx> object. Each initialisation routine +openssl_ctx_run_once is used to run some initialisation routine I<run_once_fn> +exactly once per library context I<ctx> object. Each initialisation routine should be allocate a unique run once index in cryptlib.h. Any resources allocated via a run once initialisation routine can be cleaned up -using openssl_ctx_onfree. This associates an "on free" routine C<onfreefn> with -the library context C<ctx>. When C<ctx> is freed all associated "on free" +using openssl_ctx_onfree. This associates an "on free" routine I<onfreefn> with +the library context I<ctx>. When I<ctx> is freed all associated "on free" routines are called. =head1 RETURN VALUES -openssl_ctx_get_data() returns a pointer on success, or C<NULL> on +openssl_ctx_get_data() returns a pointer on success, or NULL on failure. =head1 EXAMPLES diff --git a/doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod b/doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod index 647125dc7e..5a9f99f116 100644 --- a/doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod +++ b/doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod @@ -32,14 +32,14 @@ ossl_cmp_build_cert_chain =head1 DESCRIPTION -ossl_cmp_log_parse_metadata() parses the given message buffer C<buf> populated -by L<OSSL_CMP_log()> etc. +ossl_cmp_log_parse_metadata() parses the given message buffer I<buf> populated +by L<OSSL_CMP_log(3)> etc. according to the pattern OSSL_CMP_LOG_START#level ": %s\n", filling in -the variable pointed to by C<level> with the severity level or -1, -the variable pointed to by C<func> with the function name string or NULL, -the variable pointed to by C<file> with the file name string or NULL, and -the variable pointed to by C<line> with the line number or -1. -Any string returned via C<*func> and C<*file> must be freeed by the caller. +the variable pointed to by I<level> with the severity level or -1, +the variable pointed to by I<func> with the function name string or NULL, +the variable pointed to by I<file> with the file name string or NULL, and +the variable pointed to by I<line> with the line number or -1. +Any string returned via I<*func> and I<*file> must be freeed by the caller. ossl_cmp_add_error_txt() appends text to the extra data field of the last error message in the OpenSSL error queue, after adding the optional separator @@ -48,18 +48,18 @@ which is not possible when using L<ERR_add_error_data(3)> in conjunction with L<ERR_print_errors_cb(3)>. ossl_cmp_add_error_data() is a macro calling -B<ossl_cmp_add_error_txt()> with the separator being ":". +ossl_cmp_add_error_txt() with the separator being ":". ossl_cmp_add_error_line() is a macro calling -B<ossl_cmp_add_error_txt()> with the separator being "\n". +ossl_cmp_add_error_txt() with the separator being "\n". ossl_cmp_asn1_octet_string_set1() frees any previous value of the variable -referenced via the C<tgt> argument and assigns either a copy of -the ASN1_OCTET_STRING given as the C<src> argument or C<NULL>. +referenced via the I<tgt> argument and assigns either a copy of +the ASN1_OCTET_STRING given as the I<src> argument or NULL. It returns 1 on success, 0 on error. ossl_cmp_asn1_octet_string_set1_bytes() frees any previous value of the variable -referenced via the C<tgt> argument and assigns either a copy of the given byte +referenced via the I<tgt> argument and assigns either a copy of the given byte string (with the given length) or NULL. It returns 1 on success, 0 on error. ossl_cmp_build_cert_chain() builds up the certificate chain of cert as high up diff --git a/doc/internal/man3/ossl_cmp_sk_X509_add1_cert.pod b/doc/internal/man3/ossl_cmp_sk_X509_add1_cert.pod index 20ba218d0a..cb36855adf 100644 --- a/doc/internal/man3/ossl_cmp_sk_X509_add1_cert.pod +++ b/doc/internal/man3/ossl_cmp_sk_X509_add1_cert.pod @@ -22,18 +22,18 @@ ossl_cmp_X509_STORE_get1_certs =head1 DESCRIPTION -ossl_cmp_sk_X509_add1_cert() appends or prepends (depending on the B<prepend> +ossl_cmp_sk_X509_add1_cert() appends or prepends (depending on the I<prepend> argument) a certificate to the given list, optionally only if it is not already contained. On success the reference count of the certificate is increased. -ossl_cmp_sk_X509_add1_certs() appends or prepends (depending on the B<prepend> +ossl_cmp_sk_X509_add1_certs() appends or prepends (depending on the I<prepend> argument) a list of certificates to the given list, optionally only if not self-signed and optionally only if not already contained. The reference counts of those certificates appended successfully are increased. ossl_cmp_X509_STORE_add1_certs() adds all or only self-signed certificates from -the given stack to given store. The C<certs> parameter may be NULL. +the given stack to given store. The I<certs> parameter may be NULL. ossl_cmp_X509_STORE_get1_certs() retrieves a copy of all certificates in the given store. diff --git a/doc/internal/man3/ossl_init_thread_deregister.pod b/doc/internal/man3/ossl_init_thread_deregister.pod index 4d4c716680..ccfb419731 100644 --- a/doc/internal/man3/ossl_init_thread_deregister.pod +++ b/doc/internal/man3/ossl_init_thread_deregister.pod @@ -33,17 +33,17 @@ stopping the stop handler is called (while on that thread) and the code can clean up the value stored in the thread local variable. A new stop handler is registerd using the function ossl_init_thread_start(). -The B<index> parameter should be a unique value that can be used to identify a +The I<index> parameter should be a unique value that can be used to identify a set of common stop handlers and is passed in a later call to ossl_init_thread_deregister. If no later call to ossl_init_thread_deregister is -made then NULL can be passed for this parameter. The B<arg> parameter is passed +made then NULL can be passed for this parameter. The I<arg> parameter is passed back as an argument to the stop handler when it is later invoked. Finally the -B<handfn> is a function pointer to the stop handler itself. +I<handfn> is a function pointer to the stop handler itself. In the event that previously registered stop handlers need to be deregistered then this can be done using the function ossl_init_thread_deregister(). This will deregister all stop handlers (no matter which thread they were -registered for) which the same B<index> value. +registered for) which the same I<index> value. =head1 RETURN VALUES diff --git a/doc/internal/man3/ossl_method_construct.pod b/doc/internal/man3/ossl_method_construct.pod index a25ca4cd8c..f3d7a64d00 100644 --- a/doc/internal/man3/ossl_method_construct.pod +++ b/doc/internal/man3/ossl_method_construct.pod @@ -90,7 +90,7 @@ Remove a temporary store. Look up an already existing method from a store by name. The store may be given with I<store>. -B<NULL> is a valid value and means that a sub-system default store +NULL is a valid value and means that a sub-system default store must be used. This default store should be stored in the library context I<libctx>. @@ -107,7 +107,7 @@ Places the I<method> created by the construct() function (see below) in a store. The store may be given with I<store>. -B<NULL> is a valid value and means that a sub-system default store +NULL is a valid value and means that a sub-system default store must be used. This default store should be stored in the library context I<libctx>. @@ -141,7 +141,7 @@ the reference count reaches zero. =head1 RETURN VALUES ossl_method_construct() returns a constructed method on success, or -B<NULL> on error. +NULL on error. =head1 HISTORY diff --git a/doc/internal/man3/ossl_param_bld_init.pod b/doc/internal/man3/ossl_param_bld_init.pod index 4acd8ebf8f..2eb838d9a9 100644 --- a/doc/internal/man3/ossl_param_bld_init.pod +++ b/doc/internal/man3/ossl_param_bld_init.pod @@ -55,7 +55,7 @@ can be added. Any existing values are cleared. ossl_param_bld_to_param() converts a built up OSSL_PARAM_BLD structure -B<bld> into an allocated OSSL_PARAM array. +I<bld> into an allocated OSSL_PARAM array. The OSSL_PARAM array and all associated storage must be freed by calling ossl_param_bld_free() with the functions return value. @@ -64,44 +64,44 @@ ossl_param_bld_to_param(). ossl_param_bld_to_param_ex() behaves like ossl_param_bld_to_param(), except that no additional memory is allocated. -An OSSL_PARAM array of at least B<param_n> elements is passed in as B<params>. +An OSSL_PARAM array of at least I<param_n> elements is passed in as I<params>. The auxiliary storage for the parameters is a block of memory pointed to -by B<data> of at least B<data_n> bytes in size. +by I<data> of at least I<data_n> bytes in size. If required, secure memory for private BIGNUMs should be pointed to by -B<secure> of at least B<secure_n> bytes in size. +I<secure> of at least I<secure_n> bytes in size. ossl_param_bld_push_TYPE() are a series of functions which will create -OSSL_PARAM objects of the specified size and correct type for the B<val> +OSSL_PARAM objects of the specified size and correct type for the I<val> argument. -B<val> is stored by value and an expression or auto variable can be used. +I<val> is stored by value and an expression or auto variable can be used. ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object -that holds the specified BIGNUM B<bn>. -If B<bn> is marked as being securely allocated, it's OSSL_PARAM representation +that holds the specified BIGNUM I<bn>. +If I<bn> is marked as being securely allocated, it's OSSL_PARAM representation will also be securely allocated. -The B<bn> argument is stored by reference and the underlying BIGNUM object +The I<bn> argument is stored by reference and the underlying BIGNUM object must exist until after ossl_param_bld_to_param() has been called. ossl_param_bld_push_utf8_string() is a function that will create an OSSL_PARAM -object that references the UTF8 string specified by B<buf>. -If the length of the string, B<bsize>, is zero then it will be calculated. -The string that B<buf> points to is stored by reference and must remain in +object that references the UTF8 string specified by I<buf>. +If the length of the string, I<bsize>, is zero then it will be calculated. +The string that I<buf> points to is stored by reference and must remain in scope until after ossl_param_bld_to_param() has been called. ossl_param_bld_push_octet_string() is a function that will create an OSSL_PARAM -object that references the octet string specified by B<buf> and <bsize>. -The memory that B<buf> points to is stored by reference and must remain in +object that references the octet string specified by I<buf> and <bsize>. +The memory that I<buf> points to is stored by reference and must remain in scope until after ossl_param_bld_to_param() has been called. ossl_param_bld_push_utf8_ptr() is a function that will create an OSSL_PARAM -object that references the UTF8 string specified by B<buf>. -If the length of the string, B<bsize>, is zero then it will be calculated. -The string B<buf> points to is stored by reference and must remain in +object that references the UTF8 string specified by I<buf>. +If the length of the string, I<bsize>, is zero then it will be calculated. +The string I<buf> points to is stored by reference and must remain in scope until the OSSL_PARAM array is freed. ossl_param_bld_push_octet_ptr() is a function that will create an OSSL_PARAM -object that references the octet string specified by B<buf>. -The memory B<buf> points to is stored by reference and must remain in +object that references the octet string specified by I<buf>. +The memory I<buf> points to is stored by reference and must remain in scope until the OSSL_PARAM array is freed. =head1 RETURN VALUES diff --git a/doc/internal/man3/ossl_prov_util_nid_to_name.pod b/doc/internal/man3/ossl_prov_util_nid_to_name.pod index 56a16d34e6..dce4ba60ac 100644 --- a/doc/internal/man3/ossl_prov_util_nid_to_name.pod +++ b/doc/internal/man3/ossl_prov_util_nid_to_name.pod @@ -14,7 +14,7 @@ ossl_prov_util_nid_to_name =head1 DESCRIPTION The ossl_prov_util_nid_to_name() returns the name of an algorithm given a NID -in the B<nid> parameter. For the default and legacy providers it is equivalent +in the I<nid> parameter. For the default and legacy providers it is equivalent to calling OBJ_nid2sn(). The FIPS provider does not have the object database code available to it (because that code relies on the ASN.1 code), so this function is a static lookup of all known FIPS algorithm NIDs. diff --git a/doc/internal/man3/rand_bytes_ex.pod b/doc/internal/man3/rand_bytes_ex.pod index 740607310c..cf54e02a31 100644 --- a/doc/internal/man3/rand_bytes_ex.pod +++ b/doc/internal/man3/rand_bytes_ex.pod @@ -16,9 +16,9 @@ rand_bytes_ex, rand_priv_bytes_ex rand_bytes_ex() and rand_priv_bytes_ex() are the equivalent of RAND_bytes() and RAND_priv_bytes() in the public API except that they both take an additional -B<ctx> parameter. +I<ctx> parameter. The DRBG used for the operation is the public or private DRBG associated with -the specified B<ctx>. The parameter can be NULL, in which case +the specified I<ctx>. The parameter can be NULL, in which case the default library ctx is used. If the default RAND_METHOD has been changed then for compatibility reasons the RAND_METHOD will be used in preference and the DRBG of the library context diff --git a/doc/man7/EVP_KDF-HKDF.pod b/doc/man7/EVP_KDF-HKDF.pod index 4da887c007..6bb65e21e7 100644 --- a/doc/man7/EVP_KDF-HKDF.pod +++ b/doc/man7/EVP_KDF-HKDF.pod @@ -63,7 +63,7 @@ derived otherwise an error will occur. In this mode calling L<EVP_KDF-derive(3)> will just perform the extract operation. The value returned will be the intermediate fixed-length pseudorandom -key K. The C<keylen> parameter must match the size of K, which can be looked +key K. The I<keylen> parameter must match the size of K, which can be looked up by calling EVP_KDF_size() after setting the mode and digest. The digest, key and salt values must be set before a key is derived otherwise @@ -89,12 +89,12 @@ A context for HKDF can be obtained by calling: EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); -The output length of an HKDF expand operation is specified via the C<keylen> +The output length of an HKDF expand operation is specified via the I<keylen> parameter to the L<EVP_KDF-derive(3)> function. When using -EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C<keylen> parameter must equal the size of +EVP_KDF_HKDF_MODE_EXTRACT_ONLY the I<keylen> parameter must equal the size of the intermediate fixed-length pseudorandom key otherwise an error will occur. For that mode, the fixed output size can be looked up by calling EVP_KDF_size() -after setting the mode and digest on the C<EVP_KDF_CTX>. +after setting the mode and digest on the B<EVP_KDF_CTX>. =head1 EXAMPLES diff --git a/doc/man7/EVP_KDF-PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod index e18816b544..43d074bdcc 100644 --- a/doc/man7/EVP_KDF-PBKDF2.pod +++ b/doc/man7/EVP_KDF-PBKDF2.pod @@ -65,10 +65,10 @@ The value string is expected to be a decimal number 0 or 1. =head1 NOTES A typical application of this algorithm is to derive keying material for an -encryption algorithm from a password in the B<pass>, a salt in B<salt>, +encryption algorithm from a password in the "pass", a salt in "salt", and an iteration count. -Increasing the B<iter> parameter slows down the algorithm which makes it +Increasing the "iter" parameter slows down the algorithm which makes it harder for an attacker to perform a brute force attack using a large number of candidate passwords. diff --git a/doc/man7/EVP_KDF-SCRYPT.pod b/doc/man7/EVP_KDF-SCRYPT.pod index 940629cb4b..888667e5c3 100644 --- a/doc/man7/EVP_KDF-SCRYPT.pod +++ b/doc/man7/EVP_KDF-SCRYPT.pod @@ -69,7 +69,7 @@ A context for scrypt can be obtained by calling: EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); The output length of an scrypt key derivation is specified via the -B<keylen> parameter to the L<EVP_KDF-derive(3)> function. +"keylen" parameter to the L<EVP_KDF-derive(3)> function. =head1 EXAMPLES diff --git a/doc/man7/EVP_KDF-SS.pod b/doc/man7/EVP_KDF-SS.pod index fcf423bb45..7ab3a3da63 100644 --- a/doc/man7/EVP_KDF-SS.pod +++ b/doc/man7/EVP_KDF-SS.pod @@ -68,7 +68,7 @@ A context for SSKDF can be obtained by calling: EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); -The output length of an SSKDF is specified via the C<keylen> +The output length of an SSKDF is specified via the I<keylen> parameter to the L<EVP_KDF-derive(3)> function. =head1 EXAMPLES diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod index bcf3ff5f69..81d6120f0a 100644 --- a/doc/man7/EVP_KDF-SSHKDF.pod +++ b/doc/man7/EVP_KDF-SSHKDF.pod @@ -89,7 +89,7 @@ A context for SSHKDF can be obtained by calling: EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); -The output length of the SSHKDF derivation is specified via the C<keylen> +The output length of the SSHKDF derivation is specified via the I<keylen> parameter to the L<EVP_KDF-derive(3)> function. Since the SSHKDF output length is variable, calling L<EVP_KDF-size()> to obtain the requisite length is not meaningful. The caller must diff --git a/doc/man7/EVP_KDF-TLS1_PRF.pod b/doc/man7/EVP_KDF-TLS1_PRF.pod index 0089e07599..d6c736555f 100644 --- a/doc/man7/EVP_KDF-TLS1_PRF.pod +++ b/doc/man7/EVP_KDF-TLS1_PRF.pod @@ -28,7 +28,7 @@ The supported parameters are: These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. -The C<OSSL_KDF_PARAM_DIGEST> parameter is used to set the message digest +The B<OSSL_KDF_PARAM_DIGEST> parameter is used to set the message digest associated with the TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1. @@ -56,7 +56,7 @@ A context for the TLS PRF can be obtained by calling: The digest, secret value and seed must be set before a key is derived otherwise an error will occur. -The output length of the PRF is specified by the C<keylen> parameter to the +The output length of the PRF is specified by the I<keylen> parameter to the EVP_KDF_derive() function. =head1 EXAMPLES diff --git a/doc/man7/EVP_KDF-X942.pod b/doc/man7/EVP_KDF-X942.pod index 1a4ab8131a..a45d283c15 100644 --- a/doc/man7/EVP_KDF-X942.pod +++ b/doc/man7/EVP_KDF-X942.pod @@ -51,7 +51,7 @@ A context for X942KDF can be obtained by calling: EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); -The output length of an X942KDF is specified via the C<keylen> +The output length of an X942KDF is specified via the I<keylen> parameter to the L<EVP_KDF-derive(3)> function. =head1 EXAMPLES diff --git a/doc/man7/EVP_KDF-X963.pod b/doc/man7/EVP_KDF-X963.pod index 62a5378938..427219ee1d 100644 --- a/doc/man7/EVP_KDF-X963.pod +++ b/doc/man7/EVP_KDF-X963.pod @@ -48,7 +48,7 @@ A context for X963KDF can be obtained by calling: EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); -The output length of an X963KDF is specified via the C<keylen> +The output length of an X963KDF is specified via the I<keylen> parameter to the L<EVP_KDF-derive(3)> function. =head1 EXAMPLES diff --git a/doc/man7/Ed25519.pod b/doc/man7/Ed25519.pod index 8269f2feaa..74bf7c31ee 100644 --- a/doc/man7/Ed25519.pod +++ b/doc/man7/Ed25519.pod @@ -25,7 +25,7 @@ The message to sign or verify must be passed using the one-shot EVP_DigestSign() and EVP_DigestVerify() functions. When calling EVP_DigestSignInit() or EVP_DigestVerifyInit(), the -digest B<type> parameter B<MUST> be set to B<NULL>. +digest I<type> parameter B<MUST> be set to NULL. Applications wishing to sign certificates (or other structures such as CRLs or certificate requests) using Ed25519 or Ed448 can either use X509_sign() diff --git a/doc/man7/RAND_DRBG.pod b/doc/man7/RAND_DRBG.pod index 467a544db3..8b91505000 100644 --- a/doc/man7/RAND_DRBG.pod +++ b/doc/man7/RAND_DRBG.pod @@ -239,7 +239,7 @@ pulls the necessary entropy from its source automatically. However, both calls are permitted, and do reseed the RNG. RAND_add() can be used to add both kinds of random input, depending on the -value of the B<randomness> argument: +value of the I<randomness> argument: =over 4 @@ -267,7 +267,7 @@ from the trusted entropy sources. NOTE: Manual reseeding is *not allowed* in FIPS mode, because [NIST SP-800-90Ar1] mandates that entropy *shall not* be provided by the consuming application for instantiation (Section 9.1) or -reseeding (Section 9.2). For that reason, the B<randomness> +reseeding (Section 9.2). For that reason, the I<randomness> argument is ignored and the random bytes provided by the L<RAND_add(3)> and L<RAND_seed(3)> calls are treated as additional data. diff --git a/doc/man7/bio.pod b/doc/man7/bio.pod index bc1fb1e45e..1d3276b730 100644 --- a/doc/man7/bio.pod +++ b/doc/man7/bio.pod @@ -47,7 +47,7 @@ in a memory leak. Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() on it other than the discarded return value. -Normally the B<type> argument is supplied by a function which returns a +Normally the I<type> argument is supplied by a function which returns a pointer to a BIO_METHOD. There is a naming convention for such functions: a source/sink BIO is normally called BIO_s_*() and a filter BIO BIO_f_*(); diff --git a/doc/man7/crypto.pod b/doc/man7/crypto.pod index 0e8008b332..aa6b6405ba 100644 --- a/doc/man7/crypto.pod +++ b/doc/man7/crypto.pod @@ -10,13 +10,13 @@ See the individual manual pages for details. =head1 DESCRIPTION -The OpenSSL B<crypto> library implements a wide range of cryptographic -algorithms used in various Internet standards. The services provided -by this library are used by the OpenSSL implementations of SSL, TLS +The OpenSSL crypto library (C<libcrypto>) implements a wide range of +cryptographic algorithms used in various Internet standards. The services +provided by this library are used by the OpenSSL implementations of SSL, TLS and S/MIME, and they have also been used to implement SSH, OpenPGP, and other cryptographic standards. -B<libcrypto> consists of a number of sub-libraries that implement the +C<libcrypto> consists of a number of sub-libraries that implement the individual algorithms. The functionality includes symmetric encryption, public key @@ -34,11 +34,11 @@ B<0> and B<1>. For example the functions: The B<0> version uses the supplied structure pointer directly in the parent and it will be freed up when the parent is freed. -In the above example B<crl> would be freed but B<rev> would not. +In the above example I<crl> would be freed but I<rev> would not. The B<1> function uses a copy of the supplied structure pointer (or in some cases increases its link count) in the parent and -so both (B<x> and B<obj> above) should be freed up. +so both (I<x> and I<obj> above) should be freed up. =head1 RETURN VALUES diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod index 737293d701..a7f209b104 100644 --- a/doc/man7/openssl-core.h.pod +++ b/doc/man7/openssl-core.h.pod @@ -20,14 +20,14 @@ The types are: =over 4 -=item C<OSSL_DISPATCH> +=item B<OSSL_DISPATCH> 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 C<NULL>. +identity zero and function pointer NULL. The available function identities and corresponding function signatures are defined by L<openssl-core_numbers.h(7)>. @@ -38,41 +38,41 @@ This ensures that providers built with one OpenSSL version in mind will work together with any other OpenSSL version that supports this mechanism. -=item C<OSSL_ITEM> +=item B<OSSL_ITEM> 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 C<NULL>. +zero and the pointer NULL. -=item C<OSSL_ALGORITHM> +=item B<OSSL_ALGORITHM> This type is a tuple of an algorithm name (string), a property -definition (string) and a dispatch table (array of C<OSSL_DISPATCH>). +definition (string) and a dispatch table (array of B<OSSL_DISPATCH>). 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 C<NULL>. +identity zero and function pointer NULL. The algorithm names and property definitions are defined by the providers. -=item C<OSSL_PARAM> +=item B<OSSL_PARAM> 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 C<NULL> (for +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. -C<OSSL_PARAM> is further described in L<OSSL_PARAM(3)> +B<OSSL_PARAM> is further described in L<OSSL_PARAM(3)> =back diff --git a/doc/man7/ossl_store-file.pod b/doc/man7/ossl_store-file.pod index c517503eb7..d6ea27bedf 100644 --- a/doc/man7/ossl_store-file.pod +++ b/doc/man7/ossl_store-file.pod @@ -46,7 +46,7 @@ only). =head1 NOTES When needed, the 'file' scheme loader will require a pass phrase by -using the C<UI_METHOD> that was passed via OSSL_STORE_open(). +using the B<UI_METHOD> that was passed via OSSL_STORE_open(). This pass phrase is expected to be UTF-8 encoded, anything else will give an undefined result. The files made accessible through this loader are expected to be diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index 89cf07be0c..c8377d6835 100644 --- a/doc/man7/provider-cipher.pod +++ b/doc/man7/provider-cipher.pod @@ -111,65 +111,65 @@ OP_cipher_newctx() should create and return a pointer to a provider side structure for holding context information during a cipher operation. A pointer to this context will be passed back in a number of the other cipher operation function calls. -The parameter B<provctx> is the provider context generated during provider +The parameter I<provctx> is the provider context generated during provider initialisation (see L<provider(3)>). OP_cipher_freectx() is passed a pointer to the provider side cipher context in -the B<cctx> parameter. +the I<cctx> parameter. This function should free any resources associated with that context. OP_cipher_dupctx() should duplicate the provider side cipher context in the -B<cctx> parameter and return the duplicate copy. +I<cctx> parameter and return the duplicate copy. =head2 Encryption/Decryption Functions OP_cipher_encrypt_init() initialises a cipher operation for encryption given a -newly created provider side cipher context in the B<cctx> parameter. -The key to be used is given in B<key> which is B<keylen> bytes long. -The IV to be used is given in B<iv> which is B<ivlen> bytes long. +newly created provider side cipher context in the I<cctx> parameter. +The key to be used is given in I<key> which is I<keylen> bytes long. +The IV to be used is given in I<iv> which is I<ivlen> bytes long. OP_cipher_decrypt_init() is the same as OP_cipher_encrypt_init() except that it initialises the context for a decryption operation. OP_cipher_update() is called to supply data to be encrypted/decrypted as part of a previously initialised cipher operation. -The B<cctx> parameter contains a pointer to a previously initialised provider +The I<cctx> parameter contains a pointer to a previously initialised provider side context. -OP_cipher_update() should encrypt/decrypt B<inl> bytes of data at the location -pointed to by B<in>. -The encrypted data should be stored in B<out> and the amount of data written to -B<*outl> which should not exceed B<outsize> bytes. +OP_cipher_update() should encrypt/decrypt I<inl> bytes of data at the location +pointed to by I<in>. +The encrypted data should be stored in I<out> and the amount of data written to +I<*outl> which should not exceed I<outsize> bytes. OP_cipher_update() may be called multiple times for a single cipher operation. It is the responsibility of the cipher implementation to handle input lengths that are not multiples of the block length. In such cases a cipher implementation will typically cache partial blocks of input data until a complete block is obtained. -B<out> may be the same location as B<in> but it should not partially overlap. -The same expectations apply to B<outsize> as documented for +I<out> may be the same location as I<in> but it should not partially overlap. +The same expectations apply to I<outsize> as documented for L<EVP_EncryptUpdate(3)> and L<EVP_DecryptUpdate(3)>. OP_cipher_final() completes an encryption or decryption started through previous OP_cipher_encrypt_init() or OP_cipher_decrypt_init(), and OP_cipher_update() calls. -The B<cctx> parameter contains a pointer to the provider side context. -Any final encryption/decryption output should be written to B<out> and the -amount of data written to B<*outl> which should not exceed B<outsize> bytes. -The same expectations apply to B<outsize> as documented for +The I<cctx> parameter contains a pointer to the provider side context. +Any final encryption/decryption output should be written to I<out> and the +amount of data written to I<*outl> which should not exceed I<outsize> bytes. +The same expectations apply to I<outsize> as documented for L<EVP_EncryptFinal(3)> and L<EVP_DecryptFinal(3)>. OP_cipher_cipher() performs encryption/decryption using the provider side cipher -context in the B<cctx> parameter that should have been previously initialised via +context in the I<cctx> parameter that should have been previously initialised via a call to OP_cipher_encrypt_init() or OP_cipher_decrypt_init. This should call the raw underlying cipher function without any padding. This will be invoked in the provider as a result of the application calling L<EVP_Cipher(3)>. The application is responsible for ensuring that the input is a multiple of the block length. -The data to be encrypted/decrypted will be in B<in>, and it will be B<inl> bytes +The data to be encrypted/decrypted will be in I<in>, and it will be I<inl> bytes in length. -The output from the encryption/decryption should be stored in B<out> and the -amount of data stored should be put in B<*outl> which should be no more than -B<outsize> bytes. +The output from the encryption/decryption should be stored in I<out> and the +amount of data stored should be put in I<*outl> which should be no more than +I<outsize> bytes. =head2 Cipher Parameters @@ -177,14 +177,14 @@ See L<OSSL_PARAM(3)> for further details on the parameters structure used by these functions. OP_cipher_get_params() gets details of the algorithm implementation -and stores them in B<params>. +and stores them in I<params>. OP_cipher_set_ctx_params() sets cipher operation parameters for the -provider side cipher context B<cctx> to B<params>. +provider side cipher context I<cctx> to I<params>. Any parameter settings are additional to any that were previously set. OP_cipher_get_ctx_params() gets cipher operation details details from -the given provider side cipher context B<cctx> and stores them in B<params>. +the given provider side cipher context I<cctx> and stores them in I<params>. OP_cipher_gettable_params(), OP_cipher_gettable_ctx_params(), and OP_cipher_settable_ctx_params() all return constant B<OSSL_PARAM> arrays @@ -306,7 +306,7 @@ beginning of the output buffer, do "in place" encryption of the payload and write that to the output buffer, and finally add the tag onto the end of the output buffer. -Whether encrypting or decrypting the value written to B<*outl> in the +Whether encrypting or decrypting the value written to I<*outl> in the OP_cipher_cipher call should be the length of the payload excluding the explicit IV length and the tag length. diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index ff388da100..089c0e2082 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -99,43 +99,43 @@ OP_digest_newctx() should create and return a pointer to a provider side structure for holding context information during a digest operation. A pointer to this context will be passed back in a number of the other digest operation function calls. -The parameter B<provctx> is the provider context generated during provider +The parameter I<provctx> is the provider context generated during provider initialisation (see L<provider(3)>). OP_digest_freectx() is passed a pointer to the provider side digest context in -the B<dctx> parameter. +the I<dctx> parameter. This function should free any resources associated with that context. OP_digest_dupctx() should duplicate the provider side digest context in the -B<dctx> parameter and return the duplicate copy. +I<dctx> parameter and return the duplicate copy. =head2 Digest Generation Functions OP_digest_init() initialises a digest operation given a newly created -provider side digest context in the B<dctx> parameter. +provider side digest context in the I<dctx> parameter. OP_digest_update() is called to supply data to be digested as part of a previously initialised digest operation. -The B<dctx> parameter contains a pointer to a previously initialised provider +The I<dctx> parameter contains a pointer to a previously initialised provider side context. -OP_digest_update() should digest B<inl> bytes of data at the location pointed to -by B<in>. +OP_digest_update() should digest I<inl> bytes of data at the location pointed to +by I<in>. OP_digest_update() may be called multiple times for a single digest operation. OP_digest_final() generates a digest started through previous OP_digest_init() and OP_digest_update() calls. -The B<dctx> parameter contains a pointer to the provider side context. -The digest should be written to B<*out> and the length of the digest to -B<*outl>. -The digest should not exceed B<outsz> bytes. +The I<dctx> parameter contains a pointer to the provider side context. +The digest should be written to I<*out> and the length of the digest to +I<*outl>. +The digest should not exceed I<outsz> bytes. OP_digest_digest() is a "oneshot" digest function. No provider side digest context is used. Instead the provider context that was created during provider initialisation is -passed in the B<provctx> parameter (see L<provider(3)>). -B<inl> bytes at B<in> should be digested and the result should be stored at -B<out>. The length of the digest should be stored in B<*outl> which should not -exceed B<outsz> bytes. +passed in the I<provctx> parameter (see L<provider(3)>). +I<inl> bytes at I<in> should be digested and the result should be stored at +I<out>. The length of the digest should be stored in I<*outl> which should not +exceed I<outsz> bytes. =head2 Digest Parameters @@ -143,14 +143,14 @@ See L<OSSL_PARAM(3)> for further details on the parameters structure used by these functions. OP_digest_get_params() gets details of the algorithm implementation -and stores them in B<params>. +and stores them in I<params>. OP_digest_set_ctx_params() sets digest operation parameters for the -provider side digest context B<dctx> to B<params>. +provider side digest context I<dctx> to I<params>. Any parameter settings are additional to any that were previously set. OP_digest_get_ctx_params() gets digest operation details details from -the given provider side digest context B<dctx> and stores them in B<params>. +the given provider side digest context I<dctx> and stores them in I<params>. OP_digest_gettable_params(), OP_digest_gettable_ctx_params(), and OP_digest_settable_ctx_params() all return constant B<OSSL_PARAM> arrays @@ -218,13 +218,13 @@ B<unsigned long int>. =head2 Digest Context Parameters OP_digest_set_ctx_params() sets digest parameters associated with the -given provider side digest context B<dctx> to B<params>. +given provider side digest context I<dctx> to I<params>. Any parameter settings are additional to any that were previously set. See L<OSSL_PARAM(3)> for further details on the parameters structure. OP_digest_get_ctx_params() gets details of currently set parameters -values associated with the give provider side digest context B<dctx> -and stores them in B<params>. +values associated with the give provider side digest context I<dctx> +and stores them in I<params>. See L<OSSL_PARAM(3)> for further details on the parameters structure. Parameters currently recognised by built-in digests are as follows. Not all diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index 358e16a0df..c4cb021185 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -87,27 +87,27 @@ OP_keyexch_newctx() should create and return a pointer to a provider side structure for holding context information during a key exchange operation. A pointer to this context will be passed back in a number of the other key exchange operation function calls. -The paramater B<provctx> is the provider context generated during provider +The paramater I<provctx> is the provider context generated during provider initialisation (see L<provider(3)>). OP_keyexch_freectx() is passed a pointer to the provider side key exchange -context in the B<ctx> parameter. +context in the I<ctx> parameter. This function should free any resources associated with that context. OP_keyexch_dupctx() should duplicate the provider side key exchange context in -the B<ctx> parameter and return the duplicate copy. +the I<ctx> parameter and return the duplicate copy. =head2 Shared Secret Derivation Functions OP_keyexch_init() initialises a key exchange operation given a provider side key -exchange context in the B<ctx> paramter, and a pointer to a provider key object -in the B<provkey> parameter. The key object should have been previously +exchange context in the I<ctx> paramter, and a pointer to a provider key object +in the I<provkey> parameter. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. OP_keyexch_set_peer() is called to supply the peer's public key (in the -B<provkey> parameter) to be used when deriving the shared secret. -It is also passed a previously initialised key exchange context in the B<ctx> +I<provkey> parameter) to be used when deriving the shared secret. +It is also passed a previously initialised key exchange context in the I<ctx> parameter. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see @@ -115,13 +115,13 @@ provider-keymgmt(7)>. OP_keyexch_derive() performs the actual key exchange itself by deriving a shared secret. -A previously initialised key exchange context is passed in the B<ctx> +A previously initialised key exchange context is passed in the I<ctx> parameter. -The derived secret should be written to the location B<secret> which should not -exceed B<outlen> bytes. -The length of the shared secret should be written to B<*secretlen>. -If B<secret> is NULL then the maximum length of the shared secret should be -written to B<*secretlen>. +The derived secret should be written to the location I<secret> which should not +exceed I<outlen> bytes. +The length of the shared secret should be written to I<*secretlen>. +If I<secret> is NULL then the maximum length of the shared secret should be +written to I<*secretlen>. =head2 Key Exchange Parameters @@ -129,7 +129,7 @@ See L<OSSL_PARAM(3)> for further details on the parameters structure used by the OP_keyexch_set_params() function. OP_keyexch_set_ctx_params() sets key exchange parameters associated with the -given provider side key exchange context B<ctx> to B<params>. +given provider side key exchange context I<ctx> to I<params>. Any parameter settings are additional to any that were previously set. Parameters currently recognised by built-in key exchange algorithms are as diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 777b991cc6..73d573a9f2 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -111,70 +111,70 @@ OP_signature_newctx() should create and return a pointer to a provider side structure for holding context information during a signature operation. A pointer to this context will be passed back in a number of the other signature operation function calls. -The parameter B<provctx> is the provider context generated during provider +The parameter I<provctx> is the provider context generated during provider initialisation (see L<provider(3)>). OP_signature_freectx() is passed a pointer to the provider side signature -context in the B<ctx> parameter. +context in the I<ctx> parameter. This function should free any resources associated with that context. OP_signature_dupctx() should duplicate the provider side signature context in -the B<ctx> parameter and return the duplicate copy. +the I<ctx> parameter and return the duplicate copy. =head2 Signing Functions OP_signature_sign_init() initialises a context for signing given a provider side -signature context in the B<ctx> parameter, and a pointer to a provider key object -in the B<provkey> parameter. +signature context in the I<ctx> parameter, and a pointer to a provider key object +in the I<provkey> parameter. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. OP_signature_sign() performs the actual signing itself. -A previously initialised signature context is passed in the B<ctx> +A previously initialised signature context is passed in the I<ctx> parameter. -The data to be signed is pointed to be the B<tbs> parameter which is B<tbslen> +The data to be signed is pointed to be the I<tbs> parameter which is I<tbslen> bytes long. -Unless B<sig> is NULL, the signature should be written to the location pointed -to by the B<sig> parameter and it should not exceed B<sigsize> bytes in length. -The length of the signature should be written to B<*siglen>. -If B<sig> is NULL then the maximum length of the signature should be written to -B<*siglen>. +Unless I<sig> is NULL, the signature should be written to the location pointed +to by the I<sig> parameter and it should not exceed I<sigsize> bytes in length. +The length of the signature should be written to I<*siglen>. +If I<sig> is NULL then the maximum length of the signature should be written to +I<*siglen>. =head2 Verify Functions OP_signature_verify_init() initialises a context for verifying a signature given -a provider side signature context in the B<ctx> parameter, and a pointer to a -provider key object in the B<provkey> parameter. +a provider side signature context in the I<ctx> parameter, and a pointer to a +provider key object in the I<provkey> parameter. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. OP_signature_verify() performs the actual verification itself. -A previously initialised signature context is passed in the B<ctx> parameter. -The data that the signature covers is pointed to be the B<tbs> parameter which -is B<tbslen> bytes long. -The signature is pointed to by the B<sig> parameter which is B<siglen> bytes +A previously initialised signature context is passed in the I<ctx> parameter. +The data that the signature covers is pointed to be the I<tbs> parameter which +is I<tbslen> bytes long. +The signature is pointed to by the I<sig> parameter which is I<siglen> bytes long. =head2 Verify Recover Functions OP_signature_verify_recover_init() initialises a context for recovering the -signed data given a provider side signature context in the B<ctx> parameter, and -a pointer to a provider key object in the B<provkey> parameter. +signed data given a provider side signature context in the I<ctx> parameter, and +a pointer to a provider key object in the I<provkey> parameter. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>. OP_signature_verify_recover() performs the actual verify recover itself. -A previously initialised signature context is passed in the B<ctx> parameter. -The signature is pointed to by the B<sig> parameter which is B<siglen> bytes +A previously initialised signature context is passed in the I<ctx> parameter. +The signature is pointed to by the I<sig> parameter which is I<siglen> bytes long. -Unless B<rout> is NULL, the recovered data should be written to the location -pointed to by B<rout> which should not exceed B<routsize> bytes in length. -The length of the recovered data should be written to B<*routlen>. -If B<rout> is B<NULL> then the maximum size of the output buffer is written to -the B<routlen> parameter. +Unless I<rout> is NULL, the recovered data should be written to the location +pointed to by I<rout> which should not exceed I<routsize> bytes in length. +The length of the recovered data should be written to I<*routlen>. +If I<rout> is NULL then the maximum size of the output buffer is written to +the I<routlen> parameter. =head2 Signature Parameters @@ -182,9 +182,9 @@ See L<OSSL_PARAM(3)> for further details on the parameters structure used by the OP_signature_get_ctx_params() and OP_signature_set_ctx_params() functions. OP_signature_get_ctx_params() gets signature parameters associated with the -given provider side signature context B<ctx> and stored them in B<params>. +given provider side signature context I<ctx> and stored them in I<params>. OP_signature_set_ctx_params() sets the signature parameters associated with the -given provider side signature context B<ctx> to B<params>. +given provider side signature context I<ctx> to I<params>. Any parameter settings are additional to any that were previously set. Parameters currently recognised by built-in signature algorithms are as diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index f92d111e95..c6e7d10fd8 100644 --- a/doc/man7/provider.pod +++ b/doc/man7/provider.pod @@ -150,7 +150,7 @@ L<provider-kdf(7)> =item Key Exchange In the OpenSSL libraries, the corresponding method object is -B<EVP_KEYEXCh>. +B<EVP_KEYEXCH>. The number for this operation is B<OSSL_OP_KEYEXCH>. The functions the provider can offer are described in L<provider-keyexch(7)> |