From: Dr. David von Oheimb Date: Tue, 28 Feb 2023 11:10:35 +0000 (+0100) Subject: openssl-verification-options.pod: improve description of certificate validation X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=dcac2c9e29de84d7692390abc9a32045748b3126;p=thirdparty%2Fopenssl.git openssl-verification-options.pod: improve description of certificate validation Reviewed-by: Paul Dale Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/18764) --- diff --git a/crypto/x509/v3_purp.c b/crypto/x509/v3_purp.c index 1db22047cf0..518b525866c 100644 --- a/crypto/x509/v3_purp.c +++ b/crypto/x509/v3_purp.c @@ -800,7 +800,7 @@ static int check_purpose_ns_ssl_server(const X509_PURPOSE *xp, const X509 *x, return ku_reject(x, KU_KEY_ENCIPHERMENT) ? 0 : ret; } -/* common S/MIME checks */ +/* common S/MIME client checks */ static int purpose_smime(const X509 *x, int non_leaf) { if (xku_reject(x, XKU_SMIME)) @@ -869,7 +869,7 @@ static int check_purpose_ocsp_helper(const X509_PURPOSE *xp, const X509 *x, */ if (non_leaf) return check_ca(x); - /* Leaf certificate is checked in OCSP_verify() */ + /* Leaf certificate is checked in OCSP_basic_verify() */ return 1; } diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod index 7e0c4627eb9..84940673cae 100644 --- a/doc/man1/openssl-verification-options.pod +++ b/doc/man1/openssl-verification-options.pod @@ -13,20 +13,34 @@ I =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 would actually be more +appropriate, +but for historical reasons the term I is often used instead. +In the sequel, the certificate to be validated is called I. +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. -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 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 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, which is a high-level specification of the intended use of the target certificate, -such as C for TLS servers, or (by default) for any purpose. +such as C 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. @@ -39,60 +53,67 @@ L, and L. In general, according to RFC 4158 and RFC 5280, a I 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, -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 section below. + +The most crucial input to certificate validation is a I, +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 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 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 section below. - -The currently recognized uses are -B (SSL client use), B (SSL server use), -B (S/MIME email use), B (object signer use), -B (OCSP responder use), B (OCSP request use), -B (TSA server use), and B. -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 section below. +The special EKU B +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 flag being set). @@ -102,21 +123,28 @@ It is self-signed or the B<-partial_chain> option is given 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 @@ -163,7 +191,7 @@ Part of these checks are enabled only if the B<-x509_strict> option is given. 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 is checked, and SSL/(D)TLS connection setup, where by default C or C are checked. The X.509v3 extensions of the target or "leaf" certificate @@ -173,10 +201,10 @@ and possibly also further non-standard checks are performed. The precise extensions required are described in detail in the L 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. @@ -296,11 +324,11 @@ CA certificates must explicitly include the keyUsage extension. =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 * @@ -347,12 +375,12 @@ Ignored. =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 certificates in the chain by attempting +Checks the validity of I certificates in the chain by attempting to look up valid CRLs. =item B<-use_deltas> @@ -418,7 +446,7 @@ before any certificates specified via B<-untrusted>. =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 @@ -481,6 +509,8 @@ While IETF RFC 5280 says that B and B 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 section. + =item B<-verify_depth> I Limit the certificate chain to I intermediate CA certificates. @@ -566,11 +596,15 @@ This option has no effect and is retained for backward compatibility only. 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 and B +extensions and on X.509v1 certificates apply to I 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 CAs should have the +if the CA flag is false then it is not a CA. I CAs should have the CA flag set to true. If the basicConstraints extension is absent, @@ -583,8 +617,10 @@ 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 have the +made on the uses of the certificate. A CA certificate I 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 @@ -717,7 +753,7 @@ For all other certificates the normal CA checks apply. =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>).