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>
diff --git a/include/openssl/x509.h b/include/openssl/x509.h
index f1b8ce6..6584945 100644
--- a/include/openssl/x509.h
+++ b/include/openssl/x509.h
@@ -4932,11 +4932,14 @@
DECLARE_STACK_OF(DIST_POINT)
+// 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;
@@ -4948,6 +4951,13 @@
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 {
@@ -4958,32 +4968,46 @@
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 {
@@ -4995,6 +5019,7 @@
DEFINE_STACK_OF(POLICYQUALINFO)
+// A POLICYINFO represents a PolicyInformation structure (RFC 5280).
typedef struct POLICYINFO_st {
ASN1_OBJECT *policyid;
STACK_OF(POLICYQUALINFO) *qualifiers;
@@ -5004,6 +5029,8 @@
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;
@@ -5013,6 +5040,7 @@
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;
@@ -5021,16 +5049,21 @@
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;
@@ -5038,7 +5071,7 @@
ASN1_BIT_STRING *onlysomereasons;
ASN1_BOOLEAN indirectCRL;
ASN1_BOOLEAN onlyattr;
-};
+} /* ISSUING_DIST_POINT */;
#define NS_SSL_CLIENT 0x80
#define NS_SSL_SERVER 0x40
