1 files changed, 145 insertions, 3 deletions

diff --git a/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3 b/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
index 05a36a4f79..ffde66cde5 100644
--- a/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
+++ b/src/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_VERIFY_PARAM_new.3,v 1.1 2021/10/18 14:46:37 schwarze Exp $
+.\" $OpenBSD: X509_VERIFY_PARAM_new.3,v 1.2 2021/10/18 18:20:39 schwarze Exp $
 .\"
 .\" Copyright (c) 2018, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -19,19 +19,31 @@
 .Os
 .Sh NAME
 .Nm X509_VERIFY_PARAM_new ,
+.Nm X509_VERIFY_PARAM_inherit ,
+.Nm X509_VERIFY_PARAM_set1 ,
 .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
+.Nd X509 verification parameter objects
 .Sh SYNOPSIS
 .In openssl/x509_vfy.h
 .Ft X509_VERIFY_PARAM *
 .Fo X509_VERIFY_PARAM_new
 .Fa void
 .Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_inherit
+.Fa "X509_VERIFY_PARAM *destination"
+.Fa "const X509_VERIFY_PARAM *source"
+.Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_set1
+.Fa "X509_VERIFY_PARAM *destination"
+.Fa "const X509_VERIFY_PARAM *source"
+.Fc
 .Ft void
 .Fo X509_VERIFY_PARAM_free
 .Fa "X509_VERIFY_PARAM *param"
@@ -62,6 +74,131 @@ allocates and initializes an empty
 .Vt X509_VERIFY_PARAM
 object.
 .Pp
+.Fn X509_VERIFY_PARAM_inherit
+copies some data from the
+.Fa source
+object to the
+.Fa destination
+object.
+.Pp
+The verification flags set with
+.Xr X509_VERIFY_PARAM_set_flags 3
+in the
+.Fa source
+object are always OR'ed into the verification flags of the
+.Fa destination
+object.
+.Pp
+Fields having their default value in the
+.Fa source
+object are not copied.
+.Pp
+By default, fields in the
+.Fa destination
+object already having a non-default value are not overwritten.
+However, if at least one of the
+.Fa source
+or
+.Fa destination
+objects was created during a call to
+.Xr X509_STORE_CTX_init 3
+that did not have a
+.Fa store
+argument, and if that object was not previously used as the
+.Fa destination
+in an earlier call to
+.Fn X509_VERIFY_PARAM_inherit ,
+this restriction is waived and even non-default fields in the
+.Fa destination
+object get overwritten.
+If fields overwritten in this way contain pointers to allocated memory,
+that memory is freed.
+.Pp
+As far as permitted by the above rules, the following fields are copied:
+.Bl -bullet -width 1n
+.It
+the verification purpose identifier set with
+.Xr X509_VERIFY_PARAM_set_purpose 3
+.It
+the trust setting set with
+.Xr X509_VERIFY_PARAM_set_trust 3
+.It
+the verification time set with
+.Xr X509_VERIFY_PARAM_set_time 3 ;
+in this case, the only condition is that
+.Dv X509_V_FLAG_USE_CHECK_TIME
+is not set in the
+.Fa destination
+object, whereas the time value in the
+.Fa destination
+object is not inspected before overwriting it
+.It
+the acceptable policy set set with
+.Xr X509_VERIFY_PARAM_set1_policies 3
+.It
+the maximum verification depth set with
+.Xr X509_VERIFY_PARAM_set_depth 3
+.It
+the list of expected DNS hostnames built with
+.Xr X509_VERIFY_PARAM_set1_host 3
+and
+.Xr X509_VERIFY_PARAM_add1_host 3 ;
+if this list is copied, any flags that were set with
+.Xr X509_VERIFY_PARAM_set_hostflags 3
+are copied together with the list, without inspecting any such flags
+that may already be present in the
+.Fa destination
+object before overwriting them
+.It
+the expected RFC 822 email address set with
+.Xr X509_VERIFY_PARAM_set1_email 3
+.It
+the expected IP address set with
+.Xr X509_VERIFY_PARAM_set1_ip 3
+or
+.Xr X509_VERIFY_PARAM_set1_ip_asc 3
+.El
+.Pp
+Some data that may be contained in the
+.Fa source
+object is never copied, for example the subject name of the peer
+certificate that can be retrieved with
+.Xr X509_VERIFY_PARAM_get0_peername 3 .
+.Pp
+If
+.Fa source
+is a
+.Dv NULL
+pointer, the function has no effect but returns successfully.
+.Pp
+.Fn X509_VERIFY_PARAM_set1
+is identical to
+.Fn X509_VERIFY_PARAM_inherit
+except that fields in the
+.Fa destination
+object are overwritten even if they do not match their default values.
+Still, fields having their default value in the
+.Fa source
+object are not copied.
+.Pp
+If
+.Fn X509_VERIFY_PARAM_inherit
+or
+.Fn X509_VERIFY_PARAM_set1
+fail, partial copying may have occurred, so all data in the
+.Fa destination
+object should be regarded as invalid.
+.Pp
+.Fn X509_VERIFY_PARAM_inherit
+is used internally by
+.Xr X509_STORE_CTX_init 3
+and by
+.Xr X509_STORE_CTX_set_default 3 ,
+and
+.Fn X509_VERIFY_PARAM_set1
+is used internally by
+.Xr X509_STORE_set1_param 3 .
+.Pp
 .Fn X509_VERIFY_PARAM_free
 clears all data contained in
 .Fa param
@@ -118,8 +255,11 @@ returns a pointer to the new object, or
 .Dv NULL
 on allocation failure.
 .Pp
+.Fn X509_VERIFY_PARAM_inherit ,
+.Fn X509_VERIFY_PARAM_set1 ,
+and
 .Fn X509_VERIFY_PARAM_add0_table
-returns 1 for success or 0 for failure.
+return 1 for success or 0 for failure.
 .Pp
 .Fn X509_VERIFY_PARAM_lookup
 and
@@ -143,6 +283,8 @@ returns a number of objects.
 .Xr X509_VERIFY_PARAM_set_flags 3
 .Sh HISTORY
 .Fn X509_VERIFY_PARAM_new ,
+.Fn X509_VERIFY_PARAM_inherit ,
+.Fn X509_VERIFY_PARAM_set1 ,
 .Fn X509_VERIFY_PARAM_free ,
 .Fn X509_VERIFY_PARAM_add0_table ,
 .Fn X509_VERIFY_PARAM_lookup ,