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

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

apps/verify.c

@@ -356,7 +356,7 @@ static int cb(int ok, X509_STORE_CTX *ctx)
             policies_print(ctx);
             /* fall thru */
         case X509_V_ERR_CERT_HAS_EXPIRED:
-            /* Continue even if the leaf is a self signed cert */
+            /* Continue even if the leaf is a self-signed cert */
         case X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT:
             /* Continue after extension errors too */
         case X509_V_ERR_INVALID_CA:

apps/x509.c

@@ -135,7 +135,7 @@ const OPTIONS x509_options[] = {
     {"setalias", OPT_SETALIAS, 's', "Set certificate alias"},
     {"days", OPT_DAYS, 'n',
      "How long till expiry of a signed certificate - def 30 days"},
-    {"signkey", OPT_SIGNKEY, 's', "Self sign cert with arg"},
+    {"signkey", OPT_SIGNKEY, 's', "Self-sign cert with arg"},
     {"set_serial", OPT_SET_SERIAL, 's', "Serial number to use"},
     {"extensions", OPT_EXTENSIONS, 's', "Section from config file to use"},
     {"certopt", OPT_CERTOPT, 's', "Various certificate text options"},
@@ -1030,7 +1030,7 @@ static int x509_certify(X509_STORE *ctx, const char *CAfile, const EVP_MD *diges
         goto end;
 
     /*
-     * NOTE: this certificate can/should be self signed, unless it was a
+     * NOTE: this certificate can/should be self-signed, unless it was a
      * certificate request in which case it is not.
      */
     X509_STORE_CTX_set_cert(xsc, x);
@@ -1084,8 +1084,8 @@ static int callb(int ok, X509_STORE_CTX *ctx)
     X509 *err_cert;
 
     /*
-     * it is ok to use a self signed certificate This case will catch both
-     * the initial ok == 0 and the final ok == 1 calls to this function
+     * It is ok to use a self-signed certificate. This case will catch both
+     * the initial ok == 0 and the final ok == 1 calls to this function.
      */
     err = X509_STORE_CTX_get_error(ctx);
     if (err == X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT)
@@ -1098,7 +1098,7 @@ static int callb(int ok, X509_STORE_CTX *ctx)
      */
     if (ok) {
         BIO_printf(bio_err,
-                   "error with certificate to be certified - should be self signed\n");
+                   "error with certificate to be certified - should be self-signed\n");
         return 0;
     } else {
         err_cert = X509_STORE_CTX_get_current_cert(ctx);

crypto/x509/v3_purp.c

@@ -354,6 +354,7 @@ static int setup_crldp(X509 *x)
 #define ns_reject(x, usage) \
         (((x)->ex_flags & EXFLAG_NSCERT) && !((x)->ex_nscert & (usage)))
 
+/* this caches also further information, e.g., if the cert is self-issued */
 int X509v3_cache_extensions(X509 *x, OPENSSL_CTX *libctx, const char *propq)
 {
     BASIC_CONSTRAINTS *bs;
@@ -502,11 +503,10 @@ int X509v3_cache_extensions(X509 *x, OPENSSL_CTX *libctx, const char *propq)
         x->ex_flags |= EXFLAG_INVALID;
     /* Does subject name match issuer ? */
     if (!X509_NAME_cmp(X509_get_subject_name(x), X509_get_issuer_name(x))) {
-        x->ex_flags |= EXFLAG_SI;
-        /* If SKID matches AKID also indicate self signed */
-        if (X509_check_akid(x, x->akid) == X509_V_OK &&
-            !ku_reject(x, KU_KEY_CERT_SIGN))
-            x->ex_flags |= EXFLAG_SS;
+        x->ex_flags |= EXFLAG_SI; /* cert is self-issued */
+        if (X509_check_akid(x, x->akid) == X509_V_OK /* SKID matches AKID */
+            && !ku_reject(x, KU_KEY_CERT_SIGN))
+            x->ex_flags |= EXFLAG_SS; /* indicate self-signed */
     }
     x->altname = X509_get_ext_d2i(x, NID_subject_alt_name, &i, NULL);
     if (x->altname == NULL && i != -1)
@@ -559,7 +559,7 @@ int X509v3_cache_extensions(X509 *x, OPENSSL_CTX *libctx, const char *propq)
  * 1 is a CA
  * 2 Only possible in older versions of openSSL when basicConstraints are absent
  *   new versions will not return this value. May be a CA
- * 3 basicConstraints absent but self signed V1.
+ * 3 basicConstraints absent but self-signed V1.
  * 4 basicConstraints absent but keyUsage present and keyCertSign asserted.
  * 5 Netscape specific CA Flags present
  */
@@ -803,17 +803,17 @@ static int no_check(const X509_PURPOSE *xp, const X509 *x, int ca)
 }
 
 /*-
- * Various checks to see if one certificate issued the second.
- * 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.
+ * Various checks to see if one certificate potentially issued the second.
+ * 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. If key_usage(issuer) exists, check that it supports certificate signing
- * returns 0 for OK, positive for reason for mismatch, reasons match
- * codes for X509_verify_cert()
+ * 4. Check that any key_usage(issuer) allows certificate signing
+ * 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().
  */
 
 int x509_check_issued_int(X509 *issuer, X509 *subject, OPENSSL_CTX *libctx,
@@ -833,11 +833,8 @@ int x509_check_issued_int(X509 *issuer, X509 *subject, OPENSSL_CTX *libctx,
             return ret;
     }
 
+    /* check if the subject signature alg matches the issuer's PUBKEY alg */
     {
-        /*
-         * Check if the subject signature algorithm matches the issuer's PUBKEY
-         * algorithm
-         */
         EVP_PKEY *i_pkey = X509_get0_pubkey(issuer);
         X509_ALGOR *s_algor = &subject->cert_info.signature;
         int s_pknid = NID_undef, s_mdnid = NID_undef;

crypto/x509/x509_txt.c

@@ -58,9 +58,9 @@ const char *X509_verify_cert_error_string(long n)
     case X509_V_ERR_OUT_OF_MEM:
         return "out of memory";
     case X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT:
-        return "self signed certificate";
+        return "self-signed certificate";
     case X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN:
-        return "self signed certificate in certificate chain";
+        return "self-signed certificate in certificate chain";
     case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY:
         return "unable to get local issuer certificate";
     case X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE:

crypto/x509/x509_vfy.c

@@ -111,7 +111,13 @@ static int null_callback(int ok, X509_STORE_CTX *e)
     return ok;
 }
 
-/* Return 1 is a certificate is self signed, 0 if not, or -1 on error */
+/*
+ * Return 1 if given cert is considered self-signed, 0 if not, or -1 on error.
+ * This does not verify self-signedness but relies on x509v3_cache_extensions()
+ * matching issuer and subject names (i.e., the cert being self-issued) and any
+ * present authority key identifier matching the subject key identifier, etc.
+ * Moreover the key usage (if present) must allow certificate signing - TODO correct this wrong semantics of x509v3_cache_extensions()
+ */
 static int cert_self_signed(X509_STORE_CTX *ctx, X509 *x)
 {
     if (!X509v3_cache_extensions(x, ctx->libctx, ctx->propq))
@@ -356,7 +362,7 @@ static int check_issued(X509_STORE_CTX *ctx, X509 *x, X509 *issuer)
         if (ss < 0)
             return 0;
 
-        /* Special case: single self signed certificate */
+        /* Special case: single (likely) self-signed certificate */
         if (ss > 0 && sk_X509_num(ctx->chain) == 1)
             return 1;
         for (i = 0; i < sk_X509_num(ctx->chain); i++) {
@@ -562,7 +568,7 @@ static int check_chain_extensions(X509_STORE_CTX *ctx)
             if (!verify_cb_cert(ctx, x, i, X509_V_ERR_PATH_LENGTH_EXCEEDED))
                 return 0;
         }
-        /* Increment path length if not a self issued intermediate CA */
+        /* Increment path length if not a self-issued intermediate CA */
         if (i > 0 && (x->ex_flags & EXFLAG_SI) == 0)
             plen++;
         /*
@@ -628,7 +634,7 @@ static int check_name_constraints(X509_STORE_CTX *ctx)
         X509 *x = sk_X509_value(ctx->chain, i);
         int j;
 
-        /* Ignore self issued certs unless last in chain */
+        /* Ignore self-issued certs unless last in chain */
         if (i && (x->ex_flags & EXFLAG_SI))
             continue;
 
@@ -1527,7 +1533,7 @@ static int check_crl(X509_STORE_CTX *ctx, X509_CRL *crl)
     int cnum = ctx->error_depth;
     int chnum = sk_X509_num(ctx->chain) - 1;
 
-    /* if we have an alternative CRL issuer cert use that */
+    /* If we have an alternative CRL issuer cert use that */
     if (ctx->current_issuer)
         issuer = ctx->current_issuer;
     /*
@@ -1538,7 +1544,7 @@ static int check_crl(X509_STORE_CTX *ctx, X509_CRL *crl)
         issuer = sk_X509_value(ctx->chain, cnum + 1);
     else {
         issuer = sk_X509_value(ctx->chain, chnum);
-        /* If not self signed, can't check signature */
+        /* If not self-issued, can't check signature */
         if (!ctx->check_issued(ctx, issuer, issuer) &&
             !verify_cb_crl(ctx, X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER))
             return 0;
@@ -1753,7 +1759,7 @@ static int internal_verify(X509_STORE_CTX *ctx)
         goto check_cert;
     }
 
-    if (ctx->check_issued(ctx, xi, xi))
+    if (ctx->check_issued(ctx, xi, xi)) /* the last cert appears self-signed */
         xs = xi;
     else {
         if (ctx->param->flags & X509_V_FLAG_PARTIAL_CHAIN) {
@@ -1776,9 +1782,9 @@ static int internal_verify(X509_STORE_CTX *ctx)
         EVP_PKEY *pkey;
 
         /*
-         * Skip signature check for self signed certificates unless explicitly
-         * asked for.  It doesn't add any security and just wastes time.  If
-         * the issuer's public key is unusable, report the issuer certificate
+         * Skip signature check for self-signed certificates unless explicitly
+         * asked for because it does not add any security and just wastes time.
+         * If the issuer's public key is unusable, report the issuer certificate
          * and its depth (rather than the depth of the subject).
          */
         if (xs != xi || (ctx->param->flags & X509_V_FLAG_CHECK_SS_SIGNATURE)) {
@@ -2803,7 +2809,7 @@ static int check_dane_issuer(X509_STORE_CTX *ctx, int depth)
         return  X509_TRUST_UNTRUSTED;
 
     /*
-     * Record any DANE trust-anchor matches, for the first depth to test, if
+     * Record any DANE trust anchor matches, for the first depth to test, if
      * there's one at that depth. (This'll be false for length 1 chains looking
      * for an exact match for the leaf certificate).
      */
@@ -2889,7 +2895,7 @@ static int dane_verify(X509_STORE_CTX *ctx)
      * When testing the leaf certificate, if we match a DANE-EE(3) record,
      * dane_match() returns 1 and we're done.  If however we match a PKIX-EE(1)
      * record, the match depth and matching TLSA record are recorded, but the
-     * return value is 0, because we still need to find a PKIX trust-anchor.
+     * return value is 0, because we still need to find a PKIX trust anchor.
      * Therefore, when DANE authentication is enabled (required), we're done
      * if:
      *   + matched < 0, internal error.
@@ -3012,7 +3018,7 @@ static int build_chain(X509_STORE_CTX *ctx)
     }
 
     /*
-     * If we got any "DANE-TA(2) Cert(0) Full(0)" trust-anchors from DNS, add
+     * If we got any "DANE-TA(2) Cert(0) Full(0)" trust anchors from DNS, add
      * them to our working copy of the untrusted certificate stack.  Since the
      * caller of X509_STORE_CTX_init() may have provided only a leaf cert with
      * no corresponding stack of untrusted certificates, we may need to create
@@ -3045,7 +3051,7 @@ static int build_chain(X509_STORE_CTX *ctx)
         ctx->param->depth = INT_MAX/2;
 
     /*
-     * Try to Extend the chain until we reach an ultimately trusted issuer.
+     * Try to extend the chain until we reach an ultimately trusted issuer.
      * Build chains up to one longer the limit, later fail if we hit the limit,
      * with an X509_V_ERR_CERT_CHAIN_TOO_LONG error code.
      */
@@ -3059,7 +3065,7 @@ static int build_chain(X509_STORE_CTX *ctx)
          * Look in the trust store if enabled for first lookup, or we've run
          * out of untrusted issuers and search here is not disabled.  When we
          * reach the depth limit, we stop extending the chain, if by that point
-         * we've not found a trust-anchor, any trusted chain would be too long.
+         * we've not found a trust anchor, any trusted chain would be too long.
          *
          * The error reported to the application verify callback is at the
          * maximal valid depth with the current certificate equal to the last
@@ -3105,8 +3111,8 @@ static int build_chain(X509_STORE_CTX *ctx)
                  * Alternative trusted issuer for a mid-chain untrusted cert?
                  * Pop the untrusted cert's successors and retry.  We might now
                  * be able to complete a valid chain via the trust store.  Note
-                 * that despite the current trust-store match we might still
-                 * fail complete the chain to a suitable trust-anchor, in which
+                 * that despite the current trust store match we might still
+                 * fail complete the chain to a suitable trust anchor, in which
                  * case we may prune some more untrusted certificates and try
                  * again.  Thus the S_DOALTERNATE bit may yet be turned on
                  * again with an even shorter untrusted chain!
@@ -3163,7 +3169,7 @@ static int build_chain(X509_STORE_CTX *ctx)
                     /*
                      * We have a self-signed certificate that has the same
                      * subject name (and perhaps keyid and/or serial number) as
-                     * a trust-anchor.  We must have an exact match to avoid
+                     * a trust anchor.  We must have an exact match to avoid
                      * possible impersonation via key substitution etc.
                      */
                     if (X509_cmp(x, xtmp) != 0) {

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

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.
 

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>
 

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.

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

test/recipes/25-test_verify.t

@@ -374,7 +374,7 @@ SKIP: {
 
     # ED25519 certificate from draft-ietf-curdle-pkix-04
     ok(verify("ee-ed25519", "sslserver", ["root-ed25519"], []),
-       "ED25519 signature");
+       "accept X25519 EE cert issued by trusted Ed25519 self-signed CA cert");
 
 }