X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fman3%2FX509_VERIFY_PARAM_set_flags.pod;h=61b52efeea84f05c4d1e4cd11890611482731c6e;hb=55a6250f1e7336e8a7d89fb609eb23398715ff6f;hp=2800cd441d74ade2bc49ae82613b918db60afcd8;hpb=99d63d4662e16afbeff49f29b48f1c87d5558ed0;p=oweals%2Fopenssl.git diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod index 2800cd441d..61b52efeea 100644 --- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod +++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod @@ -2,33 +2,52 @@ =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_auth_level, X509_VERIFY_PARAM_get_auth_level, 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 +X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, +X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, +X509_VERIFY_PARAM_get_inh_flags, X509_VERIFY_PARAM_set_inh_flags, +X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, +X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, +X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time, +X509_VERIFY_PARAM_get_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_get_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 #include int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, - unsigned long flags); + unsigned long flags); int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, - unsigned long flags); + unsigned long flags); unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); + int X509_VERIFY_PARAM_set_inh_flags(X509_VERIFY_PARAM *param, + uint32_t flags); + uint32_t X509_VERIFY_PARAM_get_inh_flags(const X509_VERIFY_PARAM *param); + int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); + time_t X509_VERIFY_PARAM_get_time(const X509_VERIFY_PARAM *param); int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, - ASN1_OBJECT *policy); + ASN1_OBJECT *policy); int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, - STACK_OF(ASN1_OBJECT) *policies); + STACK_OF(ASN1_OBJECT) *policies); void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param, - int auth_level); + int auth_level); int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param); int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, @@ -37,9 +56,10 @@ X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_ge const char *name, size_t namelen); void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param, unsigned int flags); + unsigned int X509_VERIFY_PARAM_get_hostflags(const X509_VERIFY_PARAM *param); 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); + 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); @@ -55,6 +75,11 @@ description of values the B parameter can take. X509_VERIFY_PARAM_get_flags() returns the flags in B. +X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in B +which specifies how verification flags are copied from one structure to +another. X509_VERIFY_PARAM_set_inh_flags() sets the inheritance flags. +See the B section for a description of these bits. + X509_VERIFY_PARAM_clear_flags() clears the flags B in B. X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B @@ -108,14 +133,32 @@ 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, +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 X509_VERIFY_PARAM_set_hostflags() (default zero). Applications are strongly advised to use this interface in preference to explicitly -calling L, hostname checks are out of scope +calling L, hostname checks may be 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. +be suppressed as appropriate when DANE verification is enabled. + +When the subject CommonName will not be ignored, whether as a result of the +B host flag, or because no DNS subject +alternative names are present in the certificate, any DNS name constraints in +issuer certificates apply to the subject CommonName as well as the subject +alternative name extension. + +When the subject CommonName will be ignored, whether as a result of the +B host flag, or because some DNS subject +alternative names are present in the certificate, DNS name constraints in +issuer certificates will not be applied to the subject DN. +As described in X509_check_host(3) the B +flag takes precendence over the B flag. + +X509_VERIFY_PARAM_get_hostflags() returns any host flags previously set via a +call to X509_VERIFY_PARAM_set_hostflags(). X509_VERIFY_PARAM_add1_host() adds B as an additional reference identifier that can match the peer's certificate. Any previous names @@ -154,6 +197,7 @@ 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_inh_flags(), X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(), X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(), @@ -163,6 +207,10 @@ failure. X509_VERIFY_PARAM_get_flags() returns the current verification flags. +X509_VERIFY_PARAM_get_hostflags() returns any current host flags. + +X509_VERIFY_PARAM_get_inh_flags() returns the current inheritance flags. + X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return values. @@ -223,10 +271,14 @@ 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 are not treated as fatal errors. -If B is set, when constructing the certificate chain, -L will search the trust store for issuer certificates before -searching the provided untrusted certificates. -As of OpenSSL 1.1.0 this option is on by default and cannot be disabled. +When B is set, construction of the certificate chain +in L 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 "TRUST SETTINGS" in L). +As of OpenSSL 1.1.0 this option is on by default. The B flag suppresses checking for alternative chains. @@ -238,15 +290,51 @@ found that is trusted. As of OpenSSL 1.1.0, with B always set, this option has no effect. +The B 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. +With OpenSSL 1.1.0 and later and set, chain +construction stops as soon as the first certificate from the trust store is +added to the chain, whether that certificate is a self-signed "root" +certificate or a not self-signed intermediate certificate. +Thus, when an intermediate certificate is found in the trust store, the +verified chain passed to callbacks may be shorter than it otherwise would +be without the B flag. + The B flag suppresses checking the validity period of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time() is used to specify a verification time, the check is not suppressed. +=head1 INHERITANCE FLAGS + +These flags specify how parameters are "inherited" from one structure to +another. + +If B is set then the current setting is zeroed +after the next call. + +If B is set then no values are copied. This overrides +all of the following flags. + +If B is set then anything set in the source is copied +to the destination. Effectively the values in "to" become default values +which will be used only if nothing new is set in "from". This is the +default. + +If B is set then all value are copied across whether +they are set or not. Flags is still Ored though. + +If B is set then the flags value is copied instead +of ORed. + =head1 NOTES The above functions should be used to manipulate verification parameters -instead of legacy functions which work in specific structures such as -X509_STORE_CTX_set_flags(). +instead of functions which work in specific structures such as +X509_STORE_CTX_set_flags() which are likely to be deprecated in a future +release. =head1 BUGS @@ -263,28 +351,32 @@ CRLs from the CRL distribution points extension. Enable CRL checking when performing certificate verification during SSL connections associated with an B structure B: - 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); + 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); =head1 SEE ALSO L, L, L, -L +L, +L =head1 HISTORY The B flag was added in OpenSSL 1.1.0 -The legacy B flag is deprecated as of +The flag B was deprecated in OpenSSL 1.1.0, and has no effect. +X509_VERIFY_PARAM_get_hostflags() was added in OpenSSL 1.1.0i. + =head1 COPYRIGHT -Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2009-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy