/*
- * Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
+ * Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
*
* Licensed under the Apache License 2.0 (the "License"). You may not use
* this file except in compliance with the License. You can obtain a copy
void OSSL_LIB_CTX_free(OSSL_LIB_CTX *ctx)
{
- if (ossl_lib_ctx_is_default(ctx))
+ if (ctx == NULL || ossl_lib_ctx_is_default(ctx))
return;
#ifndef FIPS_MODULE
ASN1_INTEGER_new() returns an allocated B<ASN1_INTEGER> structure.
ASN1_INTEGER_free() frees up a single B<ASN1_INTEGER> object.
+If the argument is NULL, nothing is done.
B<ASN1_INTEGER> structure representing the ASN.1 INTEGER type
user code set a callback by calling ASYNC_WAIT_CTX_set_callback() previously,
then the registered callback will be called.
+ASYNC_WAIT_CTX_free() frees up a single B<ASYNC_WAIT_CTX> object.
+If the argument is NULL, nothing is done.
+
=head1 RETURN VALUES
ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated B<ASYNC_WAIT_CTX>
BIO_ADDR *BIO_ADDR_new(void);
int BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src);
BIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);
- void BIO_ADDR_free(BIO_ADDR *);
+ void BIO_ADDR_free(BIO_ADDR *ap);
void BIO_ADDR_clear(BIO_ADDR *ap);
int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
const void *where, size_t wherelen, unsigned short port);
address data in B<ap>.
BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new()
-or BIO_ADDR_dup();
+or BIO_ADDR_dup(). If the argument is NULL, nothing is done.
BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
it back to an uninitialised state.
from the given one.
BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting
-with the given one.
+with the given one. If the argument is NULL, nothing is done.
=head1 RETURN VALUES
L<BIO_find_type(3)> page for more information.
BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
-associated with it.
+associated with it. If the argument is NULL, nothing is done.
BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function
used for writing arbitrary length data to the BIO respectively. This function
for backwards compatibility purposes.
A B<BN_GENCB> structure should be created through a call to BN_GENCB_new(),
-and freed through a call to BN_GENCB_free().
+and freed through a call to BN_GENCB_free(). If the argument is NULL,
+nothing is done.
For "new" style callbacks a BN_GENCB structure should be initialised with a
call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of
BUF_MEM_free() frees up an already existing buffer. The data is zeroed
before freeing up in case the buffer contains sensitive data.
+If the argument is NULL, nothing is done.
BUF_MEM_grow() changes the size of an already existing buffer to
B<len>. Any data already in the buffer is preserved if it increases in
the OpenSSL library to support TLS record and certificate compression.
COMP_CTX_new() is used to create a new B<COMP_CTX> structure used to compress data.
+
COMP_CTX_free() is used to free the returned B<COMP_CTX>.
+If the argument is NULL, nothing is done.
COMP_CTX_get_method() returns the B<COMP_METHOD> of the given I<ctx>.
=item *
CRYPTO_THREAD_lock_free() frees the provided I<lock>.
+If the argument is NULL, nothing is done.
=item *
Once a CTLOG_STORE is no longer required, it should be passed to
CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along
-with the CTLOG_STORE itself.
+with the CTLOG_STORE itself. If the argument is NULL, nothing is done.
=head1 NOTES
Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the
caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer
needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that
-was passed to it.
+was passed to it. If the argument to CTLOG_free() is NULL, nothing is done.
CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was
created. Ownership of the string remains with the CTLOG.
Each setter has a matching getter for accessing the current value.
When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to
-CT_POLICY_EVAL_CTX_free() to delete it.
+CT_POLICY_EVAL_CTX_free() to delete it. If the argument to
+CT_POLICY_EVAL_CTX_free() is NULL, nothing is done.
=head1 NOTES
existing one, but with some differences.
DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory
-associated with it.
+associated with it. If the argument is NULL, nothing is done.
DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This
is a pointer to the internal name string and so should not be freed by the
DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The
values are erased before the memory is returned to the system.
+If the argument is NULL, nothing is done.
DSA_SIG_get0() returns internal pointers to the B<r> and B<s> values contained
in B<sig>.
existing one, but with some differences.
DSA_meth_free() destroys a B<DSA_METHOD> structure and frees up any memory
-associated with it.
+associated with it. If the argument is NULL, nothing is done.
DSA_meth_get0_name() will return a pointer to the name of this DSA_METHOD. This
is a pointer to the internal name string and so should not be freed by the
Note: before OpenSSL 1.1.0, the I<r> and I<s> components were initialised.
ECDSA_SIG_free() frees the B<ECDSA_SIG> structure I<sig>.
+If the argument is NULL, nothing is done.
ECDSA_SIG_get0() returns internal pointers the I<r> and I<s> values contained
in I<sig> and stores them in I<*pr> and I<*ps>, respectively.
ENGINE_get_next(), ENGINE_get_prev(). All structural references should be
released by a corresponding to call to the ENGINE_free() function - the
ENGINE object itself will only actually be cleaned up and deallocated when
-the last structural reference is released.
+the last structural reference is released. If the argument to ENGINE_free()
+is NULL, nothing is done.
It should also be noted that many ENGINE API function calls that accept a
structural reference will internally obtain another reference - typically
EVP_ASYM_CIPHER_free() decrements the reference count for the B<EVP_ASYM_CIPHER>
structure. Typically this structure will have been obtained from an earlier call
to EVP_ASYM_CIPHER_fetch(). If the reference count drops to 0 then the
-structure is freed.
+structure is freed. If the argument is NULL, nothing is done.
EVP_ASYM_CIPHER_up_ref() increments the reference count for an
B<EVP_ASYM_CIPHER> structure.
EVP_CIPHER_meth_dup() creates a copy of B<cipher>.
EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure.
+If the argument is NULL, nothing is done.
EVP_CIPHER_meth_set_iv_length() sets the length of the IV.
This is only needed when the implemented cipher mode requires it.
Decrements the reference count for the fetched B<EVP_MD> structure.
If the reference count drops to 0 then the structure is freed.
+If the argument is NULL, nothing is done.
=item EVP_MD_CTX_new()
=item EVP_MD_CTX_free()
Cleans up digest context I<ctx> and frees up the space allocated to it.
+If the argument is NULL, nothing is done.
=item EVP_MD_CTX_ctrl()
the encode/decode functions.
EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the
-space allocated to it.
+space allocated to it. If the argument is NULL, nothing is done.
Encoding of binary data is performed in blocks of 48 input bytes (or less for
the final block). For each 48 byte input block encoded 64 bytes of base 64 data
Decrements the reference count for the fetched B<EVP_CIPHER> structure.
If the reference count drops to 0 then the structure is freed.
+If the argument is NULL, nothing is done.
=item EVP_CIPHER_CTX_new()
=item EVP_CIPHER_CTX_free()
Clears all information from a cipher context and frees any allocated memory
-associated with it, including I<ctx> itself. This function should be called after
-all operations using a cipher are complete so sensitive information does not
-remain in memory.
+associated with it, including I<ctx> itself. This function should be called
+after all operations using a cipher are complete so sensitive information does
+not remain in memory. If the argument is NULL, nothing is done.
=item EVP_CIPHER_CTX_dup()
EVP_KEM_free() decrements the reference count for the B<EVP_KEM> structure.
Typically this structure will have been obtained from an earlier call to
EVP_KEM_fetch(). If the reference count drops to 0 then the structure is freed.
+If the argument is NULL, nothing is done.
EVP_KEM_up_ref() increments the reference count for an B<EVP_KEM> structure.
EVP_KEYEXCH_free() decrements the reference count for the B<EVP_KEYEXCH>
structure. Typically this structure will have been obtained from an earlier call
to EVP_KEYEXCH_fetch(). If the reference count drops to 0 then the
-structure is freed.
+structure is freed. If the argument is NULL, nothing is done.
EVP_KEYEXCH_up_ref() increments the reference count for an B<EVP_KEYEXCH>
structure.
EVP_KEYMGMT_free() decrements the reference count for the given
B<EVP_KEYMGMT> I<keymgmt>, and when the count reaches zero, frees it.
+If the argument is NULL, nothing is done.
EVP_KEYMGMT_get0_provider() returns the provider that has this particular
implementation.
EVP_MD_meth_free() decrements the reference count for the B<EVP_MD> structure.
If the reference count drops to 0 then the structure is freed.
+If the argument is NULL, nothing is done.
EVP_MD_meth_set_input_blocksize() sets the internal input block size
for the method B<md> to B<blocksize> bytes.
when initializing the application.
EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed
-by B<ameth>.
+by B<ameth>. If the argument is NULL, nothing is done.
EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of
methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is
digest signing operation by calling L<EVP_DigestSignFinal(3)>.
EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by
-B<pmeth>.
+B<pmeth>. If the argument is NULL, nothing is done.
EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src>
to B<dst>.
EVP_SIGNATURE_free() decrements the reference count for the B<EVP_SIGNATURE>
structure. Typically this structure will have been obtained from an earlier call
to EVP_SIGNATURE_fetch(). If the reference count drops to 0 then the
-structure is freed.
+structure is freed. If the argument is NULL, nothing is done.
EVP_SIGNATURE_up_ref() increments the reference count for an B<EVP_SIGNATURE>
structure.
HMAC_CTX_free() erases the key and other data from the B<HMAC_CTX>,
releases any associated resources and finally frees the B<HMAC_CTX>
-itself.
+itself. If the argument is NULL, nothing is done.
The following functions may be used if the message is not completely
stored in memory:
NCONF_new() is similar to NCONF_new_ex() but sets the I<libctx> to NULL.
NCONF_free() frees the data associated with I<conf> and then frees the I<conf>
-object.
+object. If the argument is NULL, nothing is done.
NCONF_load() parses the file named I<filename> and adds the values found to
I<conf>. If an error occurs I<file> and I<eline> list the file and line that
OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure.
OCSP_REQUEST_free() frees up the request structure B<req>.
+If the argument is NULL, nothing is done.
OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns
the B<OCSP_ONEREQ> structure added so an application can add additional
B<serialNumber>.
OCSP_CERTID_free() frees up B<id>.
+If the argument is NULL, nothing is done.
OCSP_id_cmp() compares B<OCSP_CERTID> B<a> and B<b>.
I<status> and optionally including basic response I<bs>.
OCSP_RESPONSE_free() frees up OCSP response I<resp>.
+If the argument is NULL, nothing is done.
OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the
subject name in the supplied X509 certificate I<cert> for the OCSP responder.
B<lh_I<TYPE>_free>() frees the B<LHASH_OF>(B<I<TYPE>>) structure
I<table>. Allocated hash table entries will not be freed; consider
using B<lh_I<TYPE>_doall>() to deallocate any remaining entries in the
-hash table (see below).
+hash table (see below). If the argument is NULL, nothing is done.
B<lh_I<TYPE>_flush>() empties the B<LHASH_OF>(B<I<TYPE>>) structure I<table>. New
entries can be added to the flushed table. Allocated hash table entries
the configuration file will cause an error return from B<OPENSSL_init_crypto>
or indirectly L<OPENSSL_init_ssl(3)>.
The object can be released with OPENSSL_INIT_free() when done.
+If the argument to OPENSSL_INIT_free() is NULL, nothing is done.
=head1 NOTES
OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used
when the buffer at B<addr> holds sensitive information.
The old buffer is filled with zero's by calling OPENSSL_cleanse()
-before ultimately calling OPENSSL_free().
+before ultimately calling OPENSSL_free(). If the argument to OPENSSL_free() is
+NULL, nothing is done.
OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's.
Use OPENSSL_cleanse() with care if the memory is a mapping of a file.
calling OPENSSL_free().
It exists for consistency with OPENSSL_secure_malloc() , and
is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__>
-and C<__LINE__> parameters..
+and C<__LINE__> parameters.. If the argument to OPENSSL_secure_free()
+is NULL, nothing is done.
OPENSSL_secure_clear_free() is similar to OPENSSL_secure_free() except
that it has an additional C<num> parameter which is used to clear
the memory if it was not allocated from the secure heap.
If CRYPTO_secure_malloc_init() is not called, this is equivalent to
-calling OPENSSL_clear_free().
+calling OPENSSL_clear_free(). If the argument to OPENSSL_secure_clear_free()
+is NULL, nothing is done.
OPENSSL_secure_actual_size() tells the actual size allocated to the
pointer; implementations may allocate more space than initially
and the proof-of-possession method is set to OSSL_CRMF_POPO_SIGNATURE.
OSSL_CMP_CTX_free() deallocates an OSSL_CMP_CTX structure.
+If the argument is NULL, nothing is done.
OSSL_CMP_CTX_reinit() prepares the given I<ctx> for a further transaction by
clearing the internal CMP transaction (aka session) status, PKIStatusInfo,
I<propq>, both of which may be NULL to select the defaults.
OSSL_CMP_SRV_CTX_free() deletes the given I<srv_ctx>.
+If the argument is NULL, nothing is done.
OSSL_CMP_SRV_CTX_init() sets in the given I<srv_ctx> a custom server context
pointer as well as callback functions performing the specific processing of CMP
OSSL_DECODER_free() decrements the reference count for the given
I<decoder>, and when the count reaches zero, frees it.
+If the argument is NULL, nothing is done.
OSSL_DECODER_get0_provider() returns the provider of the given
I<decoder>.
implementation doesn't recognise should be ignored by it.
OSSL_DECODER_CTX_free() frees the given context I<ctx>.
+If the argument is NULL, nothing is done.
OSSL_DECODER_CTX_add_decoder() populates the B<OSSL_DECODER_CTX> I<ctx> with
a decoder, to be used to attempt to decode some encoded input.
OSSL_ENCODER_free() decrements the reference count for the given
I<encoder>, and when the count reaches zero, frees it.
+If the argument is NULL, nothing is done.
OSSL_ENCODER_get0_provider() returns the provider of the given
I<encoder>.
implementation doesn't recognise should be ignored.
OSSL_ENCODER_CTX_free() frees the given context I<ctx>.
+If the argument is NULL, nothing is done.
OSSL_ENCODER_CTX_add_encoder() populates the B<OSSL_ENCODER_CTX>
I<ctx> with a encoder, to be used to encode an input object.
entries is duplicated on adding to the thread state.
OSSL_ERR_STATE_free() frees the saved error state I<es>.
+If the argument is NULL, nothing is done.
=head1 RETURN VALUES
be set to NULL.
OSSL_HPKE_CTX_free() frees the I<ctx> B<OSSL_HPKE_CTX> that was created
-previously by a call to OSSL_HPKE_CTX_new().
+previously by a call to OSSL_HPKE_CTX_new(). If the argument to
+OSSL_HPKE_CTX_free() is NULL, nothing is done.
=head2 Sender APIs
OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I<rctx>.
The I<rbio> is not free'd, I<wbio> will be free'd if I<free_wbio> is set.
+If the argument is NULL, nothing is done.
OSSL_HTTP_REQ_CTX_set_request_line() adds the 1st HTTP request line to I<rctx>.
The HTTP method is determined by I<method_POST>,
from a configuration.
OSSL_LIB_CTX_free() frees the given I<ctx>, unless it happens to be the
-default OpenSSL library context.
+default OpenSSL library context. If the argument is NULL, nothing is done.
OSSL_LIB_CTX_get0_global_default() returns a concrete (non NULL) reference to
the global default library context.
Any existing values are cleared.
OSSL_PARAM_BLD_free() deallocates the memory allocates by OSSL_PARAM_BLD_new().
+If the argument is NULL, nothing is done.
OSSL_PARAM_BLD_to_param() converts a built up OSSL_PARAM_BLD structure
I<bld> into an allocated OSSL_PARAM array.
OSSL_PARAM_free() frees the parameter array I<params> that was created using
OSSL_PARAM_dup(), OSSL_PARAM_merge() or OSSL_PARAM_BLD_to_param().
+If the argument to OSSL_PARAM_free() is NULL, nothing is done.
=head1 RETURN VALUES
different phases.
OSSL_SELF_TEST_free() frees the space allocated by OSSL_SELF_TEST_new().
+If the argument is NULL, nothing is done.
OSSL_SELF_TEST_onbegin() may be inserted at the start of a block of self test
code. It can be used for diagnostic purposes.
OSSL_STORE_INFO_get_type()) matches the function, otherwise NULL.
OSSL_STORE_INFO_free() frees a B<OSSL_STORE_INFO> and its contained type.
+If the argument is NULL, nothing is done.
OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(),
, OSSL_STORE_INFO_new_PUBKEY(), OSSL_STORE_INFO_new_PKEY(),
OSSL_STORE_LOADER_free() decrements the reference count for the given
I<loader>, and when the count reaches zero, frees it.
+If the argument is NULL, nothing is done.
OSSL_STORE_LOADER_get0_provider() returns the provider of the given
I<loader>.
I<store_loader>.
OSSL_STORE_LOADER_free() frees the given I<store_loader>.
+If the argument is NULL, nothing is done.
OSSL_STORE_register_loader() register the given I<store_loader> and
thereby makes it available for use with OSSL_STORE_open(),
B<OSSL_STORE_SEARCH>.
OSSL_STORE_SEARCH_free() is used to free the B<OSSL_STORE_SEARCH>.
+If the argument is NULL, nothing is done.
=head2 Loader Functions
B<RSA_METHOD> based on an existing one, but with some differences.
RSA_meth_free() destroys an B<RSA_METHOD> structure and frees up any
-memory associated with it.
+memory associated with it. If the argument is NULL, nothing is done.
RSA_meth_get0_name() will return a pointer to the name of this
RSA_METHOD. This is a pointer to the internal name string and so
(TLS extension, X.509 certificate extension or OCSP response). This is not
required for verifying the SCT.
+SCT_free() frees the specified SCT.
+If the argument is NULL, nothing is done.
+
+SCT_LIST_free() frees the specified stack of SCTs.
+If the argument is NULL, nothing is done.
+
=head1 NOTES
Some of the setters return int, instead of void. These will all return 1 on
being used for any operations requiring algorithm fetches.
TS_RESP_CTX_free() frees the B<TS_RESP_CTX> object I<ctx>.
+If the argument is NULL, nothing is done.
=head1 RETURN VALUES
the given B<X509_LOOKUP>.
X509_LOOKUP_free() destructs the given B<X509_LOOKUP>.
+If the argument is NULL, nothing is done.
X509_LOOKUP_set_method_data() and X509_LOOKUP_get_method_data()
associates and retrieves a pointer to application data to and from the
method.
X509_LOOKUP_meth_free() destroys a B<X509_LOOKUP_METHOD> structure.
+If the argument is NULL, nothing is done.
X509_LOOKUP_get_new_item() and X509_LOOKUP_set_new_item() get and set the
function that is called when an B<X509_LOOKUP> object is created with
X509_STORE_unlock() unlocks it.
X509_STORE_free() frees up a single X509_STORE object.
+If the argument is NULL, nothing is done.
=head1 RETURN VALUES
which re-builds the cached data.
B<I<TYPE>_free>() releases the object and all pointers and sub-objects
-within it.
+within it. If the argument is NULL, nothing is done.
B<I<TYPE>_print_ctx>() prints the object I<a> on the specified BIO I<out>.
Each line will be prefixed with I<indent> spaces.
=head1 DESCRIPTION
-The X509 ASN1 allocation routines, allocate and free an
+The X509 ASN1 allocation routines allocate and free an
X509 structure, which represents an X509 certificate.
X509_new_ex() allocates and initializes a X509 structure with a
being used for any X509 operations requiring algorithm fetches.
X509_free() decrements the reference count of B<X509> structure B<a> and
-frees it up if the reference count is zero. If B<a> is NULL nothing is done.
+frees it up if the reference count is zero. If the argument is NULL,
+nothing is done.
X509_up_ref() increments the reference count of B<a>.
OSSL_STACK_OF_X509_free() deallocates the given list of pointers to
certificates after calling X509_free() on all its elements.
+If the argument is NULL, nothing is done.
=head1 NOTES
projects / thirdparty / openssl.git / commitdiff
