new manual page OBJ_NAME_add(3)

author: schwarze <> 2021-12-17 17:56:14 +0000
committer: schwarze <> 2021-12-17 17:56:14 +0000
commit: f3fd5e4639a117250c5d13efab1883f460960aa2 (patch)
tree: fa1870870dde65aca327ceeedec90557c03ee8b6
parent: ca1af08567d5dd9ac98a715c46a88a3271fd9522 (diff)
download: openbsd-f3fd5e4639a117250c5d13efab1883f460960aa2.tar.gz
openbsd-f3fd5e4639a117250c5d13efab1883f460960aa2.tar.bz2
openbsd-f3fd5e4639a117250c5d13efab1883f460960aa2.zip
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
author	schwarze <>	2021-12-17 17:56:14 +0000
committer	schwarze <>	2021-12-17 17:56:14 +0000
commit	f3fd5e4639a117250c5d13efab1883f460960aa2 (patch)
tree	fa1870870dde65aca327ceeedec90557c03ee8b6
parent	ca1af08567d5dd9ac98a715c46a88a3271fd9522 (diff)
download	openbsd-f3fd5e4639a117250c5d13efab1883f460960aa2.tar.gz openbsd-f3fd5e4639a117250c5d13efab1883f460960aa2.tar.bz2 openbsd-f3fd5e4639a117250c5d13efab1883f460960aa2.zip

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 @@
1	# $OpenBSD: Makefile,v 1.229 2021/12/15 20:07:51 schwarze Exp $	1	# $OpenBSD: Makefile,v 1.230 2021/12/17 17:56:14 schwarze Exp $
2		2
3	.include <bsd.own.mk>	3	.include <bsd.own.mk>
4		4
@@ -206,6 +206,7 @@ MAN= \
206	HMAC.3 \	206	HMAC.3 \
207	MD5.3 \	207	MD5.3 \
208	NAME_CONSTRAINTS_new.3 \	208	NAME_CONSTRAINTS_new.3 \
		209	OBJ_NAME_add.3 \
209	OBJ_create.3 \	210	OBJ_create.3 \
210	OBJ_nid2obj.3 \	211	OBJ_nid2obj.3 \
211	OCSP_CRLID_new.3 \	212	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 @@
		1	.\" $OpenBSD: OBJ_NAME_add.3,v 1.1 2021/12/17 17:56:14 schwarze Exp $
		2	.\"
		3	.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
		4	.\"
		5	.\" Permission to use, copy, modify, and distribute this software for any
		6	.\" purpose with or without fee is hereby granted, provided that the above
		7	.\" copyright notice and this permission notice appear in all copies.
		8	.\"
		9	.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
		10	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
		11	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
		12	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
		13	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
		14	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
		15	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
		16	.\"
		17	.Dd $Mdocdate: December 17 2021 $
		18	.Dt OBJ_NAME_ADD 3
		19	.Os
		20	.Sh NAME
		21	.Nm OBJ_NAME_add ,
		22	.Nm OBJ_NAME_remove ,
		23	.Nm OBJ_NAME_get ,
		24	.Nm OBJ_NAME_new_index ,
		25	.Nm OBJ_NAME_init ,
		26	.Nm OBJ_NAME_cleanup ,
		27	.Nm OBJ_NAME_do_all ,
		28	.Nm OBJ_NAME_do_all_sorted
		29	.Nd global associative array
		30	.Sh SYNOPSIS
		31	.In openssl/objects.h
		32	.Ft int
		33	.Fo OBJ_NAME_add
		34	.Fa "const char *name"
		35	.Fa "int type"
		36	.Fa "const char *data"
		37	.Fc
		38	.Ft int
		39	.Fo OBJ_NAME_remove
		40	.Fa "const char *name"
		41	.Fa "int type"
		42	.Fc
		43	.Ft const char *
		44	.Fo OBJ_NAME_get
		45	.Fa "const char *name"
		46	.Fa "int type"
		47	.Fc
		48	.Ft int
		49	.Fo OBJ_NAME_new_index
		50	.Fa "unsigned long (hash_func)(const char name)"
		51	.Fa "int (cmp_func)(const char name1, const char *name2)"
		52	.Fa "void (free_func)(const char name, int type, const char *value)"
		53	.Fc
		54	.Ft int
		55	.Fn OBJ_NAME_init void
		56	.Ft void
		57	.Fn OBJ_NAME_cleanup "int type"
		58	.Bd -literal
		59	typedef struct {
		60	int type;
		61	int alias;
		62	const char *name;
		63	const char *data;
		64	} OBJ_NAME;
		65	.Ed
		66	.Pp
		67	.Ft void
		68	.Fo OBJ_NAME_do_all
		69	.Fa "int type"
		70	.Fa "void (fn)(const OBJ_NAME pair, void *arg)"
		71	.Fa "void *arg"
		72	.Fc
		73	.Ft void
		74	.Fo OBJ_NAME_do_all_sorted
		75	.Fa "int type"
		76	.Fa "void (fn)(const OBJ_NAME pair, void *arg)"
		77	.Fa "void *arg"
		78	.Fc
		79	.Sh DESCRIPTION
		80	These functions implement a single, static associative array
		81	with the following properties:
		82	.Bl -bullet
		83	.It
		84	The keys are ordered pairs consisting of a NUL-terminated string
		85	.Pq called the Fa name
		86	and an
		87	.Vt int
		88	number
		89	.Pq called the Fa type .
		90	Two types are predefined and used internally by the library:
		91	.Dv OBJ_NAME_TYPE_MD_METH
		92	and
		93	.Dv OBJ_NAME_TYPE_CIPHER_METH .
		94	Two additional types are predefined but not used internally:
		95	.Dv OBJ_NAME_TYPE_PKEY_METH
		96	and
		97	.Dv OBJ_NAME_TYPE_COMP_METH .
		98	All predefined types are greater than
		99	.Dv OBJ_NAME_TYPE_UNDEF
		100	and smaller than
		101	.Dv OBJ_NAME_TYPE_NUM .
		102	.It
		103	The values are pointers.
		104	Formally, they are of the type
		105	.Vt const char * ,
		106	but in practice, pointers of other types, for example
		107	.Vt EVP_CIPHER *
		108	or
		109	.Vt EVP_MD * ,
		110	are often stored as values
		111	and cast back to the correct type on retrieval.
		112	.It
		113	The array supports type-specific aliases for names.
		114	.El
		115	.Pp
		116	.Fn OBJ_NAME_add
		117	removes the key-value pair or alias with the key
		118	.Pq Fa name , type
		119	in the same way as
		120	.Fn OBJ_NAME_remove
		121	and inserts a key-value pair with the specified
		122	.Fa name ,
		123	.Fa type ,
		124	and
		125	.Fa value .
		126	If the bit
		127	.Dv OBJ_NAME_ALIAS
		128	is set in the
		129	.Fa type
		130	argument, that bit is cleared before using the
		131	.Fa type
		132	and the key
		133	.Pq Fa name , type
		134	becomes an alias for the key
		135	.Pq Fa value , type
		136	instead of setting a value.
		137	It is not checked whether the key
		138	.Pq Fa value , type
		139	already exists.
		140	Consequently, it is possible to define an alias
		141	before setting the associated value.
		142	.Pp
		143	.Fn OBJ_NAME_remove
		144	removes the key-value pair or alias with the key
		145	.Pq Fa name , type
		146	from the array, it it exists.
		147	Otherwise, it has no effect.
		148	If the bit
		149	.Dv OBJ_NAME_ALIAS
		150	is set in the
		151	.Fa type
		152	argument, it is ignored and cleared before using the
		153	.Fa type .
		154	If the
		155	.Fa type
		156	is an application-defined type added with
		157	.Fn OBJ_NAME_new_index
		158	and the
		159	.Fa free_func
		160	associated with the
		161	.Fa type
		162	is not a
		163	.Dv NULL
		164	pointer, it is called with the
		165	.Fa name ,
		166	.Fa type ,
		167	and
		168	.Fa value
		169	of the key-value pair being removed or with the
		170	.Fa name ,
		171	.Fa type ,
		172	and alias target name of the alias being removed.
		173	In typical usage, this function might free the
		174	.Fa name ,
		175	and it might free the
		176	.Fa value
		177	in a type-specific way.
		178	.Pp
		179	.Fn OBJ_NAME_get
		180	looks up the key
		181	.Pq Fa name , type ,
		182	recursively resolving up to ten aliases if needed.
		183	If the bit
		184	.Dv OBJ_NAME_ALIAS
		185	is set in the
		186	.Fa type
		187	argument, it is cleared before using the
		188	.Fa type ,
		189	processing of aliases is disabled, and if
		190	.Pq Fa name , type
		191	is an alias, the target name of the alias is returned instead of a value.
		192	.Pp
		193	.Fn OBJ_NAME_new_index
		194	assigns the smallest unassigned positive integer number
		195	to represent a new, application-defined
		196	.Fa type .
		197	The three function pointers will be used, respectively,
		198	to hash a name for this type, to compare two names for this type,
		199	and to free the contents of a key-value pair holding the given
		200	.Fa name ,
		201	.Fa type ,
		202	and
		203	.Fa value .
		204	If the
		205	.Fa hash_func
		206	argument is a
		207	.Dv NULL
		208	pointer,
		209	.Xr lh_strhash 3
		210	is used instead.
		211	If the
		212	.Fa cmp_func
		213	argument is a
		214	.Dv NULL
		215	pointer,
		216	.Xr strcmp 3
		217	is used instead.
		218	If the
		219	.Fa free_func
		220	argument is a
		221	.Dv NULL
		222	pointer, the
		223	.Fa name
		224	and
		225	.Fa value
		226	pointers contained in the key-value pair are not freed,
		227	only the structure representing the pair itself is.
		228	This default behaviour is also used for the built-in types.
		229	.Pp
		230	.Fn OBJ_NAME_init
		231	initializes the array.
		232	After initialization, the array is empty.
		233	Calling
		234	.Fn OBJ_NAME_init
		235	when the array is already initialized has no effect.
		236	Application programs do not need to call this function because
		237	.Fn OBJ_NAME_add
		238	and
		239	.Fn OBJ_NAME_get
		240	automatically call it whenever needed.
		241	.Pp
		242	.Fn OBJ_NAME_cleanup
		243	removes all key-value pairs and aliases of the given
		244	.Fa type
		245	from the array by calling
		246	.Fn OBJ_NAME_remove
		247	on every such pair and alias.
		248	If the
		249	.Fa type
		250	argument is negative, it removes all key-value pairs and aliases
		251	of any type and also reverses all effects of
		252	.Fn OBJ_NAME_new_index
		253	and
		254	.Fn OBJ_NAME_init ,
		255	in particular resetting the list of types to the predefined types
		256	and releasing all memory reserved by these functions.
		257	.Pp
		258	The
		259	.Vt OBJ_NAME
		260	structure represents one key-value pair or one alias with the key
		261	.Pq Fa name , type .
		262	If the
		263	.Fa alias
		264	field is 0, the
		265	.Fa data
		266	field contains the value; otherwise, it contains the alias target name.
		267	.Pp
		268	.Fn OBJ_NAME_do_all
		269	calls
		270	.Fa fn
		271	on every
		272	.Fa pair
		273	and alias in the array that has the given
		274	.Fa type ,
		275	also passing the
		276	.Fa arg
		277	pointer.
		278	.Fn OBJ_NAME_do_all_sorted
		279	is similar except that it processes the pairs and aliases
		280	in lexicographic order of their names as determined by
		281	.Xr strcmp 3 ,
		282	ignoring any
		283	.Fa cmp_func
		284	that may be defined for the
		285	.Fa type .
		286	.Sh RETURN VALUES
		287	.Fn OBJ_NAME_add
		288	and
		289	.Fn OBJ_NAME_init
		290	return 1 on success or 0 if memory allocation fails.
		291	.Pp
		292	.Fn OBJ_NAME_remove
		293	returns 1 if one key-value pair or alias was removed or 0 otherwise.
		294	.Pp
		295	.Fn OBJ_NAME_get
		296	returns the
		297	.Fa value
		298	associated with the key
		299	.Pq Fa name , type
		300	or
		301	.Dv NULL
		302	if
		303	.Fa name
		304	is
		305	.Dv NULL ,
		306	if the array does not contain a value for this key,
		307	or if more than ten aliases are encountered before finding a value.
		308	.Pp
		309	.Fn OBJ_NAME_new_index
		310	returns a positive integer greater than or equal to
		311	.Dv OBJ_NAME_TYPE_NUM
		312	representing the new type or 0 if memory allocation fails.
		313	.Sh SEE ALSO
		314	.Xr EVP_cleanup 3 ,
		315	.Xr EVP_get_cipherbyname 3 ,
		316	.Xr EVP_get_digestbyname 3 ,
		317	.Xr lh_new 3 ,
		318	.Xr OBJ_create 3 ,
		319	.Xr OBJ_nid2obj 3
		320	.Sh BUGS
		321	Calling
		322	.Fn OBJ_NAME_get
		323	with the bit
		324	.Dv OBJ_NAME_ALIAS
		325	is not very useful because there is no way to tell
		326	whether the returned pointer points to a value or to a name,
		327	short of calling the function again without setting the bit
		328	and comparing the two returned pointers.
		329	.Pp
		330	The
		331	.Fa free_func
		332	has no way to tell whether its
		333	.Fa value
		334	argument is indeed of the given
		335	.Fa type
		336	or whether it is merely the target name of an alias.
		337	Consequently, to use values of a type
		338	that requires more cleanup than merely calling
		339	.Xr free 3
		340	on it, instances of the type need to begin with a magic number or string
		341	that cannot occur at the beginning of a name.
		342	.Pp
		343	.Fn OBJ_NAME_do_all_sorted
		344	is unable to report errors.
		345	If memory allocations fails, it does nothing at all
		346	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 @@
1	.\" $OpenBSD: OBJ_create.3,v 1.3 2021/12/16 16:36:16 schwarze Exp $	1	.\" $OpenBSD: OBJ_create.3,v 1.4 2021/12/17 17:56:14 schwarze Exp $
2	.\" full merge up to:	2	.\" full merge up to:
3	.\" OpenSSL OBJ_nid2obj.pod 9b86974e Aug 17 15:21:33 2015 -0400	3	.\" OpenSSL OBJ_nid2obj.pod 9b86974e Aug 17 15:21:33 2015 -0400
4	.\" selective merge up to:	4	.\" selective merge up to:
@@ -69,7 +69,7 @@
69	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED	69	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
70	.\" OF THE POSSIBILITY OF SUCH DAMAGE.	70	.\" OF THE POSSIBILITY OF SUCH DAMAGE.
71	.\"	71	.\"
72	.Dd $Mdocdate: December 16 2021 $	72	.Dd $Mdocdate: December 17 2021 $
73	.Dt OBJ_CREATE 3	73	.Dt OBJ_CREATE 3
74	.Os	74	.Os
75	.Sh NAME	75	.Sh NAME
@@ -253,6 +253,7 @@ obj = OBJ_nid2obj(new_nid);
253	.Sh SEE ALSO	253	.Sh SEE ALSO
254	.Xr ASN1_OBJECT_new 3 ,	254	.Xr ASN1_OBJECT_new 3 ,
255	.Xr EVP_cleanup 3 ,	255	.Xr EVP_cleanup 3 ,
		256	.Xr OBJ_NAME_add 3 ,
256	.Xr OBJ_nid2obj 3	257	.Xr OBJ_nid2obj 3
257	.Sh HISTORY	258	.Sh HISTORY
258	.Fn OBJ_new_nid ,	259	.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 @@
1	.\" $OpenBSD: OBJ_nid2obj.3,v 1.16 2021/12/15 20:07:51 schwarze Exp $	1	.\" $OpenBSD: OBJ_nid2obj.3,v 1.17 2021/12/17 17:56:14 schwarze Exp $
2	.\" full merge up to: OpenSSL c264592d May 14 11:28:00 2006 +0000	2	.\" full merge up to: OpenSSL c264592d May 14 11:28:00 2006 +0000
3	.\" selective merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200	3	.\" selective merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200
4	.\"	4	.\"
@@ -67,7 +67,7 @@
67	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED	67	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
68	.\" OF THE POSSIBILITY OF SUCH DAMAGE.	68	.\" OF THE POSSIBILITY OF SUCH DAMAGE.
69	.\"	69	.\"
70	.Dd $Mdocdate: December 15 2021 $	70	.Dd $Mdocdate: December 17 2021 $
71	.Dt OBJ_NID2OBJ 3	71	.Dt OBJ_NID2OBJ 3
72	.Os	72	.Os
73	.Sh NAME	73	.Sh NAME
@@ -389,7 +389,8 @@ obj = OBJ_txt2obj("1.2.3.4", 1);
389	.Xr ASN1_OBJECT_new 3 ,	389	.Xr ASN1_OBJECT_new 3 ,
390	.Xr BIO_new 3 ,	390	.Xr BIO_new 3 ,
391	.Xr d2i_ASN1_OBJECT 3 ,	391	.Xr d2i_ASN1_OBJECT 3 ,
392	.Xr OBJ_create 3	392	.Xr OBJ_create 3 ,
		393	.Xr OBJ_NAME_add 3
393	.Sh HISTORY	394	.Sh HISTORY
394	.Fn OBJ_nid2obj ,	395	.Fn OBJ_nid2obj ,
395	.Fn OBJ_nid2ln ,	396	.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 @@
1	.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.9 2021/12/16 16:36:16 schwarze Exp $	1	.\" $OpenBSD: OpenSSL_add_all_algorithms.3,v 1.10 2021/12/17 17:56:14 schwarze Exp $
2	.\" full merge up to: OpenSSL b3696a55 Sep 2 09:35:50 2017 -0400	2	.\" full merge up to: OpenSSL b3696a55 Sep 2 09:35:50 2017 -0400
3	.\"	3	.\"
4	.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.	4	.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
48	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED	48	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49	.\" OF THE POSSIBILITY OF SUCH DAMAGE.	49	.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50	.\"	50	.\"
51	.Dd $Mdocdate: December 16 2021 $	51	.Dd $Mdocdate: December 17 2021 $
52	.Dt OPENSSL_ADD_ALL_ALGORITHMS 3	52	.Dt OPENSSL_ADD_ALL_ALGORITHMS 3
53	.Os	53	.Os
54	.Sh NAME	54	.Sh NAME
@@ -98,12 +98,17 @@ If any of the above functions is called more than once,
98	only the first call has an effect.	98	only the first call has an effect.
99	.Pp	99	.Pp
100	.Fn EVP_cleanup	100	.Fn EVP_cleanup
101	removes all ciphers and digests from the table.	101	removes all ciphers and digests from the table and also calls
		102	.Xr OBJ_NAME_cleanup 3
		103	with an argument of \-1, thus resetting the global associative array
		104	to its default state, removing all types, key-value pairs, and aliases
		105	from it, including any that are unrelated to the EVP library.
102	.Sh SEE ALSO	106	.Sh SEE ALSO
103	.Xr evp 3 ,	107	.Xr evp 3 ,
104	.Xr EVP_DigestInit 3 ,	108	.Xr EVP_DigestInit 3 ,
105	.Xr EVP_EncryptInit 3 ,	109	.Xr EVP_EncryptInit 3 ,
106	.Xr OBJ_cleanup 3 ,	110	.Xr OBJ_cleanup 3 ,
		111	.Xr OBJ_NAME_add 3 ,
107	.Xr OPENSSL_config 3	112	.Xr OPENSSL_config 3
108	.Sh HISTORY	113	.Sh HISTORY
109	.Fn EVP_cleanup	114	.Fn EVP_cleanup