x509/v3_purp.c etc.: improve doc/comments on codesign and timestamp purpose checks

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19064)

3 files changed, 35 insertions, 13 deletions

diff --git a/CHANGES.md b/CHANGES.md
index a55a6c47aa..e4dd7833fa 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -170,6 +170,11 @@ OpenSSL 3.2
 
    *Tomáš Mráz*
 
+ * Add X.509 certificate codeSigning purpose and related checks on key usage and
+   extended key usage of the leaf certificate according to the CA/Browser Forum.
+
+   * Lutz Jänicke*
+
  * Fix and extend certificate handling and the apps `x509`, `verify` etc.
    such as adding a trace facility for debugging certificate chain building.
 
diff --git a/crypto/x509/v3_purp.c b/crypto/x509/v3_purp.c
index a261d9082d..ce195daa5f 100644
--- a/crypto/x509/v3_purp.c
+++ b/crypto/x509/v3_purp.c
@@ -839,11 +839,22 @@ static int check_purpose_timestamp_sign(const X509_PURPOSE *xp, const X509 *x,
 {
     int i_ext;
 
-    /* If ca is true we must return if this is a valid CA certificate. */
+    /*
+     * If require_ca is true we must check if this is a valid CA certificate.
+     * The extra requirements by the CA/Browser Forum are not checked.
+     */
     if (require_ca)
         return check_ca(x);
 
     /*
+     * Key Usage is checked according to RFC 5280 and
+     * Extended Key Usage attributes is checked according to RFC 3161.
+     * The extra (and somewhat conflicting) CA/Browser Forum
+     * Baseline Requirements for the Issuance and Management of
+     * Publicly‐Trusted Code Signing Certificates, Version 3.0.0,
+     * Section 7.1.2.3: Code signing and Timestamp Certificate are not checked.
+     */
+    /*
      * Check the optional key usage field:
      * if Key Usage is present, it must be one of digitalSignature
      * and/or nonRepudiation (other values are not consistent and shall
@@ -871,21 +882,24 @@ static int check_purpose_code_sign(const X509_PURPOSE *xp, const X509 *x,
 {
     int i_ext;
 
-    /* If ca is true we must return if this is a valid CA certificate. */
+    /*
+     * If require_ca is true we must check if this is a valid CA certificate.
+     * The extra requirements by the CA/Browser Forum are not checked.
+     */
     if (require_ca)
         return check_ca(x);
 
     /*
      * Check the key usage and extended key usage fields:
      *
-     * Reference: CA Browser Forum,
-     * Baseline Requirements for the Issuance and Management of 
+     * Reference: CA/Browser Forum,
+     * Baseline Requirements for the Issuance and Management of
      * Publicly‐Trusted Code Signing Certificates, Version 3.0.0,
      * Section 7.1.2.3: Code signing and Timestamp Certificate
      *
      * Checking covers Key Usage and Extended Key Usage attributes.
-     * Other properties like CRL Distribution Points and Authoriy
-     * Information Access (AIA) are not checked.
+     * The certificatePolicies, cRLDistributionPoints (CDP), and
+     * authorityInformationAccess (AIA) extensions are so far not checked.
      */
     /* Key Usage */
     if ((x->ex_flags & EXFLAG_KUSAGE) == 0)
diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod
index 72f60093d7..d12dbfb803 100644
--- a/doc/man3/X509_STORE_CTX_new.pod
+++ b/doc/man3/X509_STORE_CTX_new.pod
@@ -189,13 +189,16 @@ B<X509_PURPOSE_NS_SSL_SERVER>, B<X509_PURPOSE_SMIME_SIGN>,
 B<X509_PURPOSE_SMIME_ENCRYPT>, B<X509_PURPOSE_CRL_SIGN>, B<X509_PURPOSE_ANY>,
 B<X509_PURPOSE_OCSP_HELPER>, B<X509_PURPOSE_TIMESTAMP_SIGN> and
 B<X509_PURPOSE_CODE_SIGN>.  It is also
-possible to create a custom purpose value. Setting a purpose will ensure that
-the key usage declared within certificates in the chain being verified is
-consistent with that purpose as well as, potentially, other checks. Every
-purpose also has an associated default trust value which will also be set at the
-same time. During verification this trust setting will be verified to check it
-is consistent with the trust set by the system administrator for certificates in
-the chain.
+possible to create a custom purpose value. Setting a purpose requests that
+the key usage and extended key usage (EKU) extensions optionally declared within
+the certificate and its chain are verified to be consistent with that purpose.
+For SSL client, SSL server, and S/MIME purposes, the EKU is checked also for the
+CA certificates along the chain, including any given trust anchor certificate.
+Potentially also further checks are done (depending on the purpose given).
+Every purpose also has an associated default trust value, which will also be set
+at the same time. During verification, this trust setting will be verified
+to check whether it is consistent with the trust set by the system administrator
+for certificates in the chain.
 
 X509_STORE_CTX_set_trust() sets the trust value for the target certificate
 being verified in the I<ctx>. Built-in available values for the I<trust>