Improve documentation, layout, and code comments regarding self-issued certs etc.

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10587)

5 files changed, 136 insertions, 95 deletions

diff --git a/doc/man1/openssl-verify.pod.in b/doc/man1/openssl-verify.pod.in
index 7271efe833..bccaa2642f 100644
--- a/doc/man1/openssl-verify.pod.in
+++ b/doc/man1/openssl-verify.pod.in
@@ -97,9 +97,9 @@ with a B<->.
 
 =item I<certificate> ...
 
-One or more certificates to verify. If no certificates are given,
+One or more target certificates to verify. If no certificates are given,
 this command will attempt to read a certificate from standard input.
-If a certificate chain has multiple problems, this program tries to
+If a certificate chain has multiple problems, this program attempts to
 display all of them.
 
 =back
@@ -115,9 +115,9 @@ general form of the error message is:
 The first line contains the name of the certificate being verified followed by
 the subject name of the certificate. The second line contains the error number
 and the depth. The depth is number of the certificate being verified when a
-problem was detected starting with zero for the certificate being verified itself
-then 1 for the CA that signed the certificate and so on. Finally a text version
-of the error number is presented.
+problem was detected starting with zero for the target ("leaf") certificate
+itself then 1 for the CA that signed the target certificate and so on.
+Finally a textual version of the error number is presented.
 
 A list of the error codes and messages can be found in
 L<X509_STORE_CTX_get_error(3)>; the full list is defined in the header file
diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index c9e75eb526..3c91757eaf 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -829,44 +829,55 @@ command handles errors are documented on the specific command page.
 Verification is a complicated process, consisting of a number of separate
 steps that are detailed in the following paragraphs.
 
-First, a certificate chain is built up starting from the supplied certificate
-and ending in a root CA.  It is an error if the whole chain cannot be
-built up.  The chain is built up by looking up the certificate that
-signed (or issued) the certificate. It then repeats the process, until
-it gets to a certificate that is self-issued.
+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.
 
 The process of looking up the issuer's certificate itself involves a number
-of steps.  After all certificates whose subject name 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, in addition the keyUsage extension of the
-candidate issuer (if present) must permit certificate signing.
-
-The lookup first looks in the list of untrusted certificates and if no match
-is found the remaining lookups are from the trusted certificates. The root CA
-is always looked up in the trusted certificate list: if the certificate to
-verify is a root certificate then an exact match must be found in the trusted
-list.
-
-The second step is to check every untrusted certificate's extensions
-for consistency with the supplied purpose. If the B<-purpose> option is
-not included then no checks are done. The supplied or "leaf" certificate
-must have extensions compatible with the supplied purpose and all other
-certificates must also be valid CA certificates. The precise extensions
-required are described in more detail in
+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; in addition the keyUsage
+extension of the candidate issuer (if present) must permit certificate signing.
+
+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 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.
+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 root CA. The root
-CA 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 fourth, and final, step is to check the validity of the certificate
-chain. The validity period is checked against the system time
-and the C<notBefore> and C<notAfter> dates in the certificate. The certificate
-signatures are also checked at this point. The B<-attime> flag may be
-used to specify a time other than "now."
+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 fourth, and final, step is to check the validity of the certificate chain.
+The validity period is checked against the system time
+and the C<notBefore> and C<notAfter> dates in each certificate.
+The B<-attime> flag may be used to specify a time other than "now."
+The certificate signatures are also checked at this point
+(except for the signature of the self-signed "root CA" certificate,
+which is verified only if the B<-check_ss_sig> option is given).
+When verifying a certificate signature
+the keyUsage extension (if present) of the candidate issuer certificate
+is checked to permit digitalSignature for signing proxy certificates or
+keyCertSign for signing other certificates, respectively.
 
 If all operations complete successfully then certificate is considered
 valid. If any operation fails then the certificate is not valid.
@@ -898,7 +909,7 @@ This disables non-compliant workarounds for broken certificates.
 
 =item B<-ignore_critical>
 
-Normally if an unhandled critical extension is present which is not
+Normally if an unhandled critical extension is present that is not
 supported by OpenSSL the certificate is rejected (as required by RFC5280).
 If this option is set critical extensions are ignored.
 
@@ -954,11 +965,14 @@ keys shorter than 1024 bits.
 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.
+This certificate may be self-issued or belong to an intermediate CA.
 
 =item B<-check_ss_sig>
 
-Verify the signature on the self-signed root CA. This is disabled by default
-because it doesn't add any security.
+Verify the signature on the last certificate in a chain
+even when it is a self-signed (root CA) certificate.
+By default in this case the check is disabled
+because it does not add any security.
 
 =item B<-allow_proxy_certs>
 
@@ -968,6 +982,10 @@ Allow the verification of proxy certificates.
 
 As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
 
+When constructing the certificate chain, the trusted certificates specified
+via B<-CAfile>, B<-CApath>, B<-CAstore> or B<-trusted> are always used
+before any certificates specified via B<-untrusted>.
+
 =item B<-no_alt_chains>
 
 As of OpenSSL 1.1.0, since B<-trusted_first> always on, this option has no
@@ -986,7 +1004,8 @@ 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 that may be used to
+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.
 This option may be used multiple times.
 
diff --git a/doc/man3/X509_STORE_CTX_get_error.pod b/doc/man3/X509_STORE_CTX_get_error.pod
index ce69e4da45..474dd4dc4f 100644
--- a/doc/man3/X509_STORE_CTX_get_error.pod
+++ b/doc/man3/X509_STORE_CTX_get_error.pod
@@ -107,24 +107,29 @@ Unspecified error; should not happen.
 
 The issuer certificate of a locally looked up certificate could not be found.
 This normally means the list of trusted certificates is not complete.
+To allow any certificate (not only a self-signed one) in the trust store
+to terminate the chain the B<X509_V_FLAG_PARTIAL_CHAIN> flag may be set.
 
 =item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
 
 The CRL of a certificate could not be found.
 
-=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
+=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE:
+unable to decrypt certificate's signature>
 
 The certificate signature could not be decrypted. This means that the actual
 signature value could not be determined rather than it not matching the
 expected value, this is only meaningful for RSA keys.
 
-=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
+=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE:
+unable to decrypt CRL's signature>
 
 The CRL signature could not be decrypted: this means that the actual signature
 value could not be determined rather than it not matching the expected value.
 Unused.
 
-=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
+=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY:
+unable to decode issuer public key>
 
 The public key in the certificate C<SubjectPublicKeyInfo> field could
 not be read.
@@ -155,19 +160,23 @@ The CRL is not yet valid.
 
 The CRL has expired.
 
-=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
+=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
+format error in certificate's notBefore field>
 
 The certificate B<notBefore> field contains an invalid time.
 
-=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
+=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
+format error in certificate's notAfter field>
 
 The certificate B<notAfter> field contains an invalid time.
 
-=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
+=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD:
+format error in CRL's lastUpdate field>
 
 The CRL B<lastUpdate> field contains an invalid time.
 
-=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
+=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD:
+format error in CRL's nextUpdate field>
 
 The CRL B<nextUpdate> field contains an invalid time.
 
@@ -175,25 +184,29 @@ The CRL B<nextUpdate> field contains an invalid time.
 
 An error occurred trying to allocate memory.
 
-=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
+=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate>
 
 The passed certificate is self-signed and the same certificate cannot be found
 in the list of trusted certificates.
 
-=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
+=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN:
+self-signed certificate in certificate chain>
 
-The certificate chain could be built up using the untrusted certificates but
-the root could not be found locally.
+The certificate chain could be built up using the untrusted certificates
+but no suitable trust anchor (which typically is a self-signed root certificate)
+could be found in the trust store.
 
-=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
+=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY:
+unable to get local issuer certificate>
 
 The issuer certificate could not be found: this occurs if the issuer certificate
 of an untrusted certificate cannot be found.
 
-=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
+=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE:
+unable to verify the first certificate>
 
 No signatures could be verified because the chain contains only one certificate
-and it is not self signed.
+and it is not self-signed and the B<X509_V_FLAG_PARTIAL_CHAIN> flag is not set.
 
 =item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
 
@@ -214,7 +227,7 @@ The basicConstraints path-length parameter has been exceeded.
 
 =item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
 
-The supplied certificate cannot be used for the specified purpose.
+The target certificate cannot be used for the specified purpose.
 
 =item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
 
@@ -229,32 +242,37 @@ The root CA is marked to reject the specified purpose.
 The current candidate issuer certificate was rejected because its subject name
 did not match the issuer name of the current certificate.
 
-=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
+=item B<X509_V_ERR_AKID_SKID_MISMATCH:
+authority and subject key identifier mismatch>
 
 The current candidate issuer certificate was rejected because its subject key
 identifier was present and did not match the authority key identifier current
 certificate.
 Not used as of OpenSSL 1.1.0.
 
-=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
+=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH:
+authority and issuer serial number mismatch>
 
 The current candidate issuer certificate was rejected because its issuer name
 and serial number was present and did not match the authority key identifier of
 the current certificate.
 Not used as of OpenSSL 1.1.0.
 
-=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
+=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:
+key usage does not include certificate signing>
 
 The current candidate issuer certificate was rejected because its B<keyUsage>
 extension does not permit certificate signing.
 Not used as of OpenSSL 1.1.0.
 
-=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension>
+=item B<X509_V_ERR_INVALID_EXTENSION:
+invalid or inconsistent certificate extension>
 
 A certificate extension had an invalid value (for example an incorrect
 encoding) or some value inconsistent with other extensions.
 
-=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension>
+=item B<X509_V_ERR_INVALID_POLICY_EXTENSION:
+invalid or inconsistent certificate policy extension>
 
 A certificate policies extension had an invalid value (for example an incorrect
 encoding) or some value inconsistent with other extensions. This error only
@@ -265,7 +283,7 @@ occurs if policy processing is enabled.
 The verification flags were set to require and explicit policy but none was
 present.
 
-=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope>
+=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: different CRL scope>
 
 The only CRLs that could be found did not match the scope of the certificate.
 
@@ -281,17 +299,20 @@ A name constraint violation occurred in the permitted subtrees.
 
 A name constraint violation occurred in the excluded subtrees.
 
-=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported>
+=item B<X509_V_ERR_SUBTREE_MINMAX:
+name constraints minimum and maximum not supported>
 
 A certificate name constraints extension included a minimum or maximum field:
 this is not supported.
 
-=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type>
+=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE:
+unsupported name constraint type>
 
 An unsupported name constraint type was encountered. OpenSSL currently only
 supports directory name, DNS name, email and URI types.
 
-=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax>
+=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX:
+unsupported or invalid name constraint syntax>
 
 The format of the name constraint is not recognised: for example an email
 address format of a form not mentioned in RFC3280. This could be caused by
@@ -384,7 +405,7 @@ CA signature digest algorithm too weak.
 
 =item B<X509_V_ERR_INVALID_CALL: invalid certificate verification context>
 
-invalid certificate verification context.
+Invalid certificate verification context.
 
 =item B<X509_V_ERR_STORE_LOOKUP: issuer certificate lookup error>
 
diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index f34020cbaa..72da4cb143 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -112,8 +112,8 @@ 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
-intermediate CA certificate between the trust-anchor and the end-entity
+directly by the trust anchor, while with a B<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
@@ -283,24 +283,25 @@ they are enabled.
 If B<X509_V_FLAG_USE_DELTAS> is set delta CRLs (if present) are used to
 determine certificate status. If not set deltas are ignored.
 
-B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed
-certificate signature. By default this check is disabled because it doesn't
+B<X509_V_FLAG_CHECK_SS_SIGNATURE> requires verifying the signature of the last
+certificate in a chain even when it is a self-signed (root CA) certificate.
+In this case the check is disabled by default because it does not
 add any additional security but in some cases applications might want to
 check the signature anyway. A side effect of not checking the root CA
 signature is that disabled or unsupported message digests on the root CA
 are not treated as fatal errors.
 
-When B<X509_V_FLAG_TRUSTED_FIRST> is set, construction of the certificate chain
-in L<X509_verify_cert(3)> will search the trust store for issuer certificates
+When B<X509_V_FLAG_TRUSTED_FIRST> is set, which is always the case 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.
 Local issuer certificates are often more likely to satisfy local security
 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)>).
-As of OpenSSL 1.1.0 this option is on by default.
 
-The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative
-chains.
+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
@@ -309,15 +310,15 @@ 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_PARTIAL_CHAIN> flag causes intermediate certificates in the
-trust store to be treated as trust-anchors, in the same way as the self-signed
+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 certificates issued by an intermediate CA
-without having to trust its ancestor root CA.
+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
-construction stops as soon as the first certificate from the trust store is
-added to the chain, whether that certificate is a self-signed "root"
-certificate or a not self-signed intermediate certificate.
+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.
 Thus, when an intermediate certificate is found in the trust store, the
 verified chain passed to callbacks may be shorter than it otherwise would
 be without the B<X509_V_FLAG_PARTIAL_CHAIN> flag.
diff --git a/doc/man3/X509_check_issued.pod b/doc/man3/X509_check_issued.pod
index d41dfcd53e..0e8ab7deb3 100644
--- a/doc/man3/X509_check_issued.pod
+++ b/doc/man3/X509_check_issued.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-X509_check_issued - checks if certificate is issued by another
+X509_check_issued - checks if certificate is likely issued by another
 certificate
 
 =head1 SYNOPSIS
@@ -14,23 +14,23 @@ certificate
 
 =head1 DESCRIPTION
 
-This function checks if certificate I<subject> was issued using CA
+X509_check_issued() checks if certificate I<subject> was likely issued using CA
 certificate I<issuer>. This function takes into account not only
-matching of issuer field of I<subject> with subject field of I<issuer>,
-but also compares B<authorityKeyIdentifier> extension of I<subject> with
-B<subjectKeyIdentifier> of I<issuer> if B<authorityKeyIdentifier>
-present in the I<subject> certificate and checks B<keyUsage> field of
-I<issuer>.
+matching of the issuer field of I<subject> with the subject field of I<issuer>,
+but also compares all sub-fields of the B<authorityKeyIdentifier> extension of
+I<subject>, as far as present, with the respective B<subjectKeyIdentifier>,
+serial number, and issuer fields of I<issuer>, as far as present. It also checks
+if the B<keyUsage> field (if present) of I<issuer> allows certificate signing.
+It does not actually check the certificate signature.
 
 =head1 RETURN VALUES
 
-Function return B<X509_V_OK> if certificate I<subject> is issued by
-I<issuer> or some B<X509_V_ERR*> constant to indicate an error.
+X509_check_issued() returns B<X509_V_OK> if all checks are successful
+or some B<X509_V_ERR*> constant to indicate an error.
 
 =head1 SEE ALSO
 
-L<X509_verify_cert(3)>,
-L<X509_check_ca(3)>,
+L<X509_verify_cert(3)>, L<X509_verify(3)>, L<X509_check_ca(3)>,
 L<openssl-verify(1)>
 
 =head1 COPYRIGHT