From: Vita Batrla Date: Tue, 25 Jun 2024 09:58:49 +0000 (+0200) Subject: docs: document that *_free(NULL) does nothing X-Git-Tag: openssl-3.0.15~76 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=644f869d877deea49e667ef31e9303dde1ea7088;p=thirdparty%2Fopenssl.git docs: document that *_free(NULL) does nothing Explicitly documents that *_free(NULL) does nothing. Fixes two cases where that wasn't true. Fixes #24675. Reviewed-by: Richard Levitte Reviewed-by: Tim Hudson Reviewed-by: Sasa Nedvedicky (Merged from https://github.com/openssl/openssl/pull/24735) (cherry picked from commit 981d129a5609ee2e031367c34c67a9f61a5bfd66) --- diff --git a/crypto/context.c b/crypto/context.c index 548665fba26..ac6938e619e 100644 --- a/crypto/context.c +++ b/crypto/context.c @@ -1,5 +1,5 @@ /* - * Copyright 2019-2022 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 @@ -240,7 +240,7 @@ int OSSL_LIB_CTX_load_config(OSSL_LIB_CTX *ctx, const char *config_file) 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 diff --git a/doc/man3/ASN1_INTEGER_new.pod b/doc/man3/ASN1_INTEGER_new.pod index 4722f880c0b..fb9f3255d81 100644 --- a/doc/man3/ASN1_INTEGER_new.pod +++ b/doc/man3/ASN1_INTEGER_new.pod @@ -18,6 +18,7 @@ ASN1_INTEGER_new, ASN1_INTEGER_free - ASN1_INTEGER allocation functions ASN1_INTEGER_new() returns an allocated B structure. ASN1_INTEGER_free() frees up a single B object. +If the argument is NULL, nothing is done. B structure representing the ASN.1 INTEGER type diff --git a/doc/man3/ASYNC_WAIT_CTX_new.pod b/doc/man3/ASYNC_WAIT_CTX_new.pod index 7621a8b3a16..5293c0af5ed 100644 --- a/doc/man3/ASYNC_WAIT_CTX_new.pod +++ b/doc/man3/ASYNC_WAIT_CTX_new.pod @@ -178,6 +178,9 @@ operation, normally it is detected by a polling function or an interrupt, as the 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 object. +If the argument is NULL, nothing is done. + =head1 RETURN VALUES ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated B diff --git a/doc/man3/BIO_ADDR.pod b/doc/man3/BIO_ADDR.pod index 5ab88622cee..66dfd1f8d17 100644 --- a/doc/man3/BIO_ADDR.pod +++ b/doc/man3/BIO_ADDR.pod @@ -38,6 +38,7 @@ with routines that will fill it with information, such as BIO_accept_ex(). BIO_ADDR_free() frees a B created with BIO_ADDR_new(). +If the argument is NULL, nothing is done. BIO_ADDR_clear() clears any data held within the provided B and sets it back to an uninitialised state. diff --git a/doc/man3/BIO_ADDRINFO.pod b/doc/man3/BIO_ADDRINFO.pod index 626052e7f8b..d42a8340bad 100644 --- a/doc/man3/BIO_ADDRINFO.pod +++ b/doc/man3/BIO_ADDRINFO.pod @@ -78,7 +78,7 @@ BIO_ADDRINFO_next() returns the next B in the chain from the given one. BIO_ADDRINFO_free() frees the chain of B starting -with the given one. +with the given one. If the argument is NULL, nothing is done. =head1 RETURN VALUES diff --git a/doc/man3/BIO_meth_new.pod b/doc/man3/BIO_meth_new.pod index 86301b97189..23b96587b50 100644 --- a/doc/man3/BIO_meth_new.pod +++ b/doc/man3/BIO_meth_new.pod @@ -76,7 +76,7 @@ additionally have the "descriptor" bit set (B). See the L page for more information. BIO_meth_free() destroys a B 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 diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod index b536bcb3b78..51306410e6c 100644 --- a/doc/man3/BN_generate_prime.pod +++ b/doc/man3/BN_generate_prime.pod @@ -167,7 +167,8 @@ programs should prefer the "new" style, whilst the "old" style is provided for backwards compatibility purposes. A B 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 is a B, B is of diff --git a/doc/man3/BUF_MEM_new.pod b/doc/man3/BUF_MEM_new.pod index 262e18f31bf..33ca4dfcc98 100644 --- a/doc/man3/BUF_MEM_new.pod +++ b/doc/man3/BUF_MEM_new.pod @@ -34,6 +34,7 @@ should be allocated on the secure heap; see L. 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. Any data already in the buffer is preserved if it increases in diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod index a51679b97ed..adb1259f238 100644 --- a/doc/man3/CRYPTO_THREAD_run_once.pod +++ b/doc/man3/CRYPTO_THREAD_run_once.pod @@ -69,6 +69,7 @@ CRYPTO_THREAD_unlock() unlocks the previously locked I. =item * CRYPTO_THREAD_lock_free() frees the provided I. +If the argument is NULL, nothing is done. =item * diff --git a/doc/man3/CTLOG_STORE_new.pod b/doc/man3/CTLOG_STORE_new.pod index 801b1447e15..2f1596be425 100644 --- a/doc/man3/CTLOG_STORE_new.pod +++ b/doc/man3/CTLOG_STORE_new.pod @@ -52,7 +52,7 @@ The expected format of the file is: 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 diff --git a/doc/man3/CTLOG_new.pod b/doc/man3/CTLOG_new.pod index 30b80682496..b72c1a42495 100644 --- a/doc/man3/CTLOG_new.pod +++ b/doc/man3/CTLOG_new.pod @@ -50,7 +50,7 @@ property query string are used. 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. diff --git a/doc/man3/CT_POLICY_EVAL_CTX_new.pod b/doc/man3/CT_POLICY_EVAL_CTX_new.pod index bba6778d2de..45ba91bba07 100644 --- a/doc/man3/CT_POLICY_EVAL_CTX_new.pod +++ b/doc/man3/CT_POLICY_EVAL_CTX_new.pod @@ -105,7 +105,8 @@ The time should be in milliseconds since the Unix Epoch. Each setter has a matching getter for accessing the current value. When no longer required, the B 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 diff --git a/doc/man3/DH_meth_new.pod b/doc/man3/DH_meth_new.pod index 43827f55ef8..977ae012413 100644 --- a/doc/man3/DH_meth_new.pod +++ b/doc/man3/DH_meth_new.pod @@ -81,7 +81,7 @@ parameter. This might be useful for creating a new B based on an existing one, but with some differences. DH_meth_free() destroys a B 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 diff --git a/doc/man3/DSA_SIG_new.pod b/doc/man3/DSA_SIG_new.pod index 1f532d30006..7e909f6d676 100644 --- a/doc/man3/DSA_SIG_new.pod +++ b/doc/man3/DSA_SIG_new.pod @@ -20,6 +20,7 @@ DSA_SIG_new() allocates an empty B structure. DSA_SIG_free() frees the B 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 and B values contained in B. diff --git a/doc/man3/DSA_meth_new.pod b/doc/man3/DSA_meth_new.pod index c00747cfc44..7abaa9c6ba7 100644 --- a/doc/man3/DSA_meth_new.pod +++ b/doc/man3/DSA_meth_new.pod @@ -110,7 +110,7 @@ parameter. This might be useful for creating a new B based on an existing one, but with some differences. DSA_meth_free() destroys a B 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 diff --git a/doc/man3/ECDSA_SIG_new.pod b/doc/man3/ECDSA_SIG_new.pod index 3266c43b550..2eecd4ed43c 100644 --- a/doc/man3/ECDSA_SIG_new.pod +++ b/doc/man3/ECDSA_SIG_new.pod @@ -31,6 +31,7 @@ ECDSA_SIG_new() allocates an empty B structure. Note: before OpenSSL 1.1.0, the I and I components were initialised. ECDSA_SIG_free() frees the B structure I. +If the argument is NULL, nothing is done. ECDSA_SIG_get0() returns internal pointers the I and I values contained in I and stores them in I<*pr> and I<*ps>, respectively. diff --git a/doc/man3/ENGINE_add.pod b/doc/man3/ENGINE_add.pod index 55e5d76fcdb..c587f836425 100644 --- a/doc/man3/ENGINE_add.pod +++ b/doc/man3/ENGINE_add.pod @@ -227,7 +227,8 @@ references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), 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 diff --git a/doc/man3/EVP_ASYM_CIPHER_free.pod b/doc/man3/EVP_ASYM_CIPHER_free.pod index c158ec1ae74..ae7a4adc7b3 100644 --- a/doc/man3/EVP_ASYM_CIPHER_free.pod +++ b/doc/man3/EVP_ASYM_CIPHER_free.pod @@ -45,7 +45,7 @@ The returned value must eventually be freed with EVP_ASYM_CIPHER_free(). EVP_ASYM_CIPHER_free() decrements the reference count for the B 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 structure. diff --git a/doc/man3/EVP_CIPHER_meth_new.pod b/doc/man3/EVP_CIPHER_meth_new.pod index 8b862d9d99c..6cf95289c03 100644 --- a/doc/man3/EVP_CIPHER_meth_new.pod +++ b/doc/man3/EVP_CIPHER_meth_new.pod @@ -80,6 +80,7 @@ EVP_CIPHER_meth_new() creates a new B structure. EVP_CIPHER_meth_dup() creates a copy of B. EVP_CIPHER_meth_free() destroys a B 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. diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index d7202c53817..9dedb6dfcf9 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -157,6 +157,7 @@ Increments the reference count for an B structure. Decrements the reference count for the fetched B 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() @@ -170,6 +171,7 @@ existing context. =item EVP_MD_CTX_free() Cleans up digest context I and frees up the space allocated to it. +If the argument is NULL, nothing is done. =item EVP_MD_CTX_ctrl() diff --git a/doc/man3/EVP_EncodeInit.pod b/doc/man3/EVP_EncodeInit.pod index 2b9e02e02d7..2d6e4e8cbfa 100644 --- a/doc/man3/EVP_EncodeInit.pod +++ b/doc/man3/EVP_EncodeInit.pod @@ -41,7 +41,7 @@ EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for the encode/decode functions. EVP_ENCODE_CTX_free() cleans up an encode/decode context B 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 diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 12d7153d0fd..6774a5f7ea7 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -268,6 +268,7 @@ Increments the reference count for an B structure. Decrements the reference count for the fetched B 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() @@ -276,9 +277,9 @@ Allocates and returns a cipher context. =item EVP_CIPHER_CTX_free() Clears all information from a cipher context and frees any allocated memory -associated with it, including I 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 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_ctrl() diff --git a/doc/man3/EVP_KEM_free.pod b/doc/man3/EVP_KEM_free.pod index 575abc5f579..8ddd6dcf645 100644 --- a/doc/man3/EVP_KEM_free.pod +++ b/doc/man3/EVP_KEM_free.pod @@ -41,6 +41,7 @@ The returned value must eventually be freed with EVP_KEM_free(). EVP_KEM_free() decrements the reference count for the B 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 structure. diff --git a/doc/man3/EVP_KEYEXCH_free.pod b/doc/man3/EVP_KEYEXCH_free.pod index 272855ccb3d..21e097d079b 100644 --- a/doc/man3/EVP_KEYEXCH_free.pod +++ b/doc/man3/EVP_KEYEXCH_free.pod @@ -41,7 +41,7 @@ The returned value must eventually be freed with EVP_KEYEXCH_free(). EVP_KEYEXCH_free() decrements the reference count for the B 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 structure. diff --git a/doc/man3/EVP_KEYMGMT.pod b/doc/man3/EVP_KEYMGMT.pod index 455ffadce5e..e37df52860e 100644 --- a/doc/man3/EVP_KEYMGMT.pod +++ b/doc/man3/EVP_KEYMGMT.pod @@ -62,6 +62,7 @@ B I. EVP_KEYMGMT_free() decrements the reference count for the given B I, 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. diff --git a/doc/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod index a553c378f3d..9ddc0001ab5 100644 --- a/doc/man3/EVP_MD_meth_new.pod +++ b/doc/man3/EVP_MD_meth_new.pod @@ -74,6 +74,7 @@ EVP_MD_meth_dup() creates a copy of B. EVP_MD_meth_free() decrements the reference count for the B 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 to B bytes. diff --git a/doc/man3/EVP_PKEY_ASN1_METHOD.pod b/doc/man3/EVP_PKEY_ASN1_METHOD.pod index cc50d363daf..637fd480101 100644 --- a/doc/man3/EVP_PKEY_ASN1_METHOD.pod +++ b/doc/man3/EVP_PKEY_ASN1_METHOD.pod @@ -393,7 +393,7 @@ This function is not thread safe, it's recommended to only use this when initializing the application. EVP_PKEY_asn1_free() frees an existing B pointed -by B. +by B. If the argument is NULL, nothing is done. EVP_PKEY_asn1_add0() adds B to the user defined stack of methods unless another B with the same NID is diff --git a/doc/man3/EVP_PKEY_meth_new.pod b/doc/man3/EVP_PKEY_meth_new.pod index db0b09f855f..45f868d04d8 100644 --- a/doc/man3/EVP_PKEY_meth_new.pod +++ b/doc/man3/EVP_PKEY_meth_new.pod @@ -407,7 +407,7 @@ of an B is always called by the EVP framework while doing a digest signing operation by calling L. EVP_PKEY_meth_free() frees an existing B pointed by -B. +B. If the argument is NULL, nothing is done. EVP_PKEY_meth_copy() copies an B object from B to B. diff --git a/doc/man3/EVP_SIGNATURE.pod b/doc/man3/EVP_SIGNATURE.pod index 1f534ef3381..9a1bc31a403 100644 --- a/doc/man3/EVP_SIGNATURE.pod +++ b/doc/man3/EVP_SIGNATURE.pod @@ -49,7 +49,7 @@ The returned value must eventually be freed with EVP_SIGNATURE_free(). EVP_SIGNATURE_free() decrements the reference count for the B 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 structure. diff --git a/doc/man3/HMAC.pod b/doc/man3/HMAC.pod index 87a567242f6..b0c640d32e0 100644 --- a/doc/man3/HMAC.pod +++ b/doc/man3/HMAC.pod @@ -87,7 +87,7 @@ created with HMAC_CTX_new(). HMAC_CTX_free() erases the key and other data from the B, releases any associated resources and finally frees the B -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: diff --git a/doc/man3/NCONF_new_ex.pod b/doc/man3/NCONF_new_ex.pod index 6861fb198c1..394dbd82d46 100644 --- a/doc/man3/NCONF_new_ex.pod +++ b/doc/man3/NCONF_new_ex.pod @@ -35,7 +35,7 @@ I is set to NULL then the default value of NCONF_default() is used. NCONF_new() is similar to NCONF_new_ex() but sets the I to NULL. NCONF_free() frees the data associated with I and then frees the I -object. +object. If the argument is NULL, nothing is done. NCONF_load() parses the file named I and adds the values found to I. If an error occurs I and I list the file and line that diff --git a/doc/man3/OCSP_REQUEST_new.pod b/doc/man3/OCSP_REQUEST_new.pod index e34e591fe01..28779fb07d6 100644 --- a/doc/man3/OCSP_REQUEST_new.pod +++ b/doc/man3/OCSP_REQUEST_new.pod @@ -29,6 +29,7 @@ OCSP_request_onereq_get0 - OCSP request functions OCSP_REQUEST_new() allocates and returns an empty B structure. OCSP_REQUEST_free() frees up the request structure B. +If the argument is NULL, nothing is done. OCSP_request_add0_id() adds certificate ID B to B. It returns the B structure added so an application can add additional diff --git a/doc/man3/OCSP_cert_to_id.pod b/doc/man3/OCSP_cert_to_id.pod index 298527f6bb2..abf07db109e 100644 --- a/doc/man3/OCSP_cert_to_id.pod +++ b/doc/man3/OCSP_cert_to_id.pod @@ -38,6 +38,7 @@ issuer name B, issuer key hash B and serial number B. OCSP_CERTID_free() frees up B. +If the argument is NULL, nothing is done. OCSP_id_cmp() compares B B and B. diff --git a/doc/man3/OCSP_response_status.pod b/doc/man3/OCSP_response_status.pod index 7ff74923a53..a7402540b28 100644 --- a/doc/man3/OCSP_response_status.pod +++ b/doc/man3/OCSP_response_status.pod @@ -46,6 +46,7 @@ OCSP_response_create() creates and returns an I structure for I and optionally including basic response I. OCSP_RESPONSE_free() frees up OCSP response I. +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 for the OCSP responder. diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod index 688ef0edcb9..2d352fa137e 100644 --- a/doc/man3/OPENSSL_LH_COMPFUNC.pod +++ b/doc/man3/OPENSSL_LH_COMPFUNC.pod @@ -123,7 +123,7 @@ Then a hash table of B> objects can be created using this: B_free>() frees the B(B>) structure I. Allocated hash table entries will not be freed; consider using B_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_flush>() empties the B(B>) structure I
. New entries can be added to the flushed table. Allocated hash table entries diff --git a/doc/man3/OPENSSL_init_crypto.pod b/doc/man3/OPENSSL_init_crypto.pod index c3e72d27442..12f3c6864fe 100644 --- a/doc/man3/OPENSSL_init_crypto.pod +++ b/doc/man3/OPENSSL_init_crypto.pod @@ -249,6 +249,7 @@ If the B flag is not included, any errors in the configuration file will cause an error return from B or indirectly L. 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 diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 76751012bde..4f292101957 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -99,7 +99,8 @@ OPENSSL_zalloc() calls memset() to zero the memory before returning. OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used when the buffer at B 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 of size B with a string of 0's. Use OPENSSL_cleanse() with care if the memory is a mapping of a file. diff --git a/doc/man3/OPENSSL_secure_malloc.pod b/doc/man3/OPENSSL_secure_malloc.pod index c5d4bb2dbbb..cd18753d6fc 100644 --- a/doc/man3/OPENSSL_secure_malloc.pod +++ b/doc/man3/OPENSSL_secure_malloc.pod @@ -82,13 +82,15 @@ If CRYPTO_secure_malloc_init() is not called, this is equivalent to 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 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 diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod index 5b106a8ad08..c201b78c83b 100644 --- a/doc/man3/OSSL_CMP_CTX_new.pod +++ b/doc/man3/OSSL_CMP_CTX_new.pod @@ -176,6 +176,7 @@ the message timeout is set to 120 seconds, 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 for a further transaction by clearing the internal CMP transaction (aka session) status, PKIStatusInfo, diff --git a/doc/man3/OSSL_CMP_SRV_CTX_new.pod b/doc/man3/OSSL_CMP_SRV_CTX_new.pod index d7f1a2e4dba..89749615ebe 100644 --- a/doc/man3/OSSL_CMP_SRV_CTX_new.pod +++ b/doc/man3/OSSL_CMP_SRV_CTX_new.pod @@ -104,6 +104,7 @@ associated with the library context I and property query string I, both of which may be NULL to select the defaults. OSSL_CMP_SRV_CTX_free() deletes the given I. +If the argument is NULL, nothing is done. OSSL_CMP_SRV_CTX_init() sets in the given I a custom server context pointer as well as callback functions performing the specific processing of CMP diff --git a/doc/man3/OSSL_DECODER.pod b/doc/man3/OSSL_DECODER.pod index dcfd72bf973..0a923b8a8c1 100644 --- a/doc/man3/OSSL_DECODER.pod +++ b/doc/man3/OSSL_DECODER.pod @@ -61,6 +61,7 @@ I. OSSL_DECODER_free() decrements the reference count for the given I, 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. diff --git a/doc/man3/OSSL_DECODER_CTX.pod b/doc/man3/OSSL_DECODER_CTX.pod index 3ffd794cf0f..de7c22b61e7 100644 --- a/doc/man3/OSSL_DECODER_CTX.pod +++ b/doc/man3/OSSL_DECODER_CTX.pod @@ -126,6 +126,7 @@ decoders that have been added to the I so far. Parameters that an implementation doesn't recognise should be ignored by it. OSSL_DECODER_CTX_free() frees the given context I. +If the argument is NULL, nothing is done. OSSL_DECODER_CTX_add_decoder() populates the B I with a decoder, to be used to attempt to decode some encoded input. diff --git a/doc/man3/OSSL_ENCODER.pod b/doc/man3/OSSL_ENCODER.pod index 06d8f80f881..f96ea2ae7be 100644 --- a/doc/man3/OSSL_ENCODER.pod +++ b/doc/man3/OSSL_ENCODER.pod @@ -61,6 +61,7 @@ I. OSSL_ENCODER_free() decrements the reference count for the given I, 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. diff --git a/doc/man3/OSSL_ENCODER_CTX.pod b/doc/man3/OSSL_ENCODER_CTX.pod index 7f3915fda88..4d0320e78b4 100644 --- a/doc/man3/OSSL_ENCODER_CTX.pod +++ b/doc/man3/OSSL_ENCODER_CTX.pod @@ -102,6 +102,7 @@ with an L array I. Parameters that the implementation doesn't recognise should be ignored. OSSL_ENCODER_CTX_free() frees the given context I. +If the argument is NULL, nothing is done. OSSL_ENCODER_CTX_add_encoder() populates the B I with a encoder, to be used to encode an input object. diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod index 6216420e4ff..8716d8e7c9f 100644 --- a/doc/man3/OSSL_HTTP_REQ_CTX.pod +++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod @@ -71,6 +71,7 @@ which collects the HTTP request header lines. OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I. The I is not free'd, I will be free'd if I 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. The HTTP method is determined by I, diff --git a/doc/man3/OSSL_LIB_CTX.pod b/doc/man3/OSSL_LIB_CTX.pod index 45fdd8f39a6..fc205b33da3 100644 --- a/doc/man3/OSSL_LIB_CTX.pod +++ b/doc/man3/OSSL_LIB_CTX.pod @@ -88,7 +88,7 @@ This can be used to associate a library context with providers that are loaded from a configuration. OSSL_LIB_CTX_free() frees the given I, 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. diff --git a/doc/man3/OSSL_PARAM_BLD.pod b/doc/man3/OSSL_PARAM_BLD.pod index 455761c20d3..63e8eccb8c5 100644 --- a/doc/man3/OSSL_PARAM_BLD.pod +++ b/doc/man3/OSSL_PARAM_BLD.pod @@ -53,6 +53,7 @@ so that values can be added. 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 into an allocated OSSL_PARAM array. diff --git a/doc/man3/OSSL_PARAM_dup.pod b/doc/man3/OSSL_PARAM_dup.pod index 4ae33faf1e4..dbaeed9a533 100644 --- a/doc/man3/OSSL_PARAM_dup.pod +++ b/doc/man3/OSSL_PARAM_dup.pod @@ -32,6 +32,7 @@ array that have the same key. OSSL_PARAM_free() frees the parameter array I 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 diff --git a/doc/man3/OSSL_SELF_TEST_new.pod b/doc/man3/OSSL_SELF_TEST_new.pod index 4c4b10fca96..dbacf9556a3 100644 --- a/doc/man3/OSSL_SELF_TEST_new.pod +++ b/doc/man3/OSSL_SELF_TEST_new.pod @@ -32,6 +32,7 @@ The callback I may be triggered multiple times by a self test to indicate 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. diff --git a/doc/man3/OSSL_STORE_INFO.pod b/doc/man3/OSSL_STORE_INFO.pod index 39bb93fbf5f..546ec54c70c 100644 --- a/doc/man3/OSSL_STORE_INFO.pod +++ b/doc/man3/OSSL_STORE_INFO.pod @@ -101,6 +101,7 @@ holds if the B type (as returned by OSSL_STORE_INFO_get_type()) matches the function, otherwise NULL. OSSL_STORE_INFO_free() frees a B 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(), diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod index e8c8a29aacc..fe19d985388 100644 --- a/doc/man3/OSSL_STORE_LOADER.pod +++ b/doc/man3/OSSL_STORE_LOADER.pod @@ -125,6 +125,7 @@ I. OSSL_STORE_LOADER_free() decrements the reference count for the given I, 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. @@ -296,6 +297,7 @@ OSSL_STORE_LOADER_set_close() sets the closing function for the I. OSSL_STORE_LOADER_free() frees the given I. +If the argument is NULL, nothing is done. OSSL_STORE_register_loader() register the given I and thereby makes it available for use with OSSL_STORE_open(), diff --git a/doc/man3/OSSL_STORE_SEARCH.pod b/doc/man3/OSSL_STORE_SEARCH.pod index 79186b08997..021ed0c8baa 100644 --- a/doc/man3/OSSL_STORE_SEARCH.pod +++ b/doc/man3/OSSL_STORE_SEARCH.pod @@ -75,6 +75,7 @@ criterion, so they must have at least the same life time as the created B. OSSL_STORE_SEARCH_free() is used to free the B. +If the argument is NULL, nothing is done. =head2 Loader Functions diff --git a/doc/man3/RSA_meth_new.pod b/doc/man3/RSA_meth_new.pod index 29ea4161b0b..b5cfd43b6ed 100644 --- a/doc/man3/RSA_meth_new.pod +++ b/doc/man3/RSA_meth_new.pod @@ -147,7 +147,7 @@ passed as a parameter. This might be useful for creating a new B based on an existing one, but with some differences. RSA_meth_free() destroys an B 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 diff --git a/doc/man3/SCT_new.pod b/doc/man3/SCT_new.pod index 23576272199..ecaa25e1d22 100644 --- a/doc/man3/SCT_new.pod +++ b/doc/man3/SCT_new.pod @@ -166,6 +166,12 @@ SCT_set_source() can be used to record where the SCT was found (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 diff --git a/doc/man3/TS_RESP_CTX_new.pod b/doc/man3/TS_RESP_CTX_new.pod index 725a1921d13..3b5bfc65ba7 100644 --- a/doc/man3/TS_RESP_CTX_new.pod +++ b/doc/man3/TS_RESP_CTX_new.pod @@ -27,6 +27,7 @@ and property query to NULL. This results in the default (NULL) library context being used for any operations requiring algorithm fetches. TS_RESP_CTX_free() frees the B object I. +If the argument is NULL, nothing is done. =head1 RETURN VALUES diff --git a/doc/man3/X509_LOOKUP.pod b/doc/man3/X509_LOOKUP.pod index 4d2fe38f25a..d086d1b35c5 100644 --- a/doc/man3/X509_LOOKUP.pod +++ b/doc/man3/X509_LOOKUP.pod @@ -85,6 +85,7 @@ X509_LOOKUP_shutdown() tears down the internal state and resources of the given B. X509_LOOKUP_free() destructs the given B. +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 diff --git a/doc/man3/X509_LOOKUP_meth_new.pod b/doc/man3/X509_LOOKUP_meth_new.pod index 20217499356..baaccd5220b 100644 --- a/doc/man3/X509_LOOKUP_meth_new.pod +++ b/doc/man3/X509_LOOKUP_meth_new.pod @@ -110,6 +110,7 @@ be given a human-readable string containing a brief description of the lookup method. X509_LOOKUP_meth_free() destroys a B 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 object is created with diff --git a/doc/man3/X509_STORE_new.pod b/doc/man3/X509_STORE_new.pod index 31d466faa42..63c37e9530b 100644 --- a/doc/man3/X509_STORE_new.pod +++ b/doc/man3/X509_STORE_new.pod @@ -27,6 +27,7 @@ X509_STORE_lock() locks the store from modification by other threads, 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 diff --git a/doc/man3/X509_dup.pod b/doc/man3/X509_dup.pod index 849364e2aae..c8dd79ff71b 100644 --- a/doc/man3/X509_dup.pod +++ b/doc/man3/X509_dup.pod @@ -367,7 +367,7 @@ followed by I, which re-builds the cached data. B_free>() releases the object and all pointers and sub-objects -within it. +within it. If the argument is NULL, nothing is done. B_print_ctx>() prints the object I on the specified BIO I. Each line will be prefixed with I spaces. diff --git a/doc/man3/X509_new.pod b/doc/man3/X509_new.pod index ea2b3a2cc9b..0e19a76fb1d 100644 --- a/doc/man3/X509_new.pod +++ b/doc/man3/X509_new.pod @@ -18,7 +18,7 @@ X509_chain_up_ref - X509 certificate ASN1 allocation functions =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 @@ -33,7 +33,8 @@ and property query to NULL. This results in the default (NULL) library context being used for any X509 operations requiring algorithm fetches. X509_free() decrements the reference count of B structure B and -frees it up if the reference count is zero. If B 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.