mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-31 20:10:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve the documentation of cert path building and validation

Browse Source 
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13735)
This commit is contained in:
Dr. David von Oheimb 2020-12-23 23:29:04 +01:00 committed by Dr. David von Oheimb
parent 2576b9c31c
commit f9ac6f6956
12 changed files with 372 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
crypto/x509/v3_purp.c
View File

@ -894,10 +894,10 @@ static int no_check_purpose(const X509_PURPOSE *xp, const X509 *x,
* This can be used to prune a set of possible issuer certificates which
* have been looked up using some simple method such as by subject name.
* These are:
* 1. Check issuer_name(subject) == subject_name(issuer)
* 2. If akid(subject) exists, check that it matches issuer
* 3. Check that issuer public key algorithm matches subject signature algorithm
* 4. Check that any key_usage(issuer) allows certificate signing
* 1. issuer_name(subject) == subject_name(issuer)
* 2. If akid(subject) exists, it matches the respective issuer fields.
* 3. subject signature algorithm == issuer public key algorithm
* 4. If key_usage(issuer) exists, it allows for signing subject.
* Note that this does not include actually checking the signature.
* Returns 0 for OK, or positive for reason for mismatch
* where reason codes match those for X509_verify_cert().

3
crypto/x509/x509_vfy.c
View File

@ -3007,7 +3007,8 @@ static int build_chain(X509_STORE_CTX *ctx)
#define S_DOTRUSTED (1 << 1) /* Search trusted store */
#define S_DOALTERNATE (1 << 2) /* Retry with pruned alternate chain */
/*
* Set up search policy, untrusted if possible, trusted-first if enabled.
* Set up search policy, untrusted if possible, trusted-first if enabled,
* which is the default.
* If we're doing DANE and not doing PKIX-TA/PKIX-EE, we never look in the
* trust_store, otherwise we might look there first. If not trusted-first,
* and alternate chains are not disabled, try building an alternate chain

344
doc/man1/openssl-verification-options.pod
View File

@ -13,51 +13,156 @@ I<command>
=head1 DESCRIPTION
Many OpenSSL commands and various other uses of the crypto library function
L<X509_verify_cert(3)> verify X.509 certificates. The details of how each
command handles errors are documented on the specific command page.
There are many situations where X.509 certificates are verified
within the OpenSSL libraries and in various OpenSSL commands.
Certificate verification is a complicated process, consisting of
a number of separate steps that are detailed in the following paragraphs.
Certificate verification is implemented by L<X509_verify_cert(3)>.
It is a complicated process consisting of a number of steps
and depending on numerous options.
The most important of them are detailed in the following sections.
In a nutshell, a valid chain of certifciates needs to be built up and verified
starting from the I<target certificate> that is to be verified
and ending in a certificate that due to some policy is trusted.
Verification is done relative to the given I<purpose>, which is the intended use
of the target certificate, such as SSL server, or by default for any purpose.
The details of how each OpenSSL command handles errors
are documented on the specific command page.
DANE support is documented in L<openssl-s_client(1)>,
L<SSL_CTX_dane_enable(3)>, L<SSL_set1_host(3)>,
L<X509_VERIFY_PARAM_set_flags(3)>, and L<X509_check_host(3)>.
=head2 Trust Anchors
In general, according to RFC 4158 and RFC 5280, a I<trust anchor> is
any public key and related subject distinguished name (DN) that
for some reason is considered trusted
and thus is acceptable as the root of a chain of certificates.
In practice, trust anchors are given in the form of certificates,
where their essential fields are the public key and the subject DN.
In addition to the requirements in RFC 5280,
OpenSSL checks the validity period of such certificates
and makes use of some further fields.
In particular, the subject key identifier extension, if present,
is used for matching trust anchors during chain building.
In the most simple and common case, trust anchors are by default
all self-signed "root" CA certificates that are placed in the I<trust store>,
which is a collection of certificates that are trusted for certain uses.
This is akin to what is used in the trust stores of Mozilla Firefox,
or Apple's and Microsoft's certificate stores, ...
From the OpenSSL perspective, a trust anchor is a certificate
that should be augmented with an explicit designation for which
uses of a target certificate the certificate may serve as a trust anchor.
In PEM encoding, this is indicated by the C<TRUSTED CERTIFICATE> string.
Such a designation provides a set of positive trust attributes
explicitly stating trust for the listed purposes
and/or a set of negative trust attributes
explicitly rejecting the use for the listed purposes.
The purposes are encoded using the values defined for the extended key usages
(EKUs) that may be given in X.509 extensions of end-entity certificates.
See also the L</Extended Key Usage> section below.
The currently recognized uses are
B<clientAuth> (SSL client use), B<serverAuth> (SSL server use),
B<emailProtection> (S/MIME email use), B<codeSigning> (object signer use),
B<OCSPSigning> (OCSP responder use), B<OCSP> (OCSP request use),
B<timeStamping> (TSA server use), and B<anyExtendedKeyUsage>.
As of OpenSSL 1.1.0, the last of these blocks all uses when rejected or
enables all uses when trusted.
A certificate, which may be CA certificate or an end-entity certificate,
is considered a trust anchor for the given use
if and only if all the following conditions hold:
=over 4
=item *
It is an an element of the trust store.
=item *
It does not have a negative trust attribute rejecting the given use.
=item *
It has a positive trust attribute accepting the given use
or (by default) one of the following compatibilty conditions apply:
It is self-signed or the B<-partial_chain> option is given
(which corresponds to the B<X509_V_FLAG_PARTIAL_CHAIN> flag being set).
=back
=head2 Certification Path Building
First, a certificate chain is built up starting from the target certificate
and typically ending in a self-signed "root" CA certificate.
It is an error if the whole chain cannot be built up
unless the B<-partial_chain> option is given.
The chain is built up iteratively, looking up in turn
the certificate of the signer ("issuer") of the current certificate.
If a certificate is found that appears to be its own issuer
it is assumed to be the self-signed root, which must be trusted.
and ending in a trust anchor.
The process of looking up the issuer's certificate itself involves a number
of steps.
All available certificates with a subject name that matches the issuer
name of the current certificate are subject to further tests.
The relevant authority key identifier components of the current certificate
(if present) must match the subject key identifier (if present)
and issuer and serial number of the candidate issuer certificate.
The chain is built up iteratively, looking up in turn
a certificate with suitable key usage that
matches as an issuer of the current "subject" certificate as described below.
If there is such a certificate, the first one found that is currently valid
is taken, otherwise the one that expired most recently of all such certificates.
For efficiency, no backtracking is performed, thus
any further candidate issuer certificates that would match equally are ignored.
When a self-signed certificate has been added, chain construction stops.
In this case it must fully match a trust anchor, otherwise chain building fails.
A candidate issuer certificate matches a subject certificate
if all of the following conditions hold:
=over 4
=item *
Its subject name matches the issuer name of the subject certificate.
=item *
If the subject certificate has an authority key identifier extension,
each of its sub-fields equals the corresponding subject key identifier, serial
number, and issuer field of the candidate issuer certificate,
as far as the respective fields are present in both certificates.
item *
The certificate signature algorithm used to sign the subject certificate
is supported and
equals the public key algorithm of the candidate issuer certificate.
=back
The lookup first searches for issuer certificates in the trust store.
If it does not find a match there it consults
the list of untrusted "intermediate" CA certificates (if provided).
The last certificate (which typically is of a root CA) is always looked up
in the trusted certificate list; an exact match must be found there.
the list of untrusted ("intermediate" CA) certificates, if provided.
=head2 Certification Path Validation
When the certificate chain building process was successful
the chain components and their links are checked thoroughly.
The first step is to check that each certificate is well-formed.
Part of these checks are enabled only if the B<-x509_strict> option is given.
The second step is to check the extensions of every untrusted certificate
for consistency with the supplied purpose.
If the B<-purpose> option is not included then no checks are done.
The target or "leaf" certificate must have extensions compatible with the
supplied purpose and all other certificates must also be valid CA certificates.
for consistency with the given purpose.
If the B<-purpose> option is not included then no such checks are done.
The target certificate must not have an EKU extension that is incompatible with
the given purpose, and all other certificates must be valid CA certificates.
The precise extensions required are described in more detail in
L<openssl-x509(1)/CERTIFICATE EXTENSIONS>.
The third step is to check the trust settings on the last certficate,
typically of a root CA.
It should be trusted for the supplied purpose.
For compatibility with previous versions of OpenSSL,
a certificate with no trust settings is considered to be valid for all purposes.
The third step is to check the trust settings on the last certificate
(which typically is a self-signed root CA certificate).
It must be trusted for the given use.
For compatibility with previous versions of OpenSSL, a self-signed certificate
with no trust attributes is considered to be valid for all uses.
The fourth, and final, step is to check the validity of the certificate chain.
For each element in the chain, including the root CA certificate,
@ -78,23 +183,25 @@ valid. If any operation fails then the certificate is not valid.
=head2 Trusted Certificate Options
The following options specify how to select the trusted root certificates,
also known as trust anchors.
A collection of trusted roots is called a I<trust store>.
The following options specify how to supply the certificates
that can be used as trust anchors for certain uses.
As mentioned, a collection of such certificates is called a I<trust store>.
Note that OpenSSL does not provide a default set of trust anchors. Many
Linux distributions include a system default and configure OpenSSL to point
to that. Mozilla maintains an influential trust store that can be found at
L<https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/>.
The certificates to trust can be specified using following options.
The certificates to add to the trust store
can be specified using following options.
=over 4
=item B<-CAfile> I<file>
Load the specified file which contains one or more PEM-format certificates
of CA's that are trusted.
Load the specified file which contains a certificate
or several of them in case the input is in PEM or PKCS#12 format.
PEM-encoded certificates may also have trust attributes set.
=item B<-no-CAfile>
@ -102,8 +209,9 @@ Do not load the default file of trusted certificates.
=item B<-CApath> I<dir>
Use the specified directory as a list of trust certificates. That is,
files should be named with the hash of the X.509 SubjectName of each
Use the specified directory as a collection of trusted certificates,
i.e., a trust store.
Files should be named with the hash value of the X.509 SubjectName of each
certificate. This is so that the library can extract the IssuerName,
hash it, and directly lookup the file to get the issuer certificate.
See L<openssl-rehash(1)> for information on creating this type of directory.
@ -114,8 +222,8 @@ Do not use the default directory of trusted certificates.
=item B<-CAstore> I<uri>
Use I<uri> as a store of trusted CA certificates. The URI may
indicate a single certificate, as well as a collection of them.
Use I<uri> as a store of CA certificates.
The URI may indicate a single certificate, as well as a collection of them.
With URIs in the C<file:> scheme, this acts as B<-CAfile> or
B<-CApath>, depending on if the URI indicates a single file or
directory.
@ -127,7 +235,7 @@ chain (for example with L<openssl-s_time(1)>).
=item B<-no-CAstore>
Do not use the default store.
Do not use the default store of trusted CA certificates.
=back
@ -267,9 +375,10 @@ keys shorter than 1024 bits.
=item B<-partial_chain>
Allow verification to succeed even if a I<complete> chain cannot be built to a
self-signed trust-anchor, provided it is possible to construct a chain to a
trusted certificate that might not be self-signed.
Allow verification to succeed if an incomplete chain can be built.
That is, a chain ending in a certificate that normally would not be trusted
(because it has no matching positive trust attributes and is not self-signed)
but is an element of the trust store.
This certificate may be self-issued or belong to an intermediate CA.
=item B<-check_ss_sig>
@ -299,20 +408,20 @@ effect.
=item B<-trusted> I<file>
Parse I<file> as a set of one or more certificates in PEM format.
All certificates must be self-signed, unless the
B<-partial_chain> option is specified.
Parse I<file> as a set of one or more certificates.
Each of them qualifies as trusted if has a suitable positive trust attribute
or it is self-signed or the B<-partial_chain> option is specified.
This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options
and it cannot be used with the B<-CAfile>, B<-CApath> or B<-CAstore> options, so
only certificates in the file are trust anchors.
only certificates specified using the B<-trusted> option are trust anchors.
This option may be used multiple times.
=item B<-untrusted> I<file>
Parse I<file> as a set of one or more certificates in PEM format.
All certificates are untrusted certificates (typically of intermedate CAs)
that may be used to
construct a certificate chain from the subject certificate to a trust anchor.
Parse I<file> as a set of one or more certificates.
All certificates (typically of intermediate CAs) are considered untrusted
and may be used to
construct a certificate chain from the target certificate to a trust anchor.
This option may be used multiple times.
=item B<-policy> I<arg>
@ -346,7 +455,8 @@ Set policy variable inhibit-policy-mapping (see RFC5280).
The intended use for the certificate. If this option is not specified, this
command will not consider certificate purpose during chain verification.
Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
B<smimesign>, B<smimeencrypt>.
B<smimesign>, B<smimeencrypt>, B<crlsign>, B<ocsphelper>, B<timestampsign>,
and <any>.
=item B<-verify_depth> I<num>
@ -376,7 +486,8 @@ Use default verification policies like trust model and required certificate
policies identified by I<name>.
The trust model determines which auxiliary trust or reject OIDs are applicable
to verifying the given certificate chain.
See the B<-addtrust> and B<-addreject> options for L<openssl-x509(1)>.
They can be given using the B<-addtrust> and B<-addreject> options
for L<openssl-x509(1)>.
Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
B<ssl_client>, B<ssl_server>.
These mimics the combinations of purpose and trust settings used in SSL, CMS
@ -426,6 +537,128 @@ This option has no effect and is retained for backward compatibility only.
=back
=head2 Certificate Extensions
Options like B<-purpose> lead to checking the certificate extensions,
which determine what the target certificate and intermediate CA certificates
can be used for.
=head3 Basic Constraints
The basicConstraints extension CA flag is used to determine whether the
certificate can be used as a CA. If the CA flag is true then it is a CA,
if the CA flag is false then it is not a CA. B<All> CAs should have the
CA flag set to true.
If the basicConstraints extension is absent,
which includes the case that it is an X.509v1 certificate,
then the certificate is considered to be a "possible CA" and
other extensions are checked according to the intended use of the certificate.
The treatment of certificates without basicConstraints as a CA
is presently supported, but this could change in the future.
=head3 Key Usage
If the keyUsage extension is present then additional restraints are
made on the uses of the certificate. A CA certificate B<must> have the
keyCertSign bit set if the keyUsage extension is present.
=head3 Extended Key Usage
The extKeyUsage (EKU) extension places additional restrictions on the
certificate uses. If this extension is present (whether critical or not)
the key can only be used for the purposes specified.
A complete description of each check is given below. The comments about
basicConstraints and keyUsage and X.509v1 certificates above apply to B<all>
CA certificates.
=over 4
=item B<SSL Client>
The extended key usage extension must be absent or include the "web client
authentication" OID. The keyUsage extension must be absent or it must have the
digitalSignature bit set. The Netscape certificate type must be absent
or it must have the SSL client bit set.
=item B<SSL Client CA>
The extended key usage extension must be absent or include the "web client
authentication" OID.
The Netscape certificate type must be absent or it must have the SSL CA bit set.
This is used as a work around if the basicConstraints extension is absent.
=item B<SSL Server>
The extended key usage extension must be absent or include the "web server
authentication" and/or one of the SGC OIDs. The keyUsage extension must be
absent or it
must have the digitalSignature, the keyEncipherment set or both bits set.
The Netscape certificate type must be absent or have the SSL server bit set.
=item B<SSL Server CA>
The extended key usage extension must be absent or include the "web server
authentication" and/or one of the SGC OIDs. The Netscape certificate type must
be absent or the SSL CA bit must be set.
This is used as a work around if the basicConstraints extension is absent.
=item B<Netscape SSL Server>
For Netscape SSL clients to connect to an SSL server it must have the
keyEncipherment bit set if the keyUsage extension is present. This isn't
always valid because some cipher suites use the key for digital signing.
Otherwise it is the same as a normal SSL server.
=item B<Common S/MIME Client Tests>
The extended key usage extension must be absent or include the "email
protection" OID. The Netscape certificate type must be absent or should have the
S/MIME bit set. If the S/MIME bit is not set in the Netscape certificate type
then the SSL client bit is tolerated as an alternative but a warning is shown.
This is because some Verisign certificates don't set the S/MIME bit.
=item B<S/MIME Signing>
In addition to the common S/MIME client tests the digitalSignature bit or
the nonRepudiation bit must be set if the keyUsage extension is present.
=item B<S/MIME Encryption>
In addition to the common S/MIME tests the keyEncipherment bit must be set
if the keyUsage extension is present.
=item B<S/MIME CA>
The extended key usage extension must be absent or include the "email
protection" OID. The Netscape certificate type must be absent or must have the
S/MIME CA bit set.
This is used as a work around if the basicConstraints extension is absent.
=item B<CRL Signing>
The keyUsage extension must be absent or it must have the CRL signing bit
set.
=item B<CRL Signing CA>
The normal CA tests apply. Except in this case the basicConstraints extension
must be present.
=back
=head1 BUGS
The issuer checks still suffer from limitations in the underlying X509_LOOKUP
API. One consequence of this is that trusted certificates with matching
subject name must appear in a file (as specified by the B<-CAfile> option),
a directory (as specified by B<-CApath>),
or a store (as specified by B<-CAstore>).
If there are multiple such matches, possibly in multiple locations,
only the first one (in the mentioned order of locations) is recognised.
=head1 SEE ALSO
L<X509_verify_cert(3)>,
@ -438,7 +671,6 @@ L<openssl-smime(1)>,
L<openssl-cmp(1)>,
L<openssl-cms(1)>
=head1 HISTORY
The checks enabled by B<-x509_strict> have been extended in OpenSSL 3.0.

43
doc/man1/openssl-verify.pod.in
View File

@ -9,12 +9,12 @@ openssl-verify - certificate verification command
B<openssl> B<verify>
[B<-help>]
[B<-CRLfile> I<file>]
[B<-CRLfile> I<filename>|I<uri>]
[B<-crl_download>]
[B<-show_chain>]
[B<-verbose>]
[B<-trusted> I<file>]
[B<-untrusted> I<file>]
[B<-trusted> I<filename>|I<uri>]
[B<-untrusted> I<filename>|I<uri>]
[B<-vfyopt> I<nm>:I<v>]
{- $OpenSSL::safe::opt_name_synopsis -}
{- $OpenSSL::safe::opt_trust_synopsis -}
@ -36,11 +36,11 @@ problems, this program attempts to display all of them.
Print out a usage message.
=item B<-CRLfile> I<file>
=item B<-CRLfile> I<filename>|I<uri>
The file or URI should contain one or more CRLs in PEM or DER format.
This option can be specified more than once to include CRLs from multiple
I<file>s.
sources.
=item B<-crl_download>
@ -56,19 +56,19 @@ flagged as "untrusted".
Print extra information about the operations being performed.
=item B<-trusted> I<file>
=item B<-trusted> I<filename>|I<uri>
A file or URI of (more or less) trusted certificates.
See L<openssl-verification-options(1)> for more information on trust settings.
A file or URI of trusted certificates in PEM, DER, or PKCS#12 format.
This option can be specified more than once to load certificates from multiple
I<file>s.
sources.
=item B<-untrusted> I<file>
=item B<-untrusted> I<filename>|I<uri>
A file or URI of untrusted certificates in PEM, DER, or PKCS#12 format
to use for chain building.
A file or URI of untrusted certificates to use for chain building.
This option can be specified more than once to load certificates from multiple
I<file>s.
sources.
=item B<-vfyopt> I<nm>:I<v>
@ -126,23 +126,6 @@ F<< <openssl/x509_vfy.h> >>.
This command ignores many errors, in order to allow all the problems with a
certificate chain to be determined.
=head1 BUGS
Although the issuer checks are a considerable improvement over the old
technique they still suffer from limitations in the underlying X509_LOOKUP
API. One consequence of this is that trusted certificates with matching
subject name must either appear in a file (as specified by the B<-CAfile>
option), a directory (as specified by B<-CApath>), or a store (as specified
by B<-CAstore>). If they occur in more than one location then only the
certificates in the file will be recognised.
Previous versions of OpenSSL assume certificates with matching subject
name are identical and mishandled them.
Previous versions of this documentation swapped the meaning of the
B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
=head1 SEE ALSO
L<openssl-verification-options(1)>,

134
doc/man1/openssl-x509.pod.in
View File

@ -305,9 +305,9 @@ Prints the OCSP responder address(es) if any.
=item B<-purpose>
This option performs tests on the certificate extensions and prints
the results. For a more complete description see the
L</CERTIFICATE EXTENSIONS> section.
This option performs tests on the certificate extensions and outputs
the results. For a more complete description see
L<openssl-verification-options(1)/Certificate Extensions>.
=item B<-pubkey>
@ -518,7 +518,7 @@ Trust settings currently are only used with a root CA.
They allow a finer control over the purposes the root CA can be used for.
For example, a CA may be trusted for SSL client but not SSL server use.
See the description in L<openssl-verify(1)> for more information
See L<openssl-verification-options(1)> for more information
on the meaning of trust settings.
Future versions of OpenSSL will recognize trust settings on any
@ -545,13 +545,10 @@ Clears all the permitted or trusted uses of the certificate.
=item B<-addtrust> I<arg>
Adds a trusted certificate use.
Any object name can be used here but currently only B<clientAuth> (SSL client
use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email)
and B<anyExtendedKeyUsage> are used.
As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
enables all purposes when trusted.
Other OpenSSL applications may define additional uses.
Adds an allowed trust anchor purpose.
Any object name can be used here but currently only those
listed in L<openssl-verification-options(1)/Trust Anchors> are supported.
Other OpenSSL applications may define additional purposes.
=item B<-clrreject>
@ -559,7 +556,7 @@ Clears all the prohibited or rejected uses of the certificate.
=item B<-addreject> I<arg>
Adds a prohibited use.
Adds a prohibited trust anchor purpose.
It accepts the same values as the B<-addtrust> option.
=back
@ -732,119 +729,6 @@ The B<-email> option searches the subject name and the subject alternative
name extension. Only unique email addresses will be printed out: it will
not print the same address more than once.
=head1 CERTIFICATE EXTENSIONS
The B<-purpose> option checks the certificate extensions and determines
what the certificate can be used for. The actual checks done are rather
complex and include various hacks and workarounds to handle broken
certificates and software.
The same code is used when verifying untrusted certificates in chains
so this section is useful if a chain is rejected by the verify code.
The basicConstraints extension CA flag is used to determine whether the
certificate can be used as a CA. If the CA flag is true then it is a CA,
if the CA flag is false then it is not a CA. B<All> CAs should have the
CA flag set to true.
If the basicConstraints extension is absent then the certificate is
considered to be a "possible CA" other extensions are checked according
to the intended use of the certificate. A warning is given in this case
because the certificate should really not be regarded as a CA: however
it is allowed to be a CA to work around some broken software.
If the certificate is a V1 certificate (and thus has no extensions) and
it is self-signed it is also assumed to be a CA but a warning is again
given: this is to work around the problem of Verisign roots which are V1
self-signed certificates.
If the keyUsage extension is present then additional restraints are
made on the uses of the certificate. A CA certificate B<must> have the
keyCertSign bit set if the keyUsage extension is present.
The extended key usage extension places additional restrictions on the
certificate uses. If this extension is present (whether critical or not)
the key can only be used for the purposes specified.
A complete description of each test is given below. The comments about
basicConstraints and keyUsage and V1 certificates above apply to B<all>
CA certificates.
=over 4
=item B<SSL Client>
The extended key usage extension must be absent or include the "web client
authentication" OID. keyUsage must be absent or it must have the
digitalSignature bit set. Netscape certificate type must be absent or it must
have the SSL client bit set.
=item B<SSL Client CA>
The extended key usage extension must be absent or include the "web client
authentication" OID. Netscape certificate type must be absent or it must have
the SSL CA bit set: this is used as a work around if the basicConstraints
extension is absent.
=item B<SSL Server>
The extended key usage extension must be absent or include the "web server
authentication" and/or one of the SGC OIDs. keyUsage must be absent or it
must have the digitalSignature, the keyEncipherment set or both bits set.
Netscape certificate type must be absent or have the SSL server bit set.
=item B<SSL Server CA>
The extended key usage extension must be absent or include the "web server
authentication" and/or one of the SGC OIDs. Netscape certificate type must
be absent or the SSL CA bit must be set: this is used as a work around if the
basicConstraints extension is absent.
=item B<Netscape SSL Server>
For Netscape SSL clients to connect to an SSL server it must have the
keyEncipherment bit set if the keyUsage extension is present. This isn't
always valid because some cipher suites use the key for digital signing.
Otherwise it is the same as a normal SSL server.
=item B<Common S/MIME Client Tests>
The extended key usage extension must be absent or include the "email
protection" OID. Netscape certificate type must be absent or should have the
S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type
then the SSL client bit is tolerated as an alternative but a warning is shown:
this is because some Verisign certificates don't set the S/MIME bit.
=item B<S/MIME Signing>
In addition to the common S/MIME client tests the digitalSignature bit or
the nonRepudiation bit must be set if the keyUsage extension is present.
=item B<S/MIME Encryption>
In addition to the common S/MIME tests the keyEncipherment bit must be set
if the keyUsage extension is present.
=item B<S/MIME CA>
The extended key usage extension must be absent or include the "email
protection" OID. Netscape certificate type must be absent or must have the
S/MIME CA bit set: this is used as a work around if the basicConstraints
extension is absent.
=item B<CRL Signing>
The keyUsage extension must be absent or it must have the CRL signing bit
set.
=item B<CRL Signing CA>
The normal CA tests apply. Except in this case the basicConstraints extension
must be present.
=back
=head1 BUGS
It is possible to produce invalid certificates or requests by specifying the

7
doc/man3/SSL_CTX_add1_chain_cert.pod
View File

@ -52,8 +52,9 @@ SSL_CTX_clear_chain_certs() clears any existing chain associated with the
current certificate of B<ctx>. (This is implemented by calling
SSL_CTX_set0_chain() with B<sk> set to B<NULL>).
SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> normally
this uses the chain store or the verify store if the chain store is not set.
SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx>.
Normally this uses the chain store
or the verify store if the chain store is not set.
If the function is successful the built chain will replace any existing chain.
The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use
existing chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT>
@ -63,6 +64,8 @@ sanity checking and rearranging them if necessary), the flag
B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification:
if flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors
are cleared from the error queue.
Details of the chain building process are described in
L<openssl-verification-options(1)/Certification Path Building>.
Each of these functions operates on the I<current> end entity
(i.e. server or client) certificate. This is the last certificate loaded or

15
doc/man3/SSL_CTX_load_verify_locations.pod
View File

@ -33,6 +33,9 @@ locations for B<ctx>, at which CA certificates for verification purposes
are located. The certificates available via B<CAfile>, B<CApath> and
B<CAstore> are trusted.
Details of the certificate verification and chain checking process are
described in L<openssl-verification-options(1)/Certification Path Validation>.
SSL_CTX_set_default_verify_paths() specifies that the default locations from
which CA certificates are loaded should be used. There is one default directory,
one default file and one default store.
@ -85,14 +88,10 @@ The certificates in B<CApath> are only looked up when required, e.g. when
building the certificate chain or when actually performing the verification
of a peer certificate.
When looking up CA certificates, the OpenSSL library will first search the
certificates in B<CAfile>, then those in B<CApath>. Certificate matching
is done based on the subject name, the key identifier (if present), and the
serial number as taken from the certificate to be verified. If these data
do not match, the next certificate will be tried. If a first certificate
matching the parameters is found, the verification process will be performed;
no other certificates for the same parameters will be searched in case of
failure.
When looking up CA certificates for chain building, the OpenSSL library
will search for suitable certificates first in B<CAfile>, then in B<CApath>.
Details of the chain building process are described in
L<openssl-verification-options(1)/Certification Path Building>.
If B<CAstore> is not NULL, it's a URI for to a store, which may
represent a single container or a whole catalogue of containers.

3
doc/man3/SSL_CTX_set1_verify_cert_store.pod
View File

@ -52,6 +52,9 @@ the server's certificate chain and a SSL/TLS server will use it to verify
any client certificate chain.
The chain store is used to build the certificate chain.
Details of the chain building and checking process are described in
L<openssl-verification-options(1)/Certification Path Building> and
L<openssl-verification-options(1)/Certification Path Validation>.
If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set or a certificate chain is
configured already (for example using the functions such as

6
doc/man3/X509_STORE_CTX_get_error.pod
View File

@ -460,6 +460,12 @@ If an unrecognised error code is passed to X509_verify_cert_error_string() the
numerical value of the unknown code is returned in a static buffer. This is not
thread safe but will never happen unless an invalid code is passed.
=head1 BUGS
Previous versions of this documentation swapped the meaning of the
B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
=head1 SEE ALSO
L<X509_verify_cert(3)>, L<X509_STORE_CTX_verify(3)>,

47
doc/man3/X509_STORE_CTX_new.pod
View File

@ -5,10 +5,10 @@
X509_STORE_CTX_new_ex, X509_STORE_CTX_new, X509_STORE_CTX_cleanup,
X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack,
X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls,
X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain,
X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param,
X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted,
X509_STORE_CTX_get_num_untrusted,
X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain,
X509_STORE_CTX_set_default,
X509_STORE_CTX_set_verify,
X509_STORE_CTX_verify_fn
@ -29,19 +29,19 @@ X509_STORE_CTX_verify_fn
void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *target);
STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
int X509_STORE_CTX_get_num_untrusted(const X509_STORE_CTX *ctx);
STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx);
void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *);
void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify);
@ -66,7 +66,6 @@ X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx>
is no longer valid.
If I<ctx> is NULL nothing is done.
X509_STORE_CTX_init() sets up I<ctx> for a subsequent verification operation.
It must be called before each call to L<X509_verify_cert(3)> or
L<X509_STORE_CTX_verify(3)>, i.e., a context is only good for one verification.
If you want to verify a further certificate or chain with the same I<ctx>
@ -87,17 +86,18 @@ this can be also set indirectly using X509_STORE_CTX_set0_untrusted().
X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of
I<ctx> to I<sk>. This is an alternative way of specifying trusted certificates
instead of using an B<X509_STORE> where its complexity is not needed.
instead of using an B<X509_STORE> where its complexity is not needed
or to make sure that only the given set I<sk> of certificates are trusted.
X509_STORE_CTX_set_cert() sets the target certificate to be verified in I<ctx>
to I<target>.
X509_STORE_CTX_set0_verified_chain() sets the validated chain used
by I<ctx> to be I<chain>.
Ownership of the chain is transferred to I<ctx> and should not be
free'd by the caller.
X509_STORE_CTX_set0_verified_chain() sets the validated chain to I<chain>.
Ownership of the chain is transferred to I<ctx>,
and so it should not be free'd by the caller.
X509_STORE_CTX_get0_chain() returns the internal pointer used by the
I<ctx> that contains the validated chain.
I<ctx> that contains the constructed (output) chain.
X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate
verification to I<sk>. These CRLs will only be used if CRL verification is
@ -108,6 +108,9 @@ for example in a PKCS#7 structure.
X509_STORE_CTX_get0_param() retrieves an internal pointer
to the verification parameters associated with I<ctx>.
X509_STORE_CTX_set0_param() sets the internal verification parameter pointer
to I<param>. After this call B<param> should not be used.
X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the
stack of untrusted certificates associated with I<ctx>.
@ -116,17 +119,27 @@ of untrusted certificates associated with I<ctx> to I<sk>.
X509_STORE_CTX_verify() will take the first element, if any,
as its default target if the target certificate is not set explicitly.
X509_STORE_CTX_set0_param() sets the internal verification parameter pointer
to I<param>. After this call B<param> should not be used.
X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
that were used in building the chain.
This is can be used after calling L<X509_verify_cert(3)> and similar functions.
With L<X509_STORE_CTX_verify(3)>, this does not count the first chain element.
X509_STORE_CTX_get0_chain() returns the internal pointer used by the
I<ctx> that contains the validated chain.
Details of the chain building and checking process are described in
L<openssl-verification-options(1)/Certification Path Building> and
L<openssl-verification-options(1)/Certification Path Validation>.
X509_STORE_CTX_set0_verified_chain() sets the validated chain used
by I<ctx> to be I<chain>.
Ownership of the chain is transferred to I<ctx>,
and so it should not be free'd by the caller.
X509_STORE_CTX_set_default() looks up and sets the default verification
method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to
find an appropriate set of parameters from I<name>.
X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates
that were used in building the chain following a call to L<X509_verify_cert(3)>.
With L<X509_STORE_CTX_verify(3)>, this does not count the first chain element.
X509_STORE_CTX_set_verify() provides the capability for overriding the default
verify function. This function is responsible for verifying chain signatures and
expiration times.

4
doc/man3/X509_STORE_add_cert.pod
View File

@ -53,6 +53,10 @@ It admits multiple lookup mechanisms and efficient scaling performance
with large numbers of certificates, and a great deal of flexibility in
how validation and policy checks are performed.
Details of the chain building and checking process are described in
L<openssl-verification-options(1)/Certification Path Building> and
L<openssl-verification-options(1)/Certification Path Validation>.
L<X509_STORE_new(3)> creates an empty B<X509_STORE> structure, which contains
no information about trusted certificates or where such certificates
are located on disk, and is generally not usable. Normally, trusted

2
doc/man3/X509_VERIFY_PARAM_set_flags.pod
View File

@ -317,7 +317,7 @@ 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 <X509_V_FLAG_PARTIAL_CHAIN> set, chain
With OpenSSL 1.1.0 and later and 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.