From fe9ac7b09157e97ae2148a9610f5f1614d1d4f79 Mon Sep 17 00:00:00 2001 From: tb Date: Wed, 31 Jan 2024 08:02:53 +0000 Subject: [PATCH] Merge OBJ_NAME_do_all*(3) into EVP_CIPHER_do_all(3) This is the only OBJ_NAME API that will remain after the next major bump. The API is misnamed and really is about EVP, so move it to an EVP manual documenting another API doing essentially the same thing. Remove most cross references to OBJ_NAME_*. --- lib/libcrypto/man/EVP_CIPHER_do_all.3 | 97 ++++++++++++++++++++++--- lib/libcrypto/man/OBJ_NAME_add.3 | 45 +----------- lib/libcrypto/man/OBJ_create.3 | 5 +- lib/libcrypto/man/OBJ_find_sigid_algs.3 | 5 +- lib/libcrypto/man/OBJ_nid2obj.3 | 7 +- 5 files changed, 96 insertions(+), 63 deletions(-) diff --git a/lib/libcrypto/man/EVP_CIPHER_do_all.3 b/lib/libcrypto/man/EVP_CIPHER_do_all.3 index 1d43d503def..9411a41f7de 100644 --- a/lib/libcrypto/man/EVP_CIPHER_do_all.3 +++ b/lib/libcrypto/man/EVP_CIPHER_do_all.3 @@ -1,6 +1,7 @@ -.\" $OpenBSD: EVP_CIPHER_do_all.3,v 1.1 2023/08/30 00:58:57 tb Exp $ +.\" $OpenBSD: EVP_CIPHER_do_all.3,v 1.2 2024/01/31 08:02:53 tb Exp $ .\" -.\" Copyright (c) 2023 Theo Buehler +.\" Copyright (c) 2023,2024 Theo Buehler +.\" Copyright (c) 2021 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: August 30 2023 $ +.Dd $Mdocdate: January 31 2024 $ .Dt EVP_CIPHER_DO_ALL 3 .Os .Sh NAME @@ -49,6 +50,27 @@ const char *to, void *arg)" .Fa "void *arg" .Fc +.Bd -literal +typedef struct { + int type; + int alias; + const char *name; + const char *data; +} OBJ_NAME; +.Ed +.Pp +.Ft void +.Fo OBJ_NAME_do_all +.Fa "int type" +.Fa "void (*fn)(const OBJ_NAME *obj_name, void *arg)" +.Fa "void *arg" +.Fc +.Ft void +.Fo OBJ_NAME_do_all_sorted +.Fa "int type" +.Fa "void (*fn)(const OBJ_NAME *obj_name, void *arg)" +.Fa "void *arg" +.Fc .Sh DESCRIPTION .Fn EVP_CIPHER_do_all calls @@ -117,18 +139,71 @@ in lexicographic order of their .Fa from names as determined by .Xr strcmp 3 . +.Pp +.Vt OBJ_NAME +is an abstraction of the types underlying the lookup tables +for ciphers and their aliases, and digests and their aliases, respectively. +For a cipher, +.Fa type +is +.Dv OBJ_NAME_TYPE_CIPHER_METH , +.Fa alias +is 0, +.Fa name +is its lookup name and +.Fa data +is the +.Vt EVP_CIPHER +object it represents, cast to +.Vt const char * . +For a cipher alias, +.Fa type +is +.Dv OBJ_NAME_TYPE_CIPHER_METH , +.Fa alias +is +.Dv OBJ_NAME_ALIAS , +.Fa name +is its lookup name and +.Fa data +is the name it aliases. +Digests representing an +.Vt EVP_MD +object and their aliases are represented similarly, except that their type is +.Dv OBJ_NAME_TYPE_MD_METH . +.Pp +.Fn OBJ_NAME_do_all +calls +.Fa fn +on every +.Fa obj_name +in the table that has the given +.Fa type +(either +.Dv OBJ_NAME_TYPE_CIPHER_METH +or +.Dv OBJ_NAME_TYPE_MD_METH ) , +also passing the +.Fa arg +pointer. +.Fn OBJ_NAME_do_all_sorted +is similar except that it processes the +.Fa obj_name +in lexicographic order of their names as determined by +.Xr strcmp 3 . .Sh SEE ALSO .Xr evp 3 , -.Xr EVP_add_cipher 3 , -.Xr OBJ_NAME_do_all 3 +.Xr EVP_get_cipherbyname 3 , +.Xr EVP_get_digestbyname 3 .Sh HISTORY These functions first appeared in OpenSSL 1.0.0 and have been available since .Ox 4.9 . -.Sh BUGS -.Fn EVP_CIPHER_do_all_sorted +.Sh CAVEATS +.Fn EVP_CIPHER_do_all_sorted , +.Fn EVP_MD_do_all_sorted , and -.Fn EVP_MD_do_all_sorted -are wrappers of -.Xr OBJ_NAME_do_all_sorted 3 . -In particular, if memory allocation fails, they do nothing at all +.Fn OBJ_NAME_do_all_sorted +cannot report errors. +In some implementations they need to allocate internally and +if memory allocation fails they do nothing at all, without telling the caller about the problem. diff --git a/lib/libcrypto/man/OBJ_NAME_add.3 b/lib/libcrypto/man/OBJ_NAME_add.3 index ad2ba80893c..0b46010c491 100644 --- a/lib/libcrypto/man/OBJ_NAME_add.3 +++ b/lib/libcrypto/man/OBJ_NAME_add.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OBJ_NAME_add.3,v 1.5 2023/09/01 12:13:13 schwarze Exp $ +.\" $OpenBSD: OBJ_NAME_add.3,v 1.6 2024/01/31 08:02:53 tb Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: September 1 2023 $ +.Dd $Mdocdate: January 31 2024 $ .Dt OBJ_NAME_ADD 3 .Os .Sh NAME @@ -23,9 +23,7 @@ .Nm OBJ_NAME_get , .Nm OBJ_NAME_new_index , .Nm OBJ_NAME_init , -.Nm OBJ_NAME_cleanup , -.Nm OBJ_NAME_do_all , -.Nm OBJ_NAME_do_all_sorted +.Nm OBJ_NAME_cleanup .Nd global associative array .Sh SYNOPSIS .In openssl/objects.h @@ -63,19 +61,6 @@ typedef struct { const char *data; } OBJ_NAME; .Ed -.Pp -.Ft void -.Fo OBJ_NAME_do_all -.Fa "int type" -.Fa "void (*fn)(const OBJ_NAME *pair, void *arg)" -.Fa "void *arg" -.Fc -.Ft void -.Fo OBJ_NAME_do_all_sorted -.Fa "int type" -.Fa "void (*fn)(const OBJ_NAME *pair, void *arg)" -.Fa "void *arg" -.Fc .Sh DESCRIPTION These functions implement a single, static associative array with the following properties: @@ -264,25 +249,6 @@ If the field is 0, the .Fa data field contains the value; otherwise, it contains the alias target name. -.Pp -.Fn OBJ_NAME_do_all -calls -.Fa fn -on every -.Fa pair -and alias in the array that has the given -.Fa type , -also passing the -.Fa arg -pointer. -.Fn OBJ_NAME_do_all_sorted -is similar except that it processes the pairs and aliases -in lexicographic order of their names as determined by -.Xr strcmp 3 , -ignoring any -.Fa cmp_func -that may be defined for the -.Fa type . .Sh RETURN VALUES .Fn OBJ_NAME_add and @@ -339,8 +305,3 @@ that requires more cleanup than merely calling .Xr free 3 on it, instances of the type need to begin with a magic number or string that cannot occur at the beginning of a name. -.Pp -.Fn OBJ_NAME_do_all_sorted -is unable to report errors. -If memory allocations fails, it does nothing at all -without telling the caller about the problem. diff --git a/lib/libcrypto/man/OBJ_create.3 b/lib/libcrypto/man/OBJ_create.3 index 6bc255e9818..fa5bde3dd36 100644 --- a/lib/libcrypto/man/OBJ_create.3 +++ b/lib/libcrypto/man/OBJ_create.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OBJ_create.3,v 1.9 2024/01/13 19:06:20 tb Exp $ +.\" $OpenBSD: OBJ_create.3,v 1.10 2024/01/31 08:02:53 tb Exp $ .\" full merge up to: .\" OpenSSL OBJ_nid2obj.pod 9b86974e Aug 17 15:21:33 2015 -0400 .\" selective merge up to: @@ -69,7 +69,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: January 13 2024 $ +.Dd $Mdocdate: January 31 2024 $ .Dt OBJ_CREATE 3 .Os .Sh NAME @@ -200,7 +200,6 @@ obj = OBJ_nid2obj(new_nid); .Ed .Sh SEE ALSO .Xr ASN1_OBJECT_new 3 , -.Xr OBJ_NAME_add 3 , .Xr OBJ_nid2obj 3 .Sh HISTORY .Fn OBJ_new_nid , diff --git a/lib/libcrypto/man/OBJ_find_sigid_algs.3 b/lib/libcrypto/man/OBJ_find_sigid_algs.3 index 9aeb54c90b4..1d7a2b649be 100644 --- a/lib/libcrypto/man/OBJ_find_sigid_algs.3 +++ b/lib/libcrypto/man/OBJ_find_sigid_algs.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OBJ_find_sigid_algs.3,v 1.1 2023/07/22 06:35:26 tb Exp $ +.\" $OpenBSD: OBJ_find_sigid_algs.3,v 1.2 2024/01/31 08:02:53 tb Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 22 2023 $ +.Dd $Mdocdate: January 31 2024 $ .Dt OBJ_FIND_SIGID_ALGS 3 .Os .Sh NAME @@ -82,7 +82,6 @@ is not built into the library. .Sh SEE ALSO .Xr EVP_cleanup 3 , .Xr OBJ_create 3 , -.Xr OBJ_NAME_add 3 , .Xr OBJ_nid2obj 3 .Sh HISTORY These functions first appeared in OpenSSL 1.0.0 diff --git a/lib/libcrypto/man/OBJ_nid2obj.3 b/lib/libcrypto/man/OBJ_nid2obj.3 index 4e420b8311d..ccab1ed30ce 100644 --- a/lib/libcrypto/man/OBJ_nid2obj.3 +++ b/lib/libcrypto/man/OBJ_nid2obj.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: OBJ_nid2obj.3,v 1.21 2023/09/05 13:50:22 schwarze Exp $ +.\" $OpenBSD: OBJ_nid2obj.3,v 1.22 2024/01/31 08:02:53 tb Exp $ .\" full merge up to: OpenSSL c264592d May 14 11:28:00 2006 +0000 .\" selective merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 .\" @@ -67,7 +67,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: September 5 2023 $ +.Dd $Mdocdate: January 31 2024 $ .Dt OBJ_NID2OBJ 3 .Os .Sh NAME @@ -435,8 +435,7 @@ object = OBJ_txt2obj("1.2.3.4", 1); .Xr ASN1_OBJECT_new 3 , .Xr BIO_new 3 , .Xr d2i_ASN1_OBJECT 3 , -.Xr OBJ_create 3 , -.Xr OBJ_NAME_add 3 +.Xr OBJ_create 3 .Sh HISTORY .Fn OBJ_nid2obj , .Fn OBJ_nid2ln , -- 2.20.1