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)

3 files changed, 74 insertions, 52 deletions

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