From: schwarze Date: Fri, 17 Dec 2021 17:56:14 +0000 (+0000) Subject: new manual page OBJ_NAME_add(3) X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=d362e6b361474e3b4dff2c8b458dd5a24205a5b8;p=openbsd new manual page OBJ_NAME_add(3) --- diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 9a516403311..9f9b152d124 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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/lib/libcrypto/man/OBJ_NAME_add.3 b/lib/libcrypto/man/OBJ_NAME_add.3 new file mode 100644 index 00000000000..4fc4d566a76 --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/OBJ_create.3 b/lib/libcrypto/man/OBJ_create.3 index 0a91fc86558..bc081a8c80c 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.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/lib/libcrypto/man/OBJ_nid2obj.3 b/lib/libcrypto/man/OBJ_nid2obj.3 index a43fe962e1e..a337cedf18e 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.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/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 b/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 index e47948df4cb..f95c0713ef8 100644 --- a/lib/libcrypto/man/OpenSSL_add_all_algorithms.3 +++ b/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 . @@ -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