From e8c24b93046d3bcec18de14e694de39dcbdd4ce3 Mon Sep 17 00:00:00 2001
From: David Benjamin <davidben@google.com>
Date: Sat, 17 Feb 2024 23:27:25 -0500
Subject: [PATCH] Document the remaining struct types in x509.h

This is mostly all repetitive text, but a couple structures with unions
deserve special warning. The "ADB" (ANY DEFINED BY) stuff is pretty
scary.

Bug: 426
Change-Id: I85d27dd4e4676cf51c30529c53b6f2867c205caf
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/66391
Reviewed-by: Bob Beck <bbe@google.com>
Commit-Queue: David Benjamin <davidben@google.com>
(cherry picked from commit db614a5677d90e48cfb2c0f8197f1b5168fceea5)
---
 include/openssl/x509.h | 43 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/include/openssl/x509.h b/include/openssl/x509.h
index 40753ddfeb..1b6c28c18e 100644
--- a/include/openssl/x509.h
+++ b/include/openssl/x509.h
@@ -5134,11 +5134,14 @@ OPENSSL_EXPORT int X509_STORE_CTX_get_by_subject(X509_STORE_CTX *vs, int type,
                                                  X509_OBJECT *ret);
 
 
+// A BASIC_CONSTRAINTS_st, aka |BASIC_CONSTRAINTS| represents an
+// BasicConstraints structure (RFC 5280).
 struct BASIC_CONSTRAINTS_st {
   ASN1_BOOLEAN ca;
   ASN1_INTEGER *pathlen;
-};
+} /* BASIC_CONSTRAINTS */;
 
+// An ACCESS_DESCRIPTION represents an AccessDescription structure (RFC 5280).
 typedef struct ACCESS_DESCRIPTION_st {
   ASN1_OBJECT *method;
   GENERAL_NAME *location;
@@ -5150,6 +5153,13 @@ typedef STACK_OF(ACCESS_DESCRIPTION) AUTHORITY_INFO_ACCESS;
 
 typedef STACK_OF(ASN1_OBJECT) EXTENDED_KEY_USAGE;
 
+// A DIST_POINT_NAME represents a DistributionPointName structure (RFC 5280).
+// The |name| field contains the CHOICE value and is determined by |type|. If
+// |type| is zero, |name| must be a |fullname|. If |type| is one, |name| must be
+// a |relativename|.
+//
+// |type| and |name| must be kept consistent. An inconsistency will result in a
+// potentially exploitable memory error.
 typedef struct DIST_POINT_NAME_st {
   int type;
   union {
@@ -5160,32 +5170,46 @@ typedef struct DIST_POINT_NAME_st {
   X509_NAME *dpname;
 } DIST_POINT_NAME;
 
+// A DIST_POINT_st, aka |DIST_POINT|, represents a DistributionPoint structure
+// (RFC 5280).
 struct DIST_POINT_st {
   DIST_POINT_NAME *distpoint;
   ASN1_BIT_STRING *reasons;
   GENERAL_NAMES *CRLissuer;
-};
+} /* DIST_POINT */;
 
 typedef STACK_OF(DIST_POINT) CRL_DIST_POINTS;
 
 DEFINE_STACK_OF(DIST_POINT)
 
+// A AUTHORITY_KEYID_st, aka |AUTHORITY_KEYID|, represents an
+// AuthorityKeyIdentifier structure (RFC 5280).
 struct AUTHORITY_KEYID_st {
   ASN1_OCTET_STRING *keyid;
   GENERAL_NAMES *issuer;
   ASN1_INTEGER *serial;
-};
+} /* AUTHORITY_KEYID */;
 
+// A NOTICEREF represents a NoticeReference structure (RFC 5280).
 typedef struct NOTICEREF_st {
   ASN1_STRING *organization;
   STACK_OF(ASN1_INTEGER) *noticenos;
 } NOTICEREF;
 
+// A USERNOTICE represents a UserNotice structure (RFC 5280).
 typedef struct USERNOTICE_st {
   NOTICEREF *noticeref;
   ASN1_STRING *exptext;
 } USERNOTICE;
 
+// A POLICYQUALINFO represents a PolicyQualifierInfo structure (RFC 5280). |d|
+// contains the qualifier field of the PolicyQualifierInfo. Its type is
+// determined by |pqualid|. If |pqualid| is |NID_id_qt_cps|, |d| must be
+// |cpsuri|. If |pqualid| is |NID_id_qt_unotice|, |d| must be |usernotice|.
+// Otherwise, |d| must be |other|.
+//
+// |pqualid| and |d| must be kept consistent. An inconsistency will result in a
+// potentially exploitable memory error.
 typedef struct POLICYQUALINFO_st {
   ASN1_OBJECT *pqualid;
   union {
@@ -5197,6 +5221,7 @@ typedef struct POLICYQUALINFO_st {
 
 DEFINE_STACK_OF(POLICYQUALINFO)
 
+// A POLICYINFO represents a PolicyInformation structure (RFC 5280).
 typedef struct POLICYINFO_st {
   ASN1_OBJECT *policyid;
   STACK_OF(POLICYQUALINFO) *qualifiers;
@@ -5206,6 +5231,8 @@ typedef STACK_OF(POLICYINFO) CERTIFICATEPOLICIES;
 
 DEFINE_STACK_OF(POLICYINFO)
 
+// A POLICY_MAPPING represents an individual element of a PolicyMappings
+// structure (RFC 5280).
 typedef struct POLICY_MAPPING_st {
   ASN1_OBJECT *issuerDomainPolicy;
   ASN1_OBJECT *subjectDomainPolicy;
@@ -5215,6 +5242,7 @@ DEFINE_STACK_OF(POLICY_MAPPING)
 
 typedef STACK_OF(POLICY_MAPPING) POLICY_MAPPINGS;
 
+// A GENERAL_SUBTREE represents a GeneralSubtree structure (RFC 5280).
 typedef struct GENERAL_SUBTREE_st {
   GENERAL_NAME *base;
   ASN1_INTEGER *minimum;
@@ -5223,16 +5251,21 @@ typedef struct GENERAL_SUBTREE_st {
 
 DEFINE_STACK_OF(GENERAL_SUBTREE)
 
+// A NAME_CONSTRAINTS_st, aka |NAME_CONSTRAINTS|, represents a NameConstraints
+// structure (RFC 5280).
 struct NAME_CONSTRAINTS_st {
   STACK_OF(GENERAL_SUBTREE) *permittedSubtrees;
   STACK_OF(GENERAL_SUBTREE) *excludedSubtrees;
-};
+} /* NAME_CONSTRAINTS */;
 
+// A POLICY_CONSTRAINTS represents a PolicyConstraints structure (RFC 5280).
 typedef struct POLICY_CONSTRAINTS_st {
   ASN1_INTEGER *requireExplicitPolicy;
   ASN1_INTEGER *inhibitPolicyMapping;
 } POLICY_CONSTRAINTS;
 
+// A ISSUING_DIST_POINT_st, aka |ISSUING_DIST_POINT|, represents a
+// IssuingDistributionPoint structure (RFC 5280).
 struct ISSUING_DIST_POINT_st {
   DIST_POINT_NAME *distpoint;
   ASN1_BOOLEAN onlyuser;
@@ -5240,7 +5273,7 @@ struct ISSUING_DIST_POINT_st {
   ASN1_BIT_STRING *onlysomereasons;
   ASN1_BOOLEAN indirectCRL;
   ASN1_BOOLEAN onlyattr;
-};
+} /* ISSUING_DIST_POINT */;
 
 // X509_PURPOSE stuff