From: schwarze <schwarze@openbsd.org>
Date: Mon, 18 Oct 2021 18:20:39 +0000 (+0000)
Subject: document X509_VERIFY_PARAM_inherit(3) and X509_VERIFY_PARAM_set1(3)
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=7d88aab0f58ccee00d9e5f3dedf11d91fa7f1713;p=openbsd

document X509_VERIFY_PARAM_inherit(3) and X509_VERIFY_PARAM_set1(3)
---

diff --git a/lib/libcrypto/man/X509_STORE_CTX_new.3 b/lib/libcrypto/man/X509_STORE_CTX_new.3
index f2850451944..d1aca9527b9 100644
--- a/lib/libcrypto/man/X509_STORE_CTX_new.3
+++ b/lib/libcrypto/man/X509_STORE_CTX_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.24 2021/08/02 16:21:11 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.25 2021/10/18 18:20:39 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: August 2 2021 $
+.Dd $Mdocdate: October 18 2021 $
 .Dt X509_STORE_CTX_NEW 3
 .Os
 .Sh NAME
@@ -182,6 +182,10 @@ not freeing them before
 .Fn X509_STORE_CTX_free
 is called on
 .Fa ctx .
+If a
+.Fa store
+is provided, the verification parameters contained in it are copied using
+.Xr X509_VERIFY_PARAM_inherit 3 .
 .Pp
 .Fn X509_STORE_CTX_cleanup
 internally cleans up
@@ -323,6 +327,7 @@ if no set of additional certificates was provided.
 .Xr X509_STORE_new 3 ,
 .Xr X509_STORE_set1_param 3 ,
 .Xr X509_verify_cert 3 ,
+.Xr X509_VERIFY_PARAM_inherit 3 ,
 .Xr X509_VERIFY_PARAM_set_flags 3
 .Sh HISTORY
 .Fn X509_STORE_CTX_init ,
diff --git a/lib/libcrypto/man/X509_STORE_CTX_set_flags.3 b/lib/libcrypto/man/X509_STORE_CTX_set_flags.3
index bf78fc78eff..4307a3ae98d 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.4 2021/10/18 14:46:37 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_set_flags.3,v 1.5 2021/10/18 18:20:39 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
 .\"
@@ -286,7 +286,9 @@ looks up and sets the default verification method to
 This uses the function
 .Xr X509_VERIFY_PARAM_lookup 3
 to find an appropriate set of parameters from
-.Fa name .
+.Fa name
+and copies them using
+.Xr X509_VERIFY_PARAM_inherit 3 .
 .Sh RETURN VALUES
 .Fn X509_STORE_CTX_set_trust
 returns 1 if the
diff --git a/lib/libcrypto/man/X509_STORE_set1_param.3 b/lib/libcrypto/man/X509_STORE_set1_param.3
index 13caccb3c05..354d8738541 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.18 2021/10/18 14:46:37 schwarze Exp $
+.\" $OpenBSD: X509_STORE_set1_param.3,v 1.19 2021/10/18 18:20:39 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
@@ -102,6 +102,8 @@
 .Fn X509_STORE_set1_param
 copies the verification parameters from
 .Fa pm
+using
+.Xr X509_VERIFY_PARAM_set1 3
 into the verification parameter object contained in the
 .Fa store .
 .Pp
diff --git a/lib/libcrypto/man/X509_VERIFY_PARAM_new.3 b/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
index 05a36a4f795..ffde66cde5c 100644
--- a/lib/libcrypto/man/X509_VERIFY_PARAM_new.3
+++ b/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 ,