X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FX509_VERIFY_PARAM_set_flags.pod;h=1213627be7f45a7f19e7016c8b0b68e5acce0eac;hp=7765029766553518a8646e477b3ec00c35c0a650;hb=HEAD;hpb=4db296d9f0cf2855b358883a55b77a6b6f6848ba diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod index 7765029766..fcbbfc4c30 100644 --- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod +++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod @@ -10,11 +10,13 @@ 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_get0_host, 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_get0_email, X509_VERIFY_PARAM_set1_email, +X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_get1_ip_asc, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters @@ -26,7 +28,7 @@ X509_VERIFY_PARAM_set1_ip_asc unsigned long flags); int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, unsigned long flags); - unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); + unsigned long X509_VERIFY_PARAM_get_flags(const X509_VERIFY_PARAM *param); int X509_VERIFY_PARAM_set_inh_flags(X509_VERIFY_PARAM *param, uint32_t flags); @@ -50,6 +52,7 @@ X509_VERIFY_PARAM_set1_ip_asc int auth_level); int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param); + char *X509_VERIFY_PARAM_get0_host(X509_VERIFY_PARAM *param, int n); 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, @@ -57,9 +60,11 @@ X509_VERIFY_PARAM_set1_ip_asc 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); + char *X509_VERIFY_PARAM_get0_peername(const X509_VERIFY_PARAM *param); + char *X509_VERIFY_PARAM_get0_email(X509_VERIFY_PARAM *param); int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, const char *email, size_t emaillen); + char *X509_VERIFY_PARAM_get1_ip_asc(X509_VERIFY_PARAM *param); 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); @@ -70,7 +75,7 @@ These functions manipulate the B structure associated with a certificate verification operation. The X509_VERIFY_PARAM_set_flags() function sets the flags in B by oring -it with B. See the B section for a complete +it with B. See L for a complete description of values the B parameter can take. X509_VERIFY_PARAM_get_flags() returns the flags in B. @@ -84,7 +89,8 @@ X509_VERIFY_PARAM_clear_flags() clears the flags B in B. X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B to B. This determines the acceptable purpose of the certificate -chain, for example SSL client or SSL server. +chain, for example B. +The purpose requirement is cleared if B is 0. X509_VERIFY_PARAM_set_trust() sets the trust setting in B to B. @@ -92,8 +98,9 @@ B. X509_VERIFY_PARAM_set_time() sets the verification time in B to B. Normally the current time is used. -X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled -by default) and adds B to the acceptable policy set. +X509_VERIFY_PARAM_add0_policy() adds B to the acceptable policy set. +Contrary to preexisting documentation of this function it does not enable +policy checking. X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled by default) and sets the acceptable policy set to B. Any existing @@ -107,8 +114,8 @@ A maximal depth chain contains 2 more certificates than the limit, since neither the end-entity certificate nor the trust-anchor count against this limit. Thus a B limit of 0 only allows the end-entity certificate to be signed -directly by the trust-anchor, while with a B limit of 1 there can be one -intermediate CA certificate between the trust-anchor and the end-entity +directly by the trust anchor, while with a B limit of 1 there can be one +intermediate CA certificate between the trust anchor and the end-entity certificate. X509_VERIFY_PARAM_set_auth_level() sets the authentication security level to @@ -128,19 +135,39 @@ Security level 1 requires at least 80-bit-equivalent security and is broadly interoperable, though it will, for example, reject MD5 signatures or RSA keys shorter than 1024 bits. +X509_VERIFY_PARAM_get0_host() returns the Bth expected DNS hostname that has +been set using X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host(). +To obtain all names start with B = 0 and increment B as long as no NULL +pointer is returned. + X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to -B clearing any previously specified host name or names. If +B clearing any previously specified hostname. 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 precedence over the B flag. X509_VERIFY_PARAM_get_hostflags() returns any host flags previously set via a call to X509_VERIFY_PARAM_set_hostflags(). @@ -162,12 +189,17 @@ 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_get0_email() returns the expected RFC822 email address. + 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_get1_ip_asc() returns the expected IP address as a string. +The caller is responsible for freeing it. + 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 @@ -190,6 +222,10 @@ 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_get0_host(), X509_VERIFY_PARAM_get0_email(), and +X509_VERIFY_PARAM_get1_ip_asc(), return the string pointers specified above +or NULL if the respective value has not been set or on error. + X509_VERIFY_PARAM_get_flags() returns the current verification flags. X509_VERIFY_PARAM_get_hostflags() returns any current host flags. @@ -215,8 +251,8 @@ certificate. An error occurs if a suitable CRL cannot be found. B enables CRL checking for the entire certificate chain. -B disabled critical extension checking. By default -any unhandled critical extensions in certificates or (if checked) CRLs results +B disables critical extension checking. By default +any unhandled critical extensions in certificates or (if checked) CRLs result in a fatal error. If this flag is set unhandled critical extensions are ignored. B setting this option for anything other than debugging purposes can be a security risk. Finer control over which extensions are @@ -249,24 +285,27 @@ they are enabled. 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 -certificate signature. By default this check is disabled because it doesn't +B requests checking the signature of +the last certificate in a chain if the certificate is supposedly self-signed. +This is prohibited and will result in an error if it is a non-conforming CA +certificate with key usage restrictions not including the I bit. +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 -are not treated as fatal errors. +check the signature anyway. A side effect of not checking the self-signature +of such a certificate is that disabled or unsupported message digests used for +the signature are not treated as fatal errors. -When B is set, construction of the certificate chain -in L will search the trust store for issuer certificates +When B is set, which is always the case since +OpenSSL 1.1.0, construction of the certificate chain +in L searches 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. +explicit trust settings (see "TRUST SETTINGS" in L). -The B flag suppresses checking for alternative -chains. +The B flag could have been used before OpenSSL 1.1.0 +to suppress checking for alternative chains. By default, unless B 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 @@ -275,15 +314,15 @@ 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 +The B flag causes non-self-signed certificates in the +trust store to be treated as trust anchors, in the same way as 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. +This makes it possible to trust self-issued certificates as well as certificates +issued by an intermediate CA without having to trust their ancestor root CA. +With OpenSSL 1.1.0 and later and B set, chain +construction stops as soon as the first certificate contained in the trust store +is added to the chain, whether that certificate is a self-signed "root" +certificate or a not self-signed "intermediate" or self-issued 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. @@ -331,7 +370,7 @@ If CRLs checking is enable CRLs are expected to be available in the corresponding B structure. No attempt is made to download CRLs from the CRL distribution points extension. -=head1 EXAMPLE +=head1 EXAMPLES Enable CRL checking when performing certificate verification during SSL connections associated with an B structure B: @@ -349,21 +388,28 @@ L, L, L, L, -L +L =head1 HISTORY -The B flag was added in OpenSSL 1.1.0 -The flag B was deprecated in -OpenSSL 1.1.0, and has no effect. +The B flag was added in OpenSSL 1.1.0. +The flag B was deprecated in OpenSSL 1.1.0 +and has no effect. + +The X509_VERIFY_PARAM_get_hostflags() function was added in OpenSSL 1.1.0i. + +The X509_VERIFY_PARAM_get0_host(), X509_VERIFY_PARAM_get0_email(), +and X509_VERIFY_PARAM_get1_ip_asc() functions were added in OpenSSL 3.0. -X509_VERIFY_PARAM_get_hostflags() was added in OpenSSL 1.1.0i. +The function X509_VERIFY_PARAM_add0_policy() was historically documented as +enabling policy checking however the implementation has never done this. +The documentation was changed to align with the implementation. =head1 COPYRIGHT -Copyright 2009-2018 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2009-2023 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at L.