split seven functions out of the page X509_VERIFY_PARAM_set_flags(3), which

is becoming excessively long, into a new page X509_VERIFY_PARAM_new(3);
no content change

5 files changed, 175 insertions, 134 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 1b838a599ce..3b13fc912ad 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.190 2021/08/06 21:50:54 schwarze Exp $
+# $OpenBSD: Makefile,v 1.191 2021/10/18 14:46:37 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -308,6 +308,7 @@ MAN=	\
 	X509_STORE_set_verify_cb_func.3 \
 	X509_STORE_set1_param.3 \
 	X509_TRUST_set.3 \
+	X509_VERIFY_PARAM_new.3 \
 	X509_VERIFY_PARAM_set_flags.3 \
 	X509_add1_trust_object.3 \
 	X509_check_ca.3 \
diff --git a/lib/libcrypto/man/X509_STORE_CTX_set_flags.3 b/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
index 72479273855..bf78fc78eff 100644
--- a/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
+++ b/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.3 2021/07/25 14:05:03 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.4 2021/10/18 14:46:37 schwarze Exp $
 .\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
@@ -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: July 25 2021 $
+.Dd $Mdocdate: October 18 2021 $
 .Dt X509_STORE_CTX_SET_FLAGS 3
 .Os
 .Sh NAME
@@ -393,6 +393,7 @@ The other functions provide no diagnostics.
 .Xr X509_STORE_new 3 ,
 .Xr X509_STORE_set1_param 3 ,
 .Xr X509_verify_cert 3 ,
+.Xr X509_VERIFY_PARAM_new 3 ,
 .Xr X509_VERIFY_PARAM_set_flags 3
 .Sh HISTORY
 .Fn X509_STORE_CTX_set_depth
diff --git a/lib/libcrypto/man/X509_STORE_set1_param.3 b/lib/libcrypto/man/X509_STORE_set1_param.3
index b44293966b5..13caccb3c05 100644
--- a/lib/libcrypto/man/X509_STORE_set1_param.3
+++ b/lib/libcrypto/man/X509_STORE_set1_param.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_set1_param.3,v 1.17 2021/07/31 14:54:34 schwarze Exp $
+.\" $OpenBSD: X509_STORE_set1_param.3,v 1.18 2021/10/18 14:46:37 schwarze Exp $
 .\" content checked up to:
 .\" OpenSSL man3/X509_STORE_add_cert b0edda11 Mar 20 13:00:17 2018 +0000
 .\" OpenSSL man3/X509_STORE_get0_param e90fc053 Jul 15 09:39:45 2017 -0400
@@ -17,7 +17,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: July 31 2021 $
+.Dd $Mdocdate: October 18 2021 $
 .Dt X509_STORE_SET1_PARAM 3
 .Os
 .Sh NAME
@@ -197,6 +197,7 @@ on failure.
 .Xr X509_STORE_CTX_set0_param 3 ,
 .Xr X509_STORE_load_locations 3 ,
 .Xr X509_STORE_new 3 ,
+.Xr X509_VERIFY_PARAM_new 3 ,
 .Xr X509_VERIFY_PARAM_set_flags 3
 .Sh HISTORY
 .Fn X509_STORE_add_cert
diff --git a/lib/libcrypto/man/X509_VERIFY_PARAM_new.3 b/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
new file mode 100644
index 00000000000..05a36a4f795
--- /dev/null
+++ b/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 .
diff --git a/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 b/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
index ea3c867b8b6..a90fe6ea845 100644
--- a/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
+++ b/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.17 2021/07/23 16:43:56 schwarze Exp $
+.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.18 2021/10/18 14:46:37 schwarze Exp $
 .\" full merge up to: OpenSSL d33def66 Feb 9 14:17:13 2016 -0500
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
@@ -68,12 +68,10 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 23 2021 $
+.Dd $Mdocdate: October 18 2021 $
 .Dt X509_VERIFY_PARAM_SET_FLAGS 3
 .Os
 .Sh NAME
-.Nm X509_VERIFY_PARAM_new ,
-.Nm X509_VERIFY_PARAM_free ,
 .Nm X509_VERIFY_PARAM_get0_name ,
 .Nm X509_VERIFY_PARAM_set1_name ,
 .Nm X509_VERIFY_PARAM_set_flags ,
@@ -92,23 +90,10 @@
 .Nm X509_VERIFY_PARAM_get0_peername ,
 .Nm X509_VERIFY_PARAM_set1_email ,
 .Nm X509_VERIFY_PARAM_set1_ip ,
-.Nm X509_VERIFY_PARAM_set1_ip_asc ,
-.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
+.Nm X509_VERIFY_PARAM_set1_ip_asc
 .Nd X509 verification parameters
 .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 const char *
 .Fo X509_VERIFY_PARAM_get0_name
 .Fa "const X509_VERIFY_PARAM *param"
@@ -204,46 +189,11 @@
 .Fa "X509_VERIFY_PARAM *param"
 .Fa "const char *ipasc"
 .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
 These functions manipulate an
 .Vt X509_VERIFY_PARAM
 object associated with a certificate verification operation.
 .Pp
-.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_get0_name
 returns the name of the given
 .Fa param
@@ -458,62 +408,15 @@ The condensed "::" notation is supported for IPv6 addresses.
 will fail if
 .Fa ipasc
 is unparsable.
-.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_set1_name ,
 .Fn X509_VERIFY_PARAM_set_flags ,
 .Fn X509_VERIFY_PARAM_clear_flags ,
 .Fn X509_VERIFY_PARAM_set_purpose ,
 .Fn X509_VERIFY_PARAM_set_trust ,
 .Fn X509_VERIFY_PARAM_add0_policy ,
-.Fn X509_VERIFY_PARAM_set1_policies ,
 and
-.Fn X509_VERIFY_PARAM_add0_table
+.Fn X509_VERIFY_PARAM_set1_policies
 return 1 for success or 0 for failure.
 .Pp
 .Fn X509_VERIFY_PARAM_set1_host ,
@@ -521,7 +424,7 @@ return 1 for success or 0 for failure.
 .Fn X509_VERIFY_PARAM_set1_email ,
 .Fn X509_VERIFY_PARAM_set1_ip ,
 and
-.Fn X509_VERIFY_PARAM_set1_ip_asc ,
+.Fn X509_VERIFY_PARAM_set1_ip_asc
 return 1 for success or 0 for failure.
 A failure from these routines will poison
 the
@@ -543,21 +446,6 @@ return pointers to strings that are only valid
 during the lifetime of the given
 .Fa param
 object and that must not be freed by the application program.
-.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 VERIFICATION FLAGS
 The verification flags consists of zero or more of the following
 flags OR'ed together.
@@ -702,12 +590,9 @@ X509_VERIFY_PARAM_free(param);
 .Xr SSL_set1_host 3 ,
 .Xr SSL_set1_param 3 ,
 .Xr X509_check_host 3 ,
-.Xr X509_STORE_CTX_set0_param 3 ,
-.Xr X509_STORE_set1_param 3 ,
-.Xr X509_verify_cert 3
+.Xr X509_verify_cert 3 ,
+.Xr X509_VERIFY_PARAM_new 3
 .Sh HISTORY
-.Fn X509_VERIFY_PARAM_new ,
-.Fn X509_VERIFY_PARAM_free ,
 .Fn X509_VERIFY_PARAM_set1_name ,
 .Fn X509_VERIFY_PARAM_set_flags ,
 .Fn X509_VERIFY_PARAM_set_purpose ,
@@ -716,11 +601,8 @@ X509_VERIFY_PARAM_free(param);
 .Fn X509_VERIFY_PARAM_add0_policy ,
 .Fn X509_VERIFY_PARAM_set1_policies ,
 .Fn X509_VERIFY_PARAM_set_depth ,
-.Fn X509_VERIFY_PARAM_get_depth ,
-.Fn X509_VERIFY_PARAM_add0_table ,
-.Fn X509_VERIFY_PARAM_lookup ,
 and
-.Fn X509_VERIFY_PARAM_table_cleanup
+.Fn X509_VERIFY_PARAM_get_depth
 first appeared in OpenSSL 0.9.8.
 .Fn X509_VERIFY_PARAM_clear_flags
 and
@@ -736,10 +618,8 @@ All these functions have been available since
 .Fn X509_VERIFY_PARAM_get0_peername ,
 .Fn X509_VERIFY_PARAM_set1_email ,
 .Fn X509_VERIFY_PARAM_set1_ip ,
-.Fn X509_VERIFY_PARAM_set1_ip_asc ,
-.Fn X509_VERIFY_PARAM_get_count ,
 and
-.Fn X509_VERIFY_PARAM_get0
+.Fn X509_VERIFY_PARAM_set1_ip_asc
 first appeared in OpenSSL 1.0.2 and have been available since
 .Ox 6.3 .
 .Sh BUGS