1 files changed, 86 insertions, 11 deletions

diff --git a/src/lib/libcrypto/man/EVP_CIPHER_do_all.3 b/src/lib/libcrypto/man/EVP_CIPHER_do_all.3
index 1d43d503de..9411a41f7d 100644
--- a/src/lib/libcrypto/man/EVP_CIPHER_do_all.3
+++ b/src/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 <tb@openbsd.org>
+.\" Copyright (c) 2023,2024 Theo Buehler <tb@openbsd.org>
+.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" 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.