These functions manipulate the B<X509_VERIFY_PARAM> structure associated with
a certificate verification operation.
-The X509_VERIFY_PARAM_set_flags() function sets the flags in
B<param> by oring
-it with B<flags>. See L</VERIFICATION FLAGS> for a complete
-description of values the B<flags> parameter can take.
+The X509_VERIFY_PARAM_set_flags() function sets the flags in
I<param> by oring
+it with I<flags>. See L</VERIFICATION FLAGS> for a complete
+description of values the I<flags> parameter can take.
-X509_VERIFY_PARAM_get_flags() returns the flags in
B<param>.
+X509_VERIFY_PARAM_get_flags() returns the flags in
I<param>.
-X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in
B<param>
+X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in
I<param>
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<INHERITANCE FLAGS> section for a description of these bits.
+See the L</INHERITANCE FLAGS> section for a description of these bits.
-X509_VERIFY_PARAM_clear_flags() clears the flags
B<flags> in B<param>.
+X509_VERIFY_PARAM_clear_flags() clears the flags
I<flags> in I<param>.
-X509_VERIFY_PARAM_set_purpose() sets the verification purpose in
B<param>
-to
B<purpose>. This determines the acceptable purpose of the certificate
+X509_VERIFY_PARAM_set_purpose() sets the verification purpose in
I<param>
+to
I<purpose>. This determines the acceptable purpose of the certificate
chain, for example B<X509_PURPOSE_SSL_CLIENT>.
-The purpose requirement is cleared if B<purpose> is X509_PURPOSE_DEFAULT_ANY.
+The purpose requirement is cleared if I<purpose> is B<X509_PURPOSE_DEFAULT_ANY>.
-X509_VERIFY_PARAM_get_purpose() returns the purpose in
B<param>.
+X509_VERIFY_PARAM_get_purpose() returns the purpose in
I<param>.
-X509_VERIFY_PARAM_set_trust() sets the trust setting in
B<param> to
-B<trust>.
+X509_VERIFY_PARAM_set_trust() sets the trust setting in
I<param> to
+I<trust>.
-X509_VERIFY_PARAM_set_time() sets the verification time in
B<param> to
-B<t>. Normally the current time is used.
+X509_VERIFY_PARAM_set_time() sets the verification time in
I<param> to
+I<t>. Normally the current time is used.
-X509_VERIFY_PARAM_add0_policy() adds
B<policy> to the acceptable policy set.
+X509_VERIFY_PARAM_add0_policy() adds
I<policy> 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<policies>. Any existing
-policy set is cleared. The B<policies> parameter can be B<NULL> to clear
+by default) and sets the acceptable policy set to
I<policies>. Any existing
+policy set is cleared. The I<policies> parameter can be NULL to clear
an existing policy set.
-X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>.
+X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to I<depth>.
That is the maximum number of intermediate CA certificates that can appear in a
chain.
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<depth> limit of 0 only allows the end-entity certificate to be signed
-directly by the trust anchor, while with a B<depth> limit of 1 there can be one
+Thus a I<depth> limit of 0 only allows the end-entity certificate to be signed
+directly by the trust anchor, while with a I<depth> 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
The authentication security level determines the acceptable signature and public
key strength when verifying certificate chains.
For a certificate chain to validate, the public keys of all the certificates
interoperable, though it will, for example, reject MD5 signatures or RSA keys
shorter than 1024 bits.
-X509_VERIFY_PARAM_get0_host() returns the B<n>th expected DNS hostname that has
+X509_VERIFY_PARAM_get0_host() returns the I<n>th 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<n> = 0 and increment B<n> as long as no NULL
+To obtain all names start with I<n> = 0 and increment I<n> as long as no NULL
pointer is returned.
-X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to
-B<name> clearing any previously specified hostname. If
-B<name> is NULL, or empty the list of hostnames is cleared, and
-name checks are not performed on the peer certificate. If B<name>
-is NUL-terminated, B<namelen> may be zero, otherwise B<namelen>
-must be set to the length of B<name>.
+X509_VERIFY_PARAM_set1_host() sets in I<param> the expected
+DNS hostname to I<name>, clearing any previously specified hostname.
+If I<name> is NULL or the empty string, the list of hostnames is cleared
+and hostname checks are not performed on the peer certificate.
+If I<name> is NUL-terminated, I<namelen> may be zero,
+otherwise I<namelen> must be set to the length of I<name>.
When a hostname is specified,
certificate verification automatically invokes L<X509_check_host(3)>
-with flags equal to the B<flags> argument given to
+with flags equal to the I<flags> argument given to
X509_VERIFY_PARAM_set_hostflags() (default zero). Applications
are strongly advised to use this interface in preference to explicitly
calling L<X509_check_host(3)>, hostname checks may be out of scope
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<name> as an additional reference
+X509_VERIFY_PARAM_add1_host() adds I<name> 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<name> is NULL or empty. When
+are retained, no change is made if I<name> is NULL or the empty string. When
multiple names are configured, the peer is considered verified when
any name matches.
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<param> argument is freed. Applications must not free
+associated
I<param> 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<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise
-B<emaillen> must be set to the length of B<email>. When an email address
+I<email>. If I<email> is NUL-terminated, I<emaillen> may be zero, otherwise
+I<emaillen> must be set to the length of I<email>. When an email address
is specified, certificate verification automatically invokes
L<X509_check_email(3)>.
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<ip>.
-The B<ip> argument is in binary format, in network byte-order and
-B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP
+X509_VERIFY_PARAM_set1_ip() sets the expected IP address to I<ip>.
+The I<ip> argument is in binary format, in network byte-order and
+I<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP
address is specified, certificate verification automatically invokes
L<X509_check_ip(3)>.
X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to
-B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string:
+I<ipasc>. The I<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.
verification callback relating to policy checking.
B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and
-B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any
-policy> and B<inhibit policy mapping> flags respectively as defined in
-B<RFC3280>. Policy checking is automatically enabled if any of these flags
+B<X509_V_FLAG_INHIBIT_MAP> set the C<require explicit policy>, C<inhibit any
+policy> and C<inhibit policy mapping> flags respectively as defined in
+RFC 5280. Policy checking is automatically enabled if any of these flags
are set.
If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful
of such a certificate is that disabled or unsupported message digests used for
the signature are not treated as fatal errors.
-When B<X509_V_FLAG_TRUSTED_FIRST> is set, which is always the case since
+When B<X509_V_FLAG_TRUSTED_FIRST> is set, which is the default since
OpenSSL 1.1.0, construction of the certificate chain
in L<X509_verify_cert(3)> searches the trust store for issuer certificates
before searching the provided untrusted certificates.
This is especially important when some certificates in the trust store have
explicit trust settings (see "TRUST SETTINGS" in L<openssl-x509(1)>).
-The B<X509_V_FLAG_NO_ALT_CHAINS> flag could have been used before OpenSSL 1.1.0
-to suppress checking for alternative chains.
-By default, unless B<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.
-As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option
-has no effect.
+The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative chains.
The B<X509_V_FLAG_PARTIAL_CHAIN> 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 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<X509_V_FLAG_PARTIAL_CHAIN> set, chain
+With B<X509_V_FLAG_PARTIAL_CHAIN> 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.
=head1 EXAMPLES
Enable CRL checking when performing certificate verification during SSL
-connections associated with an B<SSL_CTX> structure B<ctx>:
+connections associated with an B<SSL_CTX> structure I<ctx>:
X509_VERIFY_PARAM *param;
=head1 SEE ALSO
+L<SSL_CTX_set_security_level(3)>,
L<X509_verify_cert(3)>,
L<X509_check_host(3)>,
L<X509_check_email(3)>,
=head1 HISTORY
+Until OpenSSL 1.1.0, by default (unless B<X509_V_FLAG_TRUSTED_FIRST> was set), when building a
+certificate chain, if the first certificate chain found was not trusted,
+OpenSSL would 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.
+Since OpenSSL 1.1.0 version, the B<X509_V_FLAG_TRUSTED_FIRST> is set by default.
+
The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0.
The flag B<X509_V_FLAG_CB_ISSUER_CHECK> was deprecated in OpenSSL 1.1.0
and has no effect.
projects / thirdparty / openssl.git / commitdiff
