From f58dfb8241b6ab724ca614500524333d620bf0e9 Mon Sep 17 00:00:00 2001 From: Boris Zbarsky Date: Wed, 8 Feb 2023 18:15:22 -0500 Subject: [PATCH] Clarify documentation around DNs in MTRCertificates and MTRCertificateInfo. Fixes https://github.com/project-chip/connectedhomeip/issues/24908 --- .../Framework/CHIP/MTRCertificateInfo.h | 29 +++++++++++++++---- src/darwin/Framework/CHIP/MTRCertificates.h | 14 ++++++--- 2 files changed, 33 insertions(+), 10 deletions(-) diff --git a/src/darwin/Framework/CHIP/MTRCertificateInfo.h b/src/darwin/Framework/CHIP/MTRCertificateInfo.h index 3d4d187f414498..ac707bdffea167 100644 --- a/src/darwin/Framework/CHIP/MTRCertificateInfo.h +++ b/src/darwin/Framework/CHIP/MTRCertificateInfo.h @@ -34,11 +34,22 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4)) - (instancetype)init NS_UNAVAILABLE; /** - * Initializes the receiver with an operational certificate in Matter TLV format. + * 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 issuer distingushed name of the certificate. This is the subject + * distinguished name of whatever certificate signed this one. For a Matter + * root certificate, issuer will match subject. + */ @property (readonly) MTRDistinguishedNameInfo * issuer; + +/** + * The subject distinguished name of the certificate. + */ @property (readonly) MTRDistinguishedNameInfo * subject; @property (readonly) NSDate * notBefore; @@ -57,27 +68,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-nil 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.