new manual page OBJ_NAME_add(3)

5 files changed, 363 insertions, 9 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 9a51640331..9f9b152d12 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.229 2021/12/15 20:07:51 schwarze Exp $
+# $OpenBSD: Makefile,v 1.230 2021/12/17 17:56:14 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -206,6 +206,7 @@ MAN=	\
         HMAC.3 \
         MD5.3 \
         NAME_CONSTRAINTS_new.3 \
+        OBJ_NAME_add.3 \
         OBJ_create.3 \
         OBJ_nid2obj.3 \
         OCSP_CRLID_new.3 \
diff --git a/src/lib/libcrypto/man/OBJ_NAME_add.3 b/src/lib/libcrypto/man/OBJ_NAME_add.3
new file mode 100644
index 0000000000..4fc4d566a7
--- /dev/null
+++ b/src/lib/libcrypto/man/OBJ_NAME_add.3
@@ -0,0 +1,346 @@
+.\" $OpenBSD: OBJ_NAME_add.3,v 1.1 2021/12/17 17:56:14 schwarze Exp $
+.\"
+.\" 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 17 2021 $
+.Dt OBJ_NAME_ADD 3
+.Os
+.Sh NAME
+.Nm OBJ_NAME_add ,
+.Nm OBJ_NAME_remove ,
+.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
+.Nd global associative array
+.Sh SYNOPSIS
+.In openssl/objects.h
+.Ft int
+.Fo OBJ_NAME_add
+.Fa "const char *name"
+.Fa "int type"
+.Fa "const char *data"
+.Fc
+.Ft int
+.Fo OBJ_NAME_remove
+.Fa "const char *name"
+.Fa "int type"
+.Fc
+.Ft const char *
+.Fo OBJ_NAME_get
+.Fa "const char *name"
+.Fa "int type"
+.Fc
+.Ft int
+.Fo OBJ_NAME_new_index
+.Fa "unsigned long (*hash_func)(const char *name)"
+.Fa "int (*cmp_func)(const char *name1, const char *name2)"
+.Fa "void (*free_func)(const char *name, int type, const char *value)"
+.Fc
+.Ft int
+.Fn OBJ_NAME_init void
+.Ft void
+.Fn OBJ_NAME_cleanup "int type"
+.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 *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:
+.Bl -bullet
+.It
+The keys are ordered pairs consisting of a NUL-terminated string
+.Pq called the Fa name
+and an
+.Vt int
+number
+.Pq called the Fa type .
+Two types are predefined and used internally by the library:
+.Dv OBJ_NAME_TYPE_MD_METH
+and
+.Dv OBJ_NAME_TYPE_CIPHER_METH .
+Two additional types are predefined but not used internally:
+.Dv OBJ_NAME_TYPE_PKEY_METH
+and
+.Dv OBJ_NAME_TYPE_COMP_METH .
+All predefined types are greater than
+.Dv OBJ_NAME_TYPE_UNDEF
+and smaller than
+.Dv OBJ_NAME_TYPE_NUM .
+.It
+The values are pointers.
+Formally, they are of the type
+.Vt const char * ,
+but in practice, pointers of other types, for example
+.Vt EVP_CIPHER *
+or
+.Vt EVP_MD * ,
+are often stored as values
+and cast back to the correct type on retrieval.
+.It
+The array supports type-specific aliases for names.
+.El
+.Pp
+.Fn OBJ_NAME_add
+removes the key-value pair or alias with the key
+.Pq Fa name , type
+in the same way as
+.Fn OBJ_NAME_remove
+and inserts a key-value pair with the specified
+.Fa name ,
+.Fa type ,
+and
+.Fa value .
+If the bit
+.Dv OBJ_NAME_ALIAS
+is set in the
+.Fa type
+argument, that bit is cleared before using the
+.Fa type
+and the key
+.Pq Fa name , type
+becomes an alias for the key
+.Pq Fa value , type
+instead of setting a value.
+It is not checked whether the key
+.Pq Fa value , type
+already exists.
+Consequently, it is possible to define an alias
+before setting the associated value.
+.Pp
+.Fn OBJ_NAME_remove
+removes the key-value pair or alias with the key
+.Pq Fa name , type
+from the array, it it exists.
+Otherwise, it has no effect.
+If the bit
+.Dv OBJ_NAME_ALIAS
+is set in the
+.Fa type
+argument, it is ignored and cleared before using the
+.Fa type .
+If the
+.Fa type
+is an application-defined type added with
+.Fn OBJ_NAME_new_index
+and the
+.Fa free_func
+associated with the
+.Fa type
+is not a
+.Dv NULL
+pointer, it is called with the
+.Fa name ,
+.Fa type ,
+and
+.Fa value
+of the key-value pair being removed or with the
+.Fa name ,
+.Fa type ,
+and alias target name of the alias being removed.
+In typical usage, this function might free the
+.Fa name ,
+and it might free the
+.Fa value
+in a type-specific way.
+.Pp
+.Fn OBJ_NAME_get
+looks up the key
+.Pq Fa name , type ,
+recursively resolving up to ten aliases if needed.
+If the bit
+.Dv OBJ_NAME_ALIAS
+is set in the
+.Fa type
+argument, it is cleared before using the
+.Fa type ,
+processing of aliases is disabled, and if
+.Pq Fa name , type
+is an alias, the target name of the alias is returned instead of a value.
+.Pp
+.Fn OBJ_NAME_new_index
+assigns the smallest unassigned positive integer number
+to represent a new, application-defined
+.Fa type .
+The three function pointers will be used, respectively,
+to hash a name for this type, to compare two names for this type,
+and to free the contents of a key-value pair holding the given
+.Fa name ,
+.Fa type ,
+and
+.Fa value .
+If the
+.Fa hash_func
+argument is a
+.Dv NULL
+pointer,
+.Xr lh_strhash 3
+is used instead.
+If the
+.Fa cmp_func
+argument is a
+.Dv NULL
+pointer,
+.Xr strcmp 3
+is used instead.
+If the
+.Fa free_func
+argument is a
+.Dv NULL
+pointer, the
+.Fa name
+and
+.Fa value
+pointers contained in the key-value pair are not freed,
+only the structure representing the pair itself is.
+This default behaviour is also used for the built-in types.
+.Pp
+.Fn OBJ_NAME_init
+initializes the array.
+After initialization, the array is empty.
+Calling
+.Fn OBJ_NAME_init
+when the array is already initialized has no effect.
+Application programs do not need to call this function because
+.Fn OBJ_NAME_add
+and
+.Fn OBJ_NAME_get
+automatically call it whenever needed.
+.Pp
+.Fn OBJ_NAME_cleanup
+removes all key-value pairs and aliases of the given
+.Fa type
+from the array by calling
+.Fn OBJ_NAME_remove
+on every such pair and alias.
+If the
+.Fa type
+argument is negative, it removes all key-value pairs and aliases
+of any type and also reverses all effects of
+.Fn OBJ_NAME_new_index
+and
+.Fn OBJ_NAME_init ,
+in particular resetting the list of types to the predefined types
+and releasing all memory reserved by these functions.
+.Pp
+The
+.Vt OBJ_NAME
+structure represents one key-value pair or one alias with the key
+.Pq Fa name , type .
+If the
+.Fa alias
+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
+.Fn OBJ_NAME_init
+return 1 on success or 0 if memory allocation fails.
+.Pp
+.Fn OBJ_NAME_remove
+returns 1 if one key-value pair or alias was removed or 0 otherwise.
+.Pp
+.Fn OBJ_NAME_get
+returns the
+.Fa value
+associated with the key
+.Pq Fa name , type
+or
+.Dv NULL
+if
+.Fa name
+is
+.Dv NULL ,
+if the array does not contain a value for this key,
+or if more than ten aliases are encountered before finding a value.
+.Pp
+.Fn OBJ_NAME_new_index
+returns a positive integer greater than or equal to
+.Dv OBJ_NAME_TYPE_NUM
+representing the new type or 0 if memory allocation fails.
+.Sh SEE ALSO
+.Xr EVP_cleanup 3 ,
+.Xr EVP_get_cipherbyname 3 ,
+.Xr EVP_get_digestbyname 3 ,
+.Xr lh_new 3 ,
+.Xr OBJ_create 3 ,
+.Xr OBJ_nid2obj 3
+.Sh BUGS
+Calling
+.Fn OBJ_NAME_get
+with the bit
+.Dv OBJ_NAME_ALIAS
+is not very useful because there is no way to tell
+whether the returned pointer points to a value or to a name,
+short of calling the function again without setting the bit
+and comparing the two returned pointers.
+.Pp
+The
+.Fa free_func
+has no way to tell whether its
+.Fa value
+argument is indeed of the given
+.Fa type
+or whether it is merely the target name of an alias.
+Consequently, to use values of a type
+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/src/lib/libcrypto/man/OBJ_create.3 b/src/lib/libcrypto/man/OBJ_create.3
index 0a91fc8655..bc081a8c80 100644
--- a/src/lib/libcrypto/man/OBJ_create.3
+++ b/src/lib/libcrypto/man/OBJ_create.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OBJ_create.3,v 1.3 2021/12/16 16:36:16 schwarze Exp $
+.\" $OpenBSD: OBJ_create.3,v 1.4 2021/12/17 17:56:14 schwarze 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: December 16 2021 $
+.Dd $Mdocdate: December 17 2021 $
 .Dt OBJ_CREATE 3
 .Os
 .Sh NAME
@@ -253,6 +253,7 @@ obj = OBJ_nid2obj(new_nid);
 .Sh SEE ALSO
 .Xr ASN1_OBJECT_new 3 ,
 .Xr EVP_cleanup 3 ,
+.Xr OBJ_NAME_add 3 ,
 .Xr OBJ_nid2obj 3
 .Sh HISTORY
 .Fn OBJ_new_nid ,
diff --git a/src/lib/libcrypto/man/OBJ_nid2obj.3 b/src/lib/libcrypto/man/OBJ_nid2obj.3
index a43fe962e1..a337cedf18 100644
--- a/src/lib/libcrypto/man/OBJ_nid2obj.3
+++ b/src/lib/libcrypto/man/OBJ_nid2obj.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OBJ_nid2obj.3,v 1.16 2021/12/15 20:07:51 schwarze Exp $
+.\" $OpenBSD: OBJ_nid2obj.3,v 1.17 2021/12/17 17:56:14 schwarze 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: December 15 2021 $
+.Dd $Mdocdate: December 17 2021 $
 .Dt OBJ_NID2OBJ 3
 .Os
 .Sh NAME
@@ -389,7 +389,8 @@ obj = 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_create 3 ,
+.Xr OBJ_NAME_add 3
 .Sh HISTORY
 .Fn OBJ_nid2obj ,
 .Fn OBJ_nid2ln ,
diff --git a/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 b/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3
index e47948df4c..f95c0713ef 100644
--- a/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3
+++ b/src/lib/libcrypto/man/OpenSSL_add_all_algorithms.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.9 2021/12/16 16:36:16 schwarze Exp $
+.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.10 2021/12/17 17:56:14 schwarze Exp $
 .\" full merge up to: OpenSSL b3696a55 Sep 2 09:35:50 2017 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 16 2021 $
+.Dd $Mdocdate: December 17 2021 $
 .Dt OPENSSL_ADD_ALL_ALGORITHMS 3
 .Os
 .Sh NAME
@@ -98,12 +98,17 @@ If any of the above functions is called more than once,
 only the first call has an effect.
 .Pp
 .Fn EVP_cleanup
-removes all ciphers and digests from the table.
+removes all ciphers and digests from the table and also calls
+.Xr OBJ_NAME_cleanup 3
+with an argument of \-1, thus resetting the global associative array
+to its default state, removing all types, key-value pairs, and aliases
+from it, including any that are unrelated to the EVP library.
 .Sh SEE ALSO
 .Xr evp 3 ,
 .Xr EVP_DigestInit 3 ,
 .Xr EVP_EncryptInit 3 ,
 .Xr OBJ_cleanup 3 ,
+.Xr OBJ_NAME_add 3 ,
 .Xr OPENSSL_config 3
 .Sh HISTORY
 .Fn EVP_cleanup