The branch master has been updated via 636a93454db40fa56e0927403fd34795aa268baf (commit) via 510d01914126947f409ddb51a3660c2196921b58 (commit) via 18b207c798b1ce1a760015d17150130269fa3110 (commit) via 7e1d7fea395654fd169bdb3d01b2f56236ed13c1 (commit) via bc4d84abce0e08e84078f9113c2f3d555b52d317 (commit) from 6ceaf67257bb33544867d0faa2d0c50ec862eba2 (commit)
- Log ----------------------------------------------------------------- commit 636a93454db40fa56e0927403fd34795aa268baf Author: Matt Caswell <m...@openssl.org> Date: Thu Feb 18 11:44:52 2021 +0000 Note that the OSSL_CORE_MAKE_FUNC macro is reserved The OSSL_CORE_MAKE_FUNC macro has been added since 1.1.1 and is undocumented. However it is not intended for application use and so we document it as "reserved". Fixes #13192 Reviewed-by: Paul Dale <pa...@openssl.org> Reviewed-by: Tomas Mraz <to...@openssl.org> Reviewed-by: Richard Levitte <levi...@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14232) commit 510d01914126947f409ddb51a3660c2196921b58 Author: Matt Caswell <m...@openssl.org> Date: Wed Feb 17 17:41:10 2021 +0000 Document the OSSL_PARAM_DEFN macro This macro was added since 1.1.1 and was undocumented. Reviewed-by: Paul Dale <pa...@openssl.org> Reviewed-by: Tomas Mraz <to...@openssl.org> Reviewed-by: Richard Levitte <levi...@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14232) commit 18b207c798b1ce1a760015d17150130269fa3110 Author: Matt Caswell <m...@openssl.org> Date: Wed Feb 17 17:22:35 2021 +0000 Add documentation for the macro OPENSSL_VERSION_PREREQ This macro was added since 1.1.1 but had no associated documentation. Reviewed-by: Paul Dale <pa...@openssl.org> Reviewed-by: Tomas Mraz <to...@openssl.org> Reviewed-by: Richard Levitte <levi...@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14232) commit 7e1d7fea395654fd169bdb3d01b2f56236ed13c1 Author: Matt Caswell <m...@openssl.org> Date: Wed Feb 17 17:06:41 2021 +0000 Document OPENSSL_LH_flush() The function OPENSSL_LH_flush() was added since 1.1.1 and was undocumented. We also add documentation for some other OPENSSL_LH_*() functions at the same time. Reviewed-by: Paul Dale <pa...@openssl.org> Reviewed-by: Tomas Mraz <to...@openssl.org> Reviewed-by: Richard Levitte <levi...@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14232) commit bc4d84abce0e08e84078f9113c2f3d555b52d317 Author: Matt Caswell <m...@openssl.org> Date: Wed Feb 17 16:37:40 2021 +0000 Suppress errors about undocumented asn1_d2i_read_bio asn1_d2i_read_bio is exported by libcrypto but is only intended for internal usage, and does not exist in our public headers. Therefore we suppress errors about it being a newly added undocumented symbol. Reviewed-by: Paul Dale <pa...@openssl.org> Reviewed-by: Tomas Mraz <to...@openssl.org> Reviewed-by: Richard Levitte <levi...@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14232) ----------------------------------------------------------------------- Summary of changes: doc/man3/OPENSSL_LH_COMPFUNC.pod | 74 +++++++++++++++++++++++++++++----------- doc/man3/OSSL_CORE_MAKE_FUNC.pod | 38 +++++++++++++++++++++ doc/man3/OSSL_PARAM_int.pod | 37 ++++++++++++-------- doc/man3/OpenSSL_version.pod | 16 ++++++--- include/openssl/core_dispatch.h | 2 ++ util/missingcrypto.txt | 9 ----- util/missingmacro.txt | 2 -- util/other-internal.syms | 2 ++ util/other.syms | 2 ++ 9 files changed, 133 insertions(+), 49 deletions(-) create mode 100644 doc/man3/OSSL_CORE_MAKE_FUNC.pod diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod index 3873ac0031..c109601597 100644 --- a/doc/man3/OPENSSL_LH_COMPFUNC.pod +++ b/doc/man3/OPENSSL_LH_COMPFUNC.pod @@ -8,7 +8,11 @@ LHASH_DOALL_ARG_FN_TYPE, IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN, lh_TYPE_new, lh_TYPE_free, lh_TYPE_flush, lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, -lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table +lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error, +OPENSSL_LH_new, OPENSSL_LH_free, OPENSSL_LH_flush, +OPENSSL_LH_insert, OPENSSL_LH_delete, OPENSSL_LH_retrieve, +OPENSSL_LH_doall, OPENSSL_LH_doall_arg, OPENSSL_LH_error +- dynamic hash table =head1 SYNOPSIS @@ -18,7 +22,7 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table DECLARE_LHASH_OF(TYPE); - LHASH *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare); + LHASH_OF(TYPE) *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare); void lh_TYPE_free(LHASH_OF(TYPE) *table); void lh_TYPE_flush(LHASH_OF(TYPE) *table); @@ -37,6 +41,19 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table typedef void (*OPENSSL_LH_DOALL_FUNC)(const void *); typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); + OPENSSL_LHASH *OPENSSL_LH_new(OPENSSL_LH_HASHFUNC h, OPENSSL_LH_COMPFUNC c); + void OPENSSL_LH_free(OPENSSL_LHASH *lh); + void OPENSSL_LH_flush(OPENSSL_LHASH *lh); + + void *OPENSSL_LH_insert(OPENSSL_LHASH *lh, void *data); + void *OPENSSL_LH_delete(OPENSSL_LHASH *lh, const void *data); + void *OPENSSL_LH_retrieve(OPENSSL_LHASH *lh, const void *data); + + void OPENSSL_LH_doall(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNC func); + void OPENSSL_LH_doall_arg(OPENSSL_LHASH *lh, OPENSSL_LH_DOALL_FUNCARG func, void *arg); + + int OPENSSL_LH_error(OPENSSL_LHASH *lh); + =head1 DESCRIPTION This library implements type-checked dynamic hash tables. The hash @@ -162,34 +179,50 @@ that is provided by the caller): B<lh_I<TYPE>_error>() can be used to determine if an error occurred in the last operation. +OPENSSL_LH_new() is the same as the B<lh_I<TYPE>_new>() except that it is not +type specific. So instead of returning an B<LHASH_OF(I<TYPE>)> value it returns +a B<void *>. In the same way the functions OPENSSL_LH_free(), +OPENSSL_LH_flush(), OPENSSL_LH_insert(), OPENSSL_LH_delete(), +OPENSSL_LH_retrieve(), OPENSSL_LH_doall(), OPENSSL_LH_doall_arg(), and +OPENSSL_LH_error() are equivalent to the similarly named B<lh_I<TYPE>> functions +except that they return or use a B<void *> where the equivalent B<lh_I<TYPE>> +function returns or uses a B<I<TYPE> *> or B<LHASH_OF(I<TYPE>) *>. B<lh_I<TYPE>> +functions are implemented as type checked wrappers around the B<OPENSSL_LH> +functions. Most applications should not call the B<OPENSSL_LH> functions +directly. + =head1 RETURN VALUES -B<lh_I<TYPE>_new>() returns NULL on error, otherwise a pointer to the new -B<LHASH> structure. +B<lh_I<TYPE>_new>() and OPENSSL_LH_new() return NULL on error, otherwise a +pointer to the new B<LHASH> structure. -When a hash table entry is replaced, B<lh_I<TYPE>_insert>() returns the value -being replaced. NULL is returned on normal operation and on error. +When a hash table entry is replaced, B<lh_I<TYPE>_insert>() or +OPENSSL_LH_insert() return the value being replaced. NULL is returned on normal +operation and on error. -B<lh_I<TYPE>_delete>() returns the entry being deleted. NULL is returned if -there is no such value in the hash table. +B<lh_I<TYPE>_delete>() and OPENSSL_LH_delete() return the entry being deleted. +NULL is returned if there is no such value in the hash table. -B<lh_I<TYPE>_retrieve>() returns the hash table entry if it has been found, -NULL otherwise. +B<lh_I<TYPE>_retrieve>() and OPENSSL_LH_retrieve() return the hash table entry +if it has been found, NULL otherwise. -B<lh_I<TYPE>_error>() returns 1 if an error occurred in the last operation, 0 -otherwise. It's meaningful only after non-retrieve operations. +B<lh_I<TYPE>_error>() and OPENSSL_LH_error() return 1 if an error occurred in +the last operation, 0 otherwise. It's meaningful only after non-retrieve +operations. -B<lh_I<TYPE>_free>(), B<lh_I<TYPE>_flush>(), B<lh_I<TYPE>_doall>() and -B<lh_I<TYPE>_doall_arg>() return no values. +B<lh_I<TYPE>_free>(), OPENSSL_LH_free(), B<lh_I<TYPE>_flush>(), +OPENSSL_LH_flush(), B<lh_I<TYPE>_doall>() OPENSSL_LH_doall(), +B<lh_I<TYPE>_doall_arg>() and OPENSSL_LH_doall_arg() return no values. =head1 NOTE The LHASH code is not thread safe. All updating operations, as well as -B<lh_I<TYPE>_error>() call must be performed under a write lock. All retrieve -operations should be performed under a read lock, I<unless> accurate -usage statistics are desired. In which case, a write lock should be used -for retrieve operations as well. For output of the usage statistics, -using the functions from L<OPENSSL_LH_stats(3)>, a read lock suffices. +B<lh_I<TYPE>_error>() or OPENSSL_LH_error() calls must be performed under +a write lock. All retrieve operations should be performed under a read lock, +I<unless> accurate usage statistics are desired. In which case, a write lock +should be used for retrieve operations as well. For output of the usage +statistics, using the functions from L<OPENSSL_LH_stats(3)>, a read lock +suffices. The LHASH code regards table entries as constant data. As such, it internally represents lh_insert()'d items with a "const void *" @@ -223,7 +256,8 @@ without any "const" qualifiers. =head1 BUGS -B<lh_I<TYPE>_insert>() returns NULL both for success and error. +B<lh_I<TYPE>_insert>() and OPENSSL_LH_insert() return NULL both for success +and error. =head1 SEE ALSO diff --git a/doc/man3/OSSL_CORE_MAKE_FUNC.pod b/doc/man3/OSSL_CORE_MAKE_FUNC.pod new file mode 100644 index 0000000000..409c19db62 --- /dev/null +++ b/doc/man3/OSSL_CORE_MAKE_FUNC.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +OSSL_CORE_MAKE_FUNC - OpenSSL reserved symbols + +=head1 SYNOPSIS + + #include <openssl/core_dispatch.h> + + #define OSSL_CORE_MAKE_FUNC(type,name,args) + +=head1 DESCRIPTION + +There are certain macros that may appear in OpenSSL header files that are +reserved for internal use. They should not be used by applications or assumed +to exist. + +All the macros listed in the synopsis above are reserved. + +=head1 RETURN VALUES + +Not applicable. + +=head1 HISTORY + +The macros described here were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2021 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 +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod index 25b87014b7..4f482ee610 100644 --- a/doc/man3/OSSL_PARAM_int.pod +++ b/doc/man3/OSSL_PARAM_int.pod @@ -7,7 +7,7 @@ OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint, OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr, -OSSL_PARAM_END, +OSSL_PARAM_END, OSSL_PARAM_DEFN, OSSL_PARAM_construct_double, OSSL_PARAM_construct_int, OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64, OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t, @@ -58,6 +58,9 @@ OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified #define OSSL_PARAM_UNMODIFIED + #define OSSL_PARAM_DEFN(key, type, addr, sz) \ + { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED } + OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf); OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, size_t bsize); @@ -107,7 +110,7 @@ OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified =head1 DESCRIPTION A collection of utility functions that simplify and add type safety to the -OSSL_PARAM arrays. The following B<I<TYPE>> names are supported: +B<OSSL_PARAM> arrays. The following B<I<TYPE>> names are supported: =over 1 @@ -158,7 +161,7 @@ unsigned long int (ulong) =back OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an -array of OSSL_PARAM structures. +array of B<OSSL_PARAM> structures. Each of these macros defines a parameter of the specified B<I<TYPE>> with the provided I<key> and parameter variable I<address>. @@ -169,40 +172,46 @@ A parameter with name I<key> is defined. The storage for this parameter is at I<address> and is of I<size> bytes. OSSL_PARAM_END provides an end of parameter list marker. -This should terminate all OSSL_PARAM arrays. +This should terminate all B<OSSL_PARAM> arrays. + +The OSSL_PARAM_DEFN() macro provides the ability to construct a single +B<OSSL_PARAM> (typically used in the construction of B<OSSL_PARAM> arrays). The +I<key>, I<type>, I<addr> and I<sz> arguments correspond to the I<key>, +I<data_type>, I<data> and I<data_size> fields of the B<OSSL_PARAM> structure as +described on the L<OSSL_PARAM(3)> page. -OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM +OSSL_PARAM_construct_TYPE() are a series of functions that create B<OSSL_PARAM> records dynamically. A parameter with name I<key> is created. The parameter will use storage pointed to by I<buf> and return size of I<ret>. OSSL_PARAM_construct_BN() is a function that constructs a large integer -OSSL_PARAM structure. +B<OSSL_PARAM> structure. A parameter with name I<key>, storage I<buf>, size I<bsize> and return size I<rsize> is created. OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 -string OSSL_PARAM structure. +string B<OSSL_PARAM> structure. A parameter with name I<key>, storage I<buf> and size I<bsize> is created. If I<bsize> is zero, the string length is determined using strlen(3). Generally pass zero for I<bsize> instead of calling strlen(3) yourself. OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET -string OSSL_PARAM structure. +string B<OSSL_PARAM> structure. A parameter with name I<key>, storage I<buf> and size I<bsize> is created. OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF string -pointer OSSL_PARAM structure. +pointer B<OSSL_PARAM> structure. A parameter with name I<key>, storage pointer I<*buf> and size I<bsize> is created. OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string -pointer OSSL_PARAM structure. +pointer B<OSSL_PARAM> structure. A parameter with name I<key>, storage pointer I<*buf> and size I<bsize> is created. OSSL_PARAM_construct_end() is a function that constructs the terminating -OSSL_PARAM structure. +B<OSSL_PARAM> structure. OSSL_PARAM_locate() is a function that searches an I<array> of parameters for the one matching the I<key> name. @@ -299,10 +308,10 @@ in the array I<params>. OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() -return a populated OSSL_PARAM structure. +return a populated B<OSSL_PARAM> structure. OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to -the matching OSSL_PARAM object. They return NULL on error or when +the matching B<OSSL_PARAM> object. They return NULL on error or when no object matching I<key> exists in the I<array>. OSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise. @@ -326,7 +335,7 @@ possible purposes. =head1 EXAMPLES Reusing the examples from L<OSSL_PARAM(3)> to just show how -C<OSSL_PARAM> arrays can be handled using the macros and functions +B<OSSL_PARAM> arrays can be handled using the macros and functions defined herein. =head2 Example 1 diff --git a/doc/man3/OpenSSL_version.pod b/doc/man3/OpenSSL_version.pod index a4ef1cfbaf..e28a35e73a 100644 --- a/doc/man3/OpenSSL_version.pod +++ b/doc/man3/OpenSSL_version.pod @@ -4,10 +4,10 @@ OPENSSL_VERSION_MAJOR, OPENSSL_VERSION_MINOR, OPENSSL_VERSION_PATCH, OPENSSL_VERSION_PRE_RELEASE, OPENSSL_VERSION_BUILD_METADATA, -OPENSSL_VERSION_TEXT, -OPENSSL_version_major, OPENSSL_version_minor, OPENSSL_version_patch, -OPENSSL_version_pre_release, OPENSSL_version_build_metadata, OpenSSL_version, -OPENSSL_VERSION_NUMBER, OpenSSL_version_num, OPENSSL_info +OPENSSL_VERSION_TEXT, OPENSSL_VERSION_PREREQ, OPENSSL_version_major, +OPENSSL_version_minor, OPENSSL_version_patch, OPENSSL_version_pre_release, +OPENSSL_version_build_metadata, OpenSSL_version, OPENSSL_VERSION_NUMBER, +OpenSSL_version_num, OPENSSL_info - get OpenSSL version number and other information =head1 SYNOPSIS @@ -24,6 +24,8 @@ OPENSSL_VERSION_NUMBER, OpenSSL_version_num, OPENSSL_info #define OPENSSL_VERSION_TEXT "OpenSSL x.y.z xx XXX xxxx" + #define OPENSSL_VERSION_PREREQ(maj,min) + #include <openssl/crypto.h> unsigned int OPENSSL_version_major(void); @@ -73,6 +75,12 @@ B<OPENSSL_VERSION_TEXT> is a convenience macro to get a full descriptive version text, which includes B<OPENSSL_FULL_VERSION_STR> and the release date. +B<OPENSSL_VERSION_PREREQ> is a useful macro for checking whether the OpenSSL +version for the headers in use is at least at the given pre-requisite major +(B<maj>) and minor (B<min>) number or not. It will evaluate to true if the +header version number (B<OPENSSL_VERSION_MAJOR>.B<OPENSSL_VERSION_MINOR>) is +greater than or equal to B<maj>.B<min>. + =head2 Functions OPENSSL_version_major(), OPENSSL_version_minor(), OPENSSL_version_patch(), diff --git a/include/openssl/core_dispatch.h b/include/openssl/core_dispatch.h index c4e109156f..6f12d6fecf 100644 --- a/include/openssl/core_dispatch.h +++ b/include/openssl/core_dispatch.h @@ -41,6 +41,8 @@ extern "C" { * |type| is the return-type of the function, |name| is the name of the * function to fetch, and |args| is a parenthesized list of parameters * for the function (that is, it is |name|'s function signature). + * Note: This is considered a "reserved" internal macro. Applications should + * not use this or assume its existence. */ #define OSSL_CORE_MAKE_FUNC(type,name,args) \ typedef type (OSSL_FUNC_##name##_fn)args; \ diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index 85f03fc9cc..61d91b0c92 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -837,17 +837,8 @@ OCSP_response_status_str(3) OCSP_url_svcloc_new(3) OPENSSL_DIR_end(3) OPENSSL_DIR_read(3) -OPENSSL_LH_delete(3) -OPENSSL_LH_doall(3) -OPENSSL_LH_doall_arg(3) -OPENSSL_LH_error(3) -OPENSSL_LH_flush(3) -OPENSSL_LH_free(3) OPENSSL_LH_get_down_load(3) -OPENSSL_LH_insert(3) -OPENSSL_LH_new(3) OPENSSL_LH_num_items(3) -OPENSSL_LH_retrieve(3) OPENSSL_LH_set_down_load(3) OPENSSL_LH_strhash(3) OPENSSL_asc2uni(3) diff --git a/util/missingmacro.txt b/util/missingmacro.txt index 4cad414f3a..6b7f9fa2b3 100644 --- a/util/missingmacro.txt +++ b/util/missingmacro.txt @@ -99,8 +99,6 @@ PEM_write_bio_OCSP_REQUEST(3) PEM_write_bio_OCSP_RESPONSE(3) ASN1_BIT_STRING_digest(3) OCSP_CERTSTATUS_dup(3) -OPENSSL_VERSION_PREREQ(3) -OSSL_PARAM_DEFN(3) OSSL_PARAM_SIZED_int(3) OSSL_PARAM_SIZED_uint(3) OSSL_PARAM_SIZED_long(3) diff --git a/util/other-internal.syms b/util/other-internal.syms index 5688daa687..9f6a22e2ea 100644 --- a/util/other-internal.syms +++ b/util/other-internal.syms @@ -1,3 +1,5 @@ ossl_cmp_allow_unprotected_cb_t datatype # DEFINE_SPARSE_ARRAY_OF define +#Functions exported by libcrypto that don't exist in our public headers +asn1_d2i_read_bio internal diff --git a/util/other.syms b/util/other.syms index 670ba78938..54eeeb95cf 100644 --- a/util/other.syms +++ b/util/other.syms @@ -348,6 +348,7 @@ OPENSSL_VERSION_MINOR define OPENSSL_VERSION_NUMBER define deprecated 3.0.0 OPENSSL_VERSION_PATCH define OPENSSL_VERSION_PRE_RELEASE define +OPENSSL_VERSION_PREREQ define OPENSSL_VERSION_BUILD_METADATA define OPENSSL_VERSION_PRE_RELEASE_STR define OPENSSL_VERSION_BUILD_METADATA_STR define @@ -404,6 +405,7 @@ OSSL_CMP_SRV_certConf_cb_t datatype OSSL_CMP_SRV_genm_cb_t datatype OSSL_CMP_SRV_error_cb_t datatype OSSL_CMP_SRV_pollReq_cb_t datatype +OSSL_CORE_MAKE_FUNC define OSSL_PARAM_TYPE define OSSL_PARAM_octet_ptr define OSSL_PARAM_octet_string define