Document three more functions recently made public by jsing@

as requested by jsing@, and also document six more related functions
that have already been public before that.
OpenSSL fails to document any of these.

1 files changed, 185 insertions, 18 deletions

diff --git a/src/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 b/src/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
index b459e75863..04f38c8ec5 100644
--- a/src/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
+++ b/src/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
@@ -1,8 +1,25 @@
-.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.6 2018/02/11 03:33:21 schwarze Exp $
+.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.7 2018/02/11 20:59:30 schwarze Exp $
 .\" full merge up to: OpenSSL d33def66 Feb 9 14:17:13 2016 -0500
 .\" selective merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2018 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.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>
 .\" and Viktor Dukhovni <viktor@dukhovni.org>.
 .\" Copyright (c) 2009, 2013, 2014, 2015, 2016, 2017 The OpenSSL Project.
 .\" All rights reserved.
@@ -55,6 +72,10 @@
 .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 ,
 .Nm X509_VERIFY_PARAM_clear_flags ,
 .Nm X509_VERIFY_PARAM_get_flags ,
@@ -71,10 +92,32 @@
 .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_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
 .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"
+.Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_set1_name
+.Fa "X509_VERIFY_PARAM *param"
+.Fa "const char *name"
+.Fc
 .Ft int
 .Fo X509_VERIFY_PARAM_set_flags
 .Fa "X509_VERIFY_PARAM *param"
@@ -161,14 +204,77 @@
 .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 the
+These functions manipulate an
 .Vt X509_VERIFY_PARAM
-structure associated with a certificate verification operation.
+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
+object, usually describing its purpose, for example
+.Qq default ,
+.Qq pkcs7 ,
+.Qq smime_sign ,
+.Qq ssl_client ,
+or
+.Qq ssl_server .
+For user-defined objects, the returned pointer may be
+.Dv NULL
+even if the object is otherwise valid.
+.Pp
+.Fn X509_VERIFY_PARAM_set1_name
+sets the name of
+.Fa param
+to a copy of
+.Fa name ,
+or to
+.Dv NULL
+if
+.Fa name
+is
+.Dv NULL .
+This function is quite dangerous because it invalidates pointers
+previously returned from
+.Fn X509_VERIFY_PARAM_get0_name .
 .Pp
-The
 .Fn X509_VERIFY_PARAM_set_flags
-function sets the flags in
+sets the flags in
 .Fa param
 by OR'ing it with
 .Fa flags .
@@ -283,11 +389,6 @@ When wildcard matching is not disabled, or when a reference identifier
 specifies a parent domain (starts with ".") rather than a hostname, the
 peer name may be a wildcard name or a sub-domain of the reference
 identifier respectively.
-The return string is allocated by the library and is no longer valid
-once the associated
-.Fa param
-argument is freed.
-Applications must not free the return value.
 .Pp
 .Fn X509_VERIFY_PARAM_set1_email
 sets the expected RFC822 email address to
@@ -324,7 +425,54 @@ The
 argument is a NUL-terminal ASCII string:
 dotted decimal quad for IPv4 and colon-separated hexadecimal for IPv6.
 The condensed "::" notation is supported for IPv6 addresses.
+.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 ,
@@ -335,20 +483,39 @@ The condensed "::" notation is supported for IPv6 addresses.
 .Fn X509_VERIFY_PARAM_add1_host ,
 .Fn X509_VERIFY_PARAM_set1_email ,
 .Fn X509_VERIFY_PARAM_set1_ip ,
+.Fn X509_VERIFY_PARAM_set1_ip_asc ,
 and
-.Fn X509_VERIFY_PARAM_set1_ip_asc
+.Fn X509_VERIFY_PARAM_add0_table
 return 1 for success or 0 for failure.
 .Pp
 .Fn X509_VERIFY_PARAM_get_flags
 returns the current verification flags.
 .Pp
-.Fn X509_VERIFY_PARAM_set_time
-and
-.Fn X509_VERIFY_PARAM_set_depth
-do not return values.
-.Pp
 .Fn X509_VERIFY_PARAM_get_depth
 returns the current verification depth.
+.Pp
+.Fn X509_VERIFY_PARAM_get0_name
+and
+.Fn X509_VERIFY_PARAM_get0_peername
+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.