mirror of https://github.com/openssl/openssl.git
X509_VERIFY_PARAM_set_flags.pod: remove heavily outdated texts on X509_V_FLAG_NO_ALT_CHAINS; other small fixes
This commit is contained in:
Dr. David von Oheimb
Dr. David von Oheimb
parent
f387b0fedd
commit
405f49af6e
|
|
@ -76,54 +76,54 @@ X509_VERIFY_PARAM_set1_ip_asc
|
|||
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>
|
||||
X509_VERIFY_PARAM_set_purpose() sets the verification purpose in I<param>
|
||||
to B<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.
|
||||
|
||||
X509_VERIFY_PARAM_get_purpose() returns the purpose in B<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
|
||||
B<auth_level>.
|
||||
I<auth_level>.
|
||||
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
|
||||
|
|
@ -139,21 +139,21 @@ 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 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
|
||||
|
|
@ -176,10 +176,10 @@ flag takes precedence over the B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> 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<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.
|
||||
|
||||
|
|
@ -190,28 +190,28 @@ 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<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.
|
||||
|
||||
|
|
@ -275,9 +275,9 @@ no policy checking is performed. Additional information is sent to the
|
|||
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
|
||||
|
|
@ -311,6 +311,8 @@ 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<openssl-x509(1)>).
|
||||
|
||||
=begin comment
|
||||
|
||||
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
|
||||
|
|
@ -321,12 +323,14 @@ found that is trusted.
|
|||
As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option
|
||||
has no effect.
|
||||
|
||||
=end comment
|
||||
|
||||
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.
|
||||
|
|
@ -386,7 +390,7 @@ CRLs from the CRL distribution points extension.
|
|||
=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;
|
||||
|
||||
|
|
@ -397,6 +401,7 @@ connections associated with an B<SSL_CTX> structure B<ctx>:
|
|||
|
||||
=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)>,
|
||||
|
|
|
|||
Loading…
Reference in New Issue