1 files changed, 158 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3 b/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
new file mode 100644
index 0000000000..05a36a4f79
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
@@ -0,0 +1,158 @@
+.\" $OpenBSD: X509_VERIFY_PARAM_new.3,v 1.1 2021/10/18 14:46:37 schwarze Exp $
+.\"
+.\" Copyright (c) 2018, 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: October 18 2021 $
+.Dt X509_VERIFY_PARAM_NEW 3
+.Os
+.Sh NAME
+.Nm X509_VERIFY_PARAM_new ,
+.Nm X509_VERIFY_PARAM_free ,
+.Nm X509_VERIFY_PARAM_add0_table ,
+.Nm X509_VERIFY_PARAM_lookup ,
+.Nm X509_VERIFY_PARAM_get_count ,
+.Nm X509_VERIFY_PARAM_get0 ,
+.Nm X509_VERIFY_PARAM_table_cleanup
+.Nd X509 verification parameter object
+.Sh SYNOPSIS
+.In openssl/x509_vfy.h
+.Ft X509_VERIFY_PARAM *
+.Fo X509_VERIFY_PARAM_new
+.Fa void
+.Fc
+.Ft void
+.Fo X509_VERIFY_PARAM_free
+.Fa "X509_VERIFY_PARAM *param"
+.Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_add0_table
+.Fa "X509_VERIFY_PARAM *param"
+.Fc
+.Ft const X509_VERIFY_PARAM *
+.Fo X509_VERIFY_PARAM_lookup
+.Fa "const char *name"
+.Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_get_count
+.Fa void
+.Fc
+.Ft const X509_VERIFY_PARAM *
+.Fo X509_VERIFY_PARAM_get0
+.Fa "int id"
+.Fc
+.Ft void
+.Fo X509_VERIFY_PARAM_table_cleanup
+.Fa void
+.Fc
+.Sh DESCRIPTION
+.Fn X509_VERIFY_PARAM_new
+allocates and initializes an empty
+.Vt X509_VERIFY_PARAM
+object.
+.Pp
+.Fn X509_VERIFY_PARAM_free
+clears all data contained in
+.Fa param
+and releases all memory used by it.
+If
+.Fa param
+is a
+.Dv NULL
+pointer, no action occurs.
+.Pp
+.Fn X509_VERIFY_PARAM_add0_table
+adds
+.Fa param
+to a static list of
+.Vt X509_VERIFY_PARAM
+objects maintained by the library.
+This function is extremely dangerous because contrary to the name
+of the function, if the list already contains an object that happens
+to have the same name, that old object is not only silently removed
+from the list, but also silently freed, which may silently invalidate
+various pointers existing elsewhere in the program.
+.Pp
+.Fn X509_VERIFY_PARAM_lookup
+searches this list for an object of the given
+.Fa name .
+If no match is found, the predefined objects built-in to the library
+are also inspected.
+.Pp
+.Fn X509_VERIFY_PARAM_get_count
+returns the sum of the number of objects on this list and the number
+of predefined objects built-in to the library.
+Note that this is not necessarily the total number of
+.Vt X509_VERIFY_PARAM
+objects existing in the program because there may be additional such
+objects that were never added to the list.
+.Pp
+.Fn X509_VERIFY_PARAM_get0
+accesses predefined and user-defined objects using
+.Fa id
+as an index, useful for looping over objects without knowing their names.
+An argument less than the number of predefined objects selects
+one of the predefined objects; a higher argument selects an object
+from the list.
+.Pp
+.Fn X509_VERIFY_PARAM_table_cleanup
+deletes all objects from this list.
+It is extremely dangerous because it also invalidates all data that
+was contained in all objects that were on the list and because it
+frees all these objects, which may invalidate various pointers
+existing elsewhere in the program.
+.Sh RETURN VALUES
+.Fn X509_VERIFY_PARAM_new
+returns a pointer to the new object, or
+.Dv NULL
+on allocation failure.
+.Pp
+.Fn X509_VERIFY_PARAM_add0_table
+returns 1 for success or 0 for failure.
+.Pp
+.Fn X509_VERIFY_PARAM_lookup
+and
+.Fn X509_VERIFY_PARAM_get0
+return a pointer to an existing built-in or user-defined object, or
+.Dv NULL
+if no object with the given
+.Fa name
+is found, or if
+.Fa id
+is at least
+.Fn X509_VERIFY_PARAM_get_count .
+.Pp
+.Fn X509_VERIFY_PARAM_get_count
+returns a number of objects.
+.Sh SEE ALSO
+.Xr SSL_set1_param 3 ,
+.Xr X509_STORE_CTX_set0_param 3 ,
+.Xr X509_STORE_set1_param 3 ,
+.Xr X509_verify_cert 3 ,
+.Xr X509_VERIFY_PARAM_set_flags 3
+.Sh HISTORY
+.Fn X509_VERIFY_PARAM_new ,
+.Fn X509_VERIFY_PARAM_free ,
+.Fn X509_VERIFY_PARAM_add0_table ,
+.Fn X509_VERIFY_PARAM_lookup ,
+and
+.Fn X509_VERIFY_PARAM_table_cleanup
+first appeared in OpenSSL 0.9.8 and have been available since
+.Ox 4.5 .
+.Pp
+.Fn X509_VERIFY_PARAM_get_count
+and
+.Fn X509_VERIFY_PARAM_get0
+first appeared in OpenSSL 1.0.2 and have been available since
+.Ox 6.3 .