=head1 DESCRIPTION
-There are many situations where X.509 certificates are verified
+There are many situations where X.509 public-key certificates are verified
within the OpenSSL libraries and in various OpenSSL commands.
+For checking certificates, the term I<validation> would actually be more
+appropriate,
+but for historical reasons the term I<verification> is often used instead.
+In the sequel, the certificate to be validated is called I<target certificate>.
+Since it usually is an end-entity (EE) certificate, it is also known as
+"leaf" certificate (of a chain or tree), but it may also be a CA certificate.
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 validation process involves several steps and depends on multiple options.
The most important of them are detailed in the following sections.
-In a nutshell, a valid chain of certificates 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.
+In a nutshell, a valid chain of certificates needs to be constructed and checked
+starting from the I<target certificate> that is to be validated and ending in a
+trust anchor, which usually is a certificate that due to some policy is trusted.
Certificate validation can be performed in the context of a I<purpose>, which
is a high-level specification of the intended use of the target certificate,
-such as C<sslserver> for TLS servers, or (by default) for any purpose.
+such as C<sslserver> for (D)TLS servers, or (by default) for any purpose.
+
+All certificates in the chain except the target ceritificate must be CA
+certificates.
+An X.509v3 certificate is considered a CA certificate
+if it has a basicConstraints extension with the `CA` flag set.
+If a pathLenConstraint is included then the chain is checked to satisfy it.
+If a CA certificate has a keyUsage extension
+then the latter must include the keyCertSign bit, and for proxy certificates
+used for issuing a certificate it must include also the digitalSignature bit.
The details of how each OpenSSL command handles errors
are documented on the specific command page.
In general, according to RFC 4158 and RFC 5280, a I<trust anchor> is just
a public key (with algorithm and any parameters) and an associated subject name
-that for some reason is considered trusted
+that in a suitable context is considered trusted for some purpose(s)
and thus is acceptable as the root of a chain of certificates.
-In practice, trust anchors are given in the form of (typically self-signed)
-certificates, where their essential fields are the subjectPublicKeyInfo and the
-subject distinguished name (DN), while the subject key identifier is optional.
-In addition to the requirements given in RFC 5280,
-OpenSSL checks the validity period of such certificates and takes the extended
-key usage (EKU) extension, if present, as a source of usage constraints.
-Any restrictions given by the (regular) key usage extension are ignored.
-
-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.
+In practice, trust anchors are given in the form of certificates.
+Commonly they are self-signed root CA certificates.
+Their most essential fields are the subjectPublicKeyInfo and
+the subject distinguished name (DN), while the subject key identifier extension
+is generally optional but highly recommended to be included in CA certificates
+because they help chain building.
+In addition to the requirements given in RFC 5280 for trust anchor handling,
+OpenSSL performs on trust anchor certificates the same checks as on regular
+CA certificates, in particular those regarding the validity period
+and X.509v3 extensions like basic constraints and key usage.
+Depending on the given validation purpose, in part even the extended key usage
+is checked - for details see the L</Extended Key Usage> section below.
+
+The most crucial input to certificate validation is a I<trust store>,
+which includes a collection of certificates and validation options.
This is akin to what is used in the trust stores of Mozilla Firefox,
or Apple's and Microsoft's certificate stores, ...
+By default all self-signed certificates in the trust store
+are considered to be trust anchors, for all or for specified purposes.
-From the OpenSSL perspective, a trust anchor is a certificate
-that should be augmented with an explicit designation for which
+Independent of any extended key usage (EKU) X.509v3 extension included,
+from the OpenSSL perspective a trust anchor certificate should be augmented
+with local trust attributes, giving 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.
+If this information is missing, it is by default trusted for all uses.
+In PEM encoding, the presence of trust attributes
+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>.
-The last of these blocks all uses when rejected or enables all uses when trusted.
+explicitly stating acceptance for the listed uses
+and/or a set of negative trust attributes explicitly rejecting the listed uses.
+These uses are encoded using the OID values defined for the extended key usages
+that may be included in X.509v3 certificate extensions.
+For the list of EKUs with currently predefined meaning
+see the L</Extended Key Usage> section below.
+The special EKU B<anyExtendedKeyUsage>
+enables all uses when trusted or blocks all uses when rejected.
A certificate, which may be CA certificate or an end-entity certificate,
-is considered a trust anchor for the given use
+is considered a trust anchor for the intended use
if and only if all the following conditions hold:
=over 4
=item *
-It is an an element of the trust store.
+It is an element of the trust store.
=item *
-It does not have a negative trust attribute rejecting the given use.
+It does not have a negative trust attribute rejecting
+the EKU associated with the intended purpose.
=item *
-It has a positive trust attribute accepting the given use
-or (by default) one of the following compatibility conditions apply:
+It has a positive trust attribute accepting
+the EKU associated with the intended purpose
+or it does not have any positive trust attribute
+and one of the following compatibility 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).
First, a certificate chain is built up starting from the target certificate
and ending in a trust anchor.
+The goal is that for each certificate in the chain, except for the final one,
+the subject of the successor is the issuer of the former certificate.
+Since it often happens that the subject and issuer Distinguished Names
+are not unique, the subject and issuer key identifier extensions,
+if present in the certificates, are used to disambiguate conflicts.
-The chain is built up iteratively, looking up in turn a certificate that
+The chain is built up iteratively, looking up each certificate in turn that
matches as an issuer of the current "subject" certificate as described below.
-If there is such a certificate, the first one found that has a suitable validity
-period or otherwise has the latest expiration date of all matching certificates.
-For efficiency, no backtracking is performed, thus
+If there is more than one matching certificate, the algorithm uses
+the first certificate found that has a suitable validity period,
+otherwise the one with the latest expiration date of all matching certificates.
+For efficiency, the algorithm does not allow for backtracking, thus
any further candidate issuer certificates that would match equally are ignored.
-Certificate extensions are available since X.509 v3 and are mostly optional.
+Certificate extensions are available since X.509v3,
+and though many are optional, some are generally recommended or required.
For certificate chain building
-the subjectKeyIdentifier and authorityKeyIdentifier extensions are very useful,
-while subject alternative names (SAN) and issuer alternative names given
-in subjectAltName or issuerAltName extensions do not play a role.
+the subjectKeyIdentifier and authorityKeyIdentifier extensions are very useful.
+The subject alternative names (SAN) and issuer alternative names given in
+subjectAltName or issuerAltName extensions are not relevant for chain building.
-When a self-signed certificate has been added, chain construction stops.
+Once 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
The second step is to check the X.509v3 extensions of every certificate
for consistency with the intended specific purpose, if any.
-If the B<-purpose> option is not given then no such checks are done except for
+If no purpose is given explicitly then no such checks are done except for
CMS signature checking, where by default C<smimesign> is checked, and SSL/(D)TLS
connection setup, where by default C<sslserver> or C<sslclient> are checked.
The X.509v3 extensions of the target or "leaf" certificate
The precise extensions required are described in detail
in the L</Certificate Extensions> section below.
-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
+The third step is to check the trust settings on the last certificate or
+trust anchor, which typically is given as a self-signed root CA certificate.
+If specified, it must be trusted for the given use.
+For compatibility, 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.
=item *
-If a pathlenConstraint is given the key usage keyCertSign must be allowed.
+If a pathLenConstraint is given the key usage keyCertSign must be allowed.
=item *
-The pathlenConstraint must not be given for non-CA certificates.
+The pathLenConstraint must not be given for non-CA certificates.
=item *
=item B<-crl_check>
-Checks end entity certificate validity by attempting to look up a valid CRL.
+Checks end-entity certificate validity by attempting to look up a valid CRL.
If a valid CRL cannot be found an error occurs.
=item B<-crl_check_all>
-Checks the validity of
B<all> certificates in the chain by attempting
+Checks the validity of
I<all> certificates in the chain by attempting
to look up valid CRLs.
=item B<-use_deltas>
=item B<-no_alt_chains>
-Since B<-trusted_first> always on, this option has no effect.
+Since B<-trusted_first> is always on, this option has no effect.
=item B<-trusted> I<file>
are only for WWW use, in practice they are used for all kinds of TLS clients
and servers, and this is what OpenSSL assumes as well.
+For details on the checks performed see the L</Certificate Extensions> section.
+
=item B<-verify_depth> I<num>
Limit the certificate chain to I<num> intermediate CA certificates.
Options like B<-purpose> and B<-verify_name> trigger the processing of specific
certificate extensions, which determine what certificates can be used for.
+The following two subsections on the B<basicConstraints> and B<keyUsage>
+extensions and on X.509v1 certificates apply to I<all> CA certificates
+regardless of any required purpose.
+
=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
+if the CA flag is false then it is not a CA.
I<All> CAs should have the
CA flag set to true.
If the basicConstraints extension is absent,
=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
+made on the uses of the certificate. A CA certificate I<must> have the
keyCertSign bit set if the keyUsage extension is present.
+Further restrictions are checked depending on the required purpose, if any;
+for details see the list given in the next subsection.
=head3 Extended Key Usage
=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
+API. 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>).
projects / thirdparty / openssl.git / commitdiff
