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
=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
=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
-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
+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(),
=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.
=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
=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
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
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
=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
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
=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.
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
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>.
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>.
=head1 RETURN VALUES
ossl_method_construct() returns a constructed method on success, or
-B<NULL> on error.
+NULL on error.
=head1 HISTORY
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.
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
=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.
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
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
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
=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.
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
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
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
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.
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
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
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
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()
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
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.
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_*();
=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
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
=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)>.
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
=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
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
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
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.
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
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
=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
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
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
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
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
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
=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)>
projects / oweals / openssl.git / commitdiff