Clarify documentation around DNs in MTRCertificates and MTRCertificat…

…eInfo. (#24932)

* Clarify documentation around DNs in MTRCertificates and MTRCertificateInfo.

Fixes #24908

* Address review comments.

src/darwin/Framework/CHIP/MTRCertificateInfo.h

@@ -35,10 +35,30 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
 
 /**
  * Initializes the receiver with an operational certificate in Matter TLV format.
+ *
+ * This can be a node operational certificate, a Matter intermediate
+ * certificate, or a Matter root certificate.
  */
 - (nullable instancetype)initWithTLVBytes:(MTRCertificateTLVBytes)bytes;
 
+/**
+ * The Distinguished Name of the issuer of the certificate.
+ *
+ * For a node operational certificate, the issuer will match the subject of the
+ * root certificate or intermediate certificate that represents the entity that
+ * issued the node operational certificate.
+ *
+ * For an intermediate certificate, the issuer will match the subject of the
+ * root certificate.
+ *
+ * Matter root certificates are self-signed, i.e. the issuer and the subject are
+ * the same.
+ */
 @property (readonly) MTRDistinguishedNameInfo * issuer;
+
+/**
+ * The Distinguished Name of the entity represented by the certificate.
+ */
 @property (readonly) MTRDistinguishedNameInfo * subject;
 
 @property (readonly) NSDate * notBefore;
@@ -57,27 +77,33 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
 - (instancetype)init NS_UNAVAILABLE;
 
 /**
- * The Node ID contained in the DN, if any.
+ * The Node ID contained in the DN, if any.  Will be non-nil for the subject of
+ * a valid node operational certificate.
  */
 @property (readonly, nullable) NSNumber * nodeID;
 
 /**
- * The Fabric ID contained in the DN, if any.
+ * The Fabric ID contained in the DN, if any.  Will be non-nil for the subject
+ * of a valid node operational certificate, and may be non-nil for the subject
+ * of a valid intermediate or root certificate.
  */
 @property (readonly, nullable) NSNumber * fabricID;
 
 /**
- * The `RCAC` ID contained in the DN, if any.
+ * The `RCAC` ID contained in the DN, if any.  Will be non-nil for the subject
+ * of a valid root certificate.
  */
 @property (readonly, nullable) NSNumber * rootCACertificateID;
 
 /**
- * The `ICAC` ID contained in the DN, if any.
+ * The `ICAC` ID contained in the DN, if any.  Will be non-nil for the subject
+ * of a valid intermediate certificate.
  */
 @property (readonly, nullable) NSNumber * intermediateCACertificateID;
 
 /**
- * The set of CASE Authenticated Tags contained in the DN.
+ * The set of CASE Authenticated Tags contained in the DN.  Maybe be non-empty for
+ * the subject of a valid node operational certificate.
  */
 @property (readonly) NSSet<NSNumber *> * caseAuthenticatedTags;
 

src/darwin/Framework/CHIP/MTRCertificates.h

@@ -35,8 +35,11 @@ NS_ASSUME_NONNULL_BEGIN
  * Create a root (self-signed) X.509 DER encoded certificate that has the
  * right fields to be a valid Matter root certificate.
  *
- * If issuerID is nil, a random issuer id is generated.  Otherwise the provided
- * issuer id is used.
+ * If issuerID is not nil, it's unsignedLongLongValue will be used for the
+ * matter-rcac-id attribute in the subject distinguished name of the resulting
+ * certificate.
+ *
+ * If issuerID is nil, a random value will be generated for matter-rcac-id.
  *
  * If fabricID is not nil, it will be included in the subject DN of the
  * certificate.  In this case it must be a valid Matter fabric id.
@@ -54,8 +57,11 @@ NS_ASSUME_NONNULL_BEGIN
  * Create an intermediate X.509 DER encoded certificate that has the
  * right fields to be a valid Matter intermediate certificate.
  *
- * If issuerID is nil, a random issuer id is generated.  Otherwise the provided
- * issuer id is used.
+ * If issuerID is not nil, it's unsignedLongLongValue will be used for the
+ * matter-icac-id attribute in the subject distinguished name of the resulting
+ * certificate.
+ *
+ * If issuerID is nil, a random value will be generated for matter-icac-id.
  *
  * If fabricID is not nil, it will be included in the subject DN of the
  * certificate.  In this case it must be a valid Matter fabric id.