-.\" $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>
.\"
.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"
.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
.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
.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 ,
projects / openbsd / commitdiff