Merge documentation from OpenSSL for seven functions

that jsing@ recently exposed publicly in libcrypto.
Requested by jsing@.

1 files changed, 196 insertions, 7 deletions

diff --git a/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 b/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
index bb9b0e127b7..b459e758632 100644
--- a/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
+++ b/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3
@@ -1,8 +1,11 @@
-.\"	$OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.5 2017/01/06 21:30:27 schwarze Exp $
-.\"	OpenSSL 2b4ffc65 Dec 23 19:28:30 2013 +0100
+.\" $OpenBSD: X509_VERIFY_PARAM_set_flags.3,v 1.6 2018/02/11 03:33:21 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>.
-.\" Copyright (c) 2009, 2013 The OpenSSL Project.  All rights reserved.
+.\" This 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.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -48,7 +51,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: January 6 2017 $
+.Dd $Mdocdate: February 11 2018 $
 .Dt X509_VERIFY_PARAM_SET_FLAGS 3
 .Os
 .Sh NAME
@@ -61,7 +64,14 @@
 .Nm X509_VERIFY_PARAM_add0_policy ,
 .Nm X509_VERIFY_PARAM_set1_policies ,
 .Nm X509_VERIFY_PARAM_set_depth ,
-.Nm X509_VERIFY_PARAM_get_depth
+.Nm X509_VERIFY_PARAM_get_depth ,
+.Nm X509_VERIFY_PARAM_set1_host ,
+.Nm X509_VERIFY_PARAM_add1_host ,
+.Nm X509_VERIFY_PARAM_set_hostflags ,
+.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
 .Nd X509 verification parameters
 .Sh SYNOPSIS
 .In openssl/x509_vfy.h
@@ -113,6 +123,44 @@
 .Fo X509_VERIFY_PARAM_get_depth
 .Fa "const X509_VERIFY_PARAM *param"
 .Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_set1_host
+.Fa "X509_VERIFY_PARAM *param"
+.Fa "const char *name"
+.Fa "size_t namelen"
+.Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_add1_host
+.Fa "X509_VERIFY_PARAM *param"
+.Fa "const char *name"
+.Fa "size_t namelen"
+.Fc
+.Ft void
+.Fo X509_VERIFY_PARAM_set_hostflags
+.Fa "X509_VERIFY_PARAM *param"
+.Fa "unsigned int flags"
+.Fc
+.Ft char *
+.Fo X509_VERIFY_PARAM_get0_peername
+.Fa "X509_VERIFY_PARAM *param"
+.Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_set1_email
+.Fa "X509_VERIFY_PARAM *param"
+.Fa "const char *email"
+.Fa "size_t emaillen"
+.Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_set1_ip
+.Fa "X509_VERIFY_PARAM *param"
+.Fa "const unsigned char *ip"
+.Fa "size_t iplen"
+.Fc
+.Ft int
+.Fo X509_VERIFY_PARAM_set1_ip_asc
+.Fa "X509_VERIFY_PARAM *param"
+.Fa "const char *ipasc"
+.Fc
 .Sh DESCRIPTION
 These functions manipulate the
 .Vt X509_VERIFY_PARAM
@@ -182,14 +230,113 @@ sets the maximum verification depth to
 .Fa depth .
 That is the maximum number of untrusted CA certificates that can appear
 in a chain.
+.Pp
+.Fn X509_VERIFY_PARAM_set1_host
+sets the expected DNS hostname to
+.Fa name
+clearing any previously specified host name or names.
+If
+.Fa name
+is
+.Dv NULL
+or empty, the list of hostnames is cleared, and name checks are not
+performed on the peer certificate.
+If
+.Fa name
+is NUL-terminated,
+.Fa namelen
+may be zero, otherwise
+.Fa namelen
+must be set to the length of
+.Fa name .
+When a hostname is specified, certificate verification automatically
+invokes
+.Xr X509_check_host 3
+with flags equal to the
+.Fa flags
+argument given to
+.Fn X509_VERIFY_PARAM_set_hostflags
+(default zero).
+.Pp
+.Fn X509_VERIFY_PARAM_add1_host
+adds
+.Fa name
+as an additional reference identifier that can match the peer's
+certificate.
+Any previous names set via
+.Fn X509_VERIFY_PARAM_set1_host
+and
+.Fn X509_VERIFY_PARAM_add1_host
+are retained.
+No change is made if
+.Fa name
+is
+.Dv NULL
+or empty.
+When multiple names are configured, the peer is considered verified when
+any name matches.
+.Pp
+.Fn X509_VERIFY_PARAM_get0_peername
+returns the DNS hostname or subject CommonName from the peer certificate
+that matched one of the reference identifiers.
+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
+.Fa email .
+If
+.Fa email
+is NUL-terminated,
+.Fa emaillen
+may be zero, otherwise
+.Fa emaillen
+must be set to the length of
+.Fa email .
+When an email address is specified, certificate verification
+automatically invokes
+.Xr X509_check_email 3 .
+.Pp
+.Fn X509_VERIFY_PARAM_set1_ip
+sets the expected IP address to
+.Fa ip .
+The
+.Fa ip
+argument is in binary format, in network byte-order, and
+.Fa iplen
+must be set to 4 for IPv4 and 16 for IPv6.
+When an IP address is specified,
+certificate verification automatically invokes
+.Xr X509_check_ip 3 .
+.Pp
+.Fn X509_VERIFY_PARAM_set1_ip_asc
+sets the expected IP address to
+.Fa ipasc .
+The
+.Fa ipasc
+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.
 .Sh RETURN VALUES
 .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 ,
+.Fn X509_VERIFY_PARAM_set1_host ,
+.Fn X509_VERIFY_PARAM_add1_host ,
+.Fn X509_VERIFY_PARAM_set1_email ,
+.Fn X509_VERIFY_PARAM_set1_ip ,
 and
-.Fn X509_VERIFY_PARAM_set1_policies
+.Fn X509_VERIFY_PARAM_set1_ip_asc
 return 1 for success or 0 for failure.
 .Pp
 .Fn X509_VERIFY_PARAM_get_flags
@@ -288,6 +435,46 @@ If this flag is set then additional status codes will be sent to the
 verification callback and it
 .Sy must
 be prepared to handle such cases without assuming they are hard errors.
+.Pp
+When
+.Dv X509_V_FLAG_TRUSTED_FIRST
+is set, construction of the certificate chain in
+.Xr X509_verify_cert 3
+will search the trust store for issuer certificates before searching the
+provided untrusted certificates.
+Local issuer certificates are often more likely to satisfy local
+security requirements and lead to a locally trusted root.
+This is especially important when some certificates in the trust store
+have explicit trust settings; see the trust settings options of the
+.Cm x509
+command in
+.Xr openssl 1 .
+.Pp
+The
+.Dv X509_V_FLAG_NO_ALT_CHAINS
+flag suppresses checking for alternative chains.
+By default, unless
+.Dv X509_V_FLAG_TRUSTED_FIRST
+is set, when building a certificate chain, if the first certificate
+chain found is not trusted, then OpenSSL will attempt to replace
+untrusted certificates supplied by the peer with certificates from the
+trust store to see if an alternative chain can be found that is trusted.
+.Pp
+The
+.Dv X509_V_FLAG_PARTIAL_CHAIN
+flag causes intermediate certificates in the trust store to be treated
+as trust-anchors, in the same way as the self-signed root CA
+certificates.
+This makes it possible to trust certificates issued by an intermediate
+CA without having to trust its ancestor root CA.
+.Pp
+The
+.Dv X509_V_FLAG_NO_CHECK_TIME
+flag suppresses checking the validity period of certificates and CRLs
+against the current time.
+If
+.Fn X509_VERIFY_PARAM_set_time
+is used to specify a verification time, the check is not suppressed.
 .Sh EXAMPLES
 Enable CRL checking when performing certificate verification during
 SSL connections associated with an
@@ -296,12 +483,14 @@ structure
 .Fa ctx :
 .Bd -literal -offset indent
 X509_VERIFY_PARAM *param;
+
 param = X509_VERIFY_PARAM_new();
 X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK);
 SSL_CTX_set1_param(ctx, param);
 X509_VERIFY_PARAM_free(param);
 .Ed
 .Sh SEE ALSO
+.Xr X509_check_host 3 ,
 .Xr X509_verify_cert 3
 .Sh BUGS
 Delta CRL checking is currently primitive.