X-Git-Url: https://git.openssl.org/?a=blobdiff_plain;f=doc%2Fcrypto%2FX509_VERIFY_PARAM_set_flags.pod;h=066ce0fb3ad4e2e68fd5531ea438d8be310b5ef0;hb=c5f2810581380bc248279207a4c58a126047acd8;hp=b68eece033876b1732ba092ecee759b9f04901aa;hpb=9074df868464024c288c0ba232042bf06f2823e8;p=openssl.git diff --git a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod index b68eece033..066ce0fb3a 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 @@ -26,6 +26,19 @@ X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_ge void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); + int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, + 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 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); + =head1 DESCRIPTION These functions manipulate the B structure associated with @@ -61,12 +74,63 @@ 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 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 +identifier 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 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. + +X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B. +The B argument is in binary format, in network byte-order and +B must be set to 4 for IPv4 and 16 for IPv6. When an IP +address is specified, certificate verification automatically invokes +L. + +X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to +B. The B 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. + =head1 RETURN VALUES -X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), +X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), -X509_VERIFY_PARAM_add0_policy() and X509_VERIFY_PARAM_set1_policies() return 1 -for success and 0 for failure. +X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(), +X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_set_hostflags(), +X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and +X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for +failure. X509_VERIFY_PARAM_get_flags() returns the current verification flags. @@ -93,13 +157,13 @@ ignored. B setting this option for anything other than debugging purposes can be a security risk. Finer control over which extensions are supported can be performed in the verification callback. -THe B flag disables workarounds for some broken +The B flag disables workarounds for some broken certificates and makes the verification strictly apply B rules. B enables proxy certificate verification. B enables certificate policy checking, by default -no policy checking is peformed. Additional information is sent to the +no policy checking is performed. Additional information is sent to the verification callback relating to policy checking. B, B and @@ -113,15 +177,15 @@ a special status code is set to the verification callback. This permits it to examine the valid policy tree and perform additional checks or simply log it for debugging purposes. -By default some addtional features such as indirect CRLs and CRLs signed by +By default some additional features such as indirect CRLs and CRLs signed by different keys are disabled. If B is set they are enabled. -If B ise set delta CRLs (if present) are used to +If B is set delta CRLs (if present) are used to determine certificate status. If not set deltas are ignored. B enables checking of the root CA self signed -cerificate signature. By default this check is disabled because it doesn't +certificate signature. By default this check is disabled because it doesn't add any additional security but in some cases applications might want to check the signature anyway. A side effect of not checking the root CA signature is that disabled or unsupported message digests on the root CA @@ -133,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 @@ -162,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