From 1080839c917a0fbb87d79de6c763932ec45f0d12 Mon Sep 17 00:00:00 2001 From: Boris Zbarsky Date: Wed, 8 Feb 2023 20:40:41 -0500 Subject: [PATCH] Clarify documentation around DNs in MTRCertificates and MTRCertificateInfo. (#24932) * Clarify documentation around DNs in MTRCertificates and MTRCertificateInfo. Fixes https://github.com/project-chip/connectedhomeip/issues/24908 * Address review comments. --- .../Framework/CHIP/MTRCertificateInfo.h | 36 ++++++++++++++++--- src/darwin/Framework/CHIP/MTRCertificates.h | 14 +++++--- 2 files changed, 41 insertions(+), 9 deletions(-) diff --git a/src/darwin/Framework/CHIP/MTRCertificateInfo.h b/src/darwin/Framework/CHIP/MTRCertificateInfo.h index 3d4d187f414498..6c92a6576a4903 100644 --- a/src/darwin/Framework/CHIP/MTRCertificateInfo.h +++ b/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 * caseAuthenticatedTags; diff --git a/src/darwin/Framework/CHIP/MTRCertificates.h b/src/darwin/Framework/CHIP/MTRCertificates.h index c87f34e3a3d131..fbcb2decced27f 100644 --- a/src/darwin/Framework/CHIP/MTRCertificates.h +++ b/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.