X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FX509_VERIFY_PARAM_set_flags.pod;h=d19dc1218c6e03841051c4afb52050697f5b937b;hp=1059d4ff84fee2aba4dffeb11202c5e08e8b995f;hb=fa7b01115bc33d9b40936688bb3c952dc93b645a;hpb=397a8e747dc3f964196caed5ca4e08d4b598362a diff --git a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod index 1059d4ff84..d19dc1218c 100644 --- a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod +++ b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod @@ -2,7 +2,7 @@ =head1 NAME -X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 verification parameters +X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters =head1 SYNOPSIS @@ -27,15 +27,17 @@ X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_ge int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, - const unsigned char *name, size_t namelen); + const char *name, size_t namelen); + int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param, + const char *name, size_t namelen); void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param, unsigned int flags); + char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param); int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, - const unsigned char *email, size_t emaillen); + const char *email, size_t emaillen); int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, const unsigned char *ip, size_t iplen); - int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, - const char *ipasc); + int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc); =head1 DESCRIPTION @@ -72,19 +74,39 @@ X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B. That is the maximum number of untrusted CA certificates that can appear in a chain. -X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to B. If -B is NUL-terminated, B may be zero, otherwise B must -be set to the length of B. When a hostname is specified, certificate -verification automatically invokes L with flags equal to -the B argument given to B (default -zero). Applications are strongly advised to use this interface in preference -to explicitly calling L, hostname checks are -out of scope with the DANE-EE(3) certificate usage, and the internal -check will be suppressed as appropriate when DANE support is added -to OpenSSL. +X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to +B clearing any previously specified host name or names. If +B is NULL, or empty the list of hostnames is cleared, and +name checks are not performed on the peer certificate. If B +is NUL-terminated, B may be zero, otherwise B +must be set to the length of B. When a hostname is specified, +certificate verification automatically invokes L +with flags equal to the B argument given to +B (default zero). Applications +are strongly advised to use this interface in preference to explicitly +calling L, hostname checks are out of scope +with the DANE-EE(3) certificate usage, and the internal check will +be suppressed as appropriate when DANE support is added to OpenSSL. + +X509_VERIFY_PARAM_add1_host() adds B as an additional reference +identifer that can match the peer's certificate. Any previous names +set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host() +are retained, no change is made if B is NULL or empty. When +multiple names are configured, the peer is considered verified when +any name matches. + +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 B argument is freed. Applications must not free +the return value. X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to -B. If B may be zero, otherwise +B. If B is NUL-terminated, B may be zero, otherwise B must be set to the length of B. When an email address is specified, certificate verification automatically invokes L. @@ -175,6 +197,12 @@ verification. If this flag is set then additional status codes will be sent to the verification callback and it B be prepared to handle such cases without assuming they are hard errors. +The B flag suppresses checking for alternative +chains. By default, when building a certificate chain, if the first certificate +chain found is not trusted, then OpenSSL will continue to check to see if an +alternative chain can be found that is trusted. With this flag set the behaviour +will match that of OpenSSL versions prior to 1.1.0. + =head1 NOTES The above functions should be used to manipulate verification parameters @@ -204,10 +232,13 @@ connections associated with an B structure B: =head1 SEE ALSO -L +L, +L, +L, +L =head1 HISTORY -TBA +The B flag was added in OpenSSL 1.1.0 =cut