MTRCertificates.h

/**
 *    Copyright (c) 2022-2023 Project CHIP Authors
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

/**
 * Utilities for working with Matter certificates.
 */

#import <Foundation/Foundation.h>

#import <Matter/MTRDefines.h>

NS_ASSUME_NONNULL_BEGIN

@protocol MTRKeypair;

MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
@interface MTRCertificates : NSObject

- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;

/**
 * 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 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.
 *
 * validityPeriod specifies when the certificate will be valid. Note that
 * there is currently no mechanism available in Matter to update or rotate
 * the root certificate of a fabric installed on a device. A certificate with
 * no expiration time can be created by specifying [NSDate distantFuture] for
 * the end of the period.
 *
 * On failure returns nil and if "error" is not null sets *error to the relevant
 * error.
 */
+ (MTRCertificateDERBytes _Nullable)createRootCertificate:(id<MTRKeypair>)keypair
                                                 issuerID:(NSNumber * _Nullable)issuerID
                                                 fabricID:(NSNumber * _Nullable)fabricID
                                           validityPeriod:(NSDateInterval *)validityPeriod
                                                    error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_AVAILABLE(ios(16.6), macos(13.5), watchos(9.6), tvos(16.6));

/**
 * As above, but defaults to no expiration time.
 */
+ (MTRCertificateDERBytes _Nullable)createRootCertificate:(id<MTRKeypair>)keypair
                                                 issuerID:(NSNumber * _Nullable)issuerID
                                                 fabricID:(NSNumber * _Nullable)fabricID
                                                    error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));

/**
 * Create an intermediate X.509 DER encoded certificate that has the
 * right fields to be a valid Matter intermediate certificate.
 *
 * 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.
 *
 * validityPeriod specifies when the certificate will be valid. A certificate
 * with no expiration time can be created by specifying [NSDate distantFuture]
 * for the end of the period.
 *
 * On failure returns nil and if "error" is not null sets *error to the relevant
 * error.
 */
+ (MTRCertificateDERBytes _Nullable)createIntermediateCertificate:(id<MTRKeypair>)rootKeypair
                                                  rootCertificate:(MTRCertificateDERBytes)rootCertificate
                                            intermediatePublicKey:(SecKeyRef)intermediatePublicKey
                                                         issuerID:(NSNumber * _Nullable)issuerID
                                                         fabricID:(NSNumber * _Nullable)fabricID
                                                   validityPeriod:(NSDateInterval *)validityPeriod
                                                            error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_AVAILABLE(ios(16.6), macos(13.5), watchos(9.6), tvos(16.6));

/**
 * As above, but defaults to no expiration time.
 */
+ (MTRCertificateDERBytes _Nullable)createIntermediateCertificate:(id<MTRKeypair>)rootKeypair
                                                  rootCertificate:(MTRCertificateDERBytes)rootCertificate
                                            intermediatePublicKey:(SecKeyRef)intermediatePublicKey
                                                         issuerID:(NSNumber * _Nullable)issuerID
                                                         fabricID:(NSNumber * _Nullable)fabricID
                                                            error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));

/**
 * Create an X.509 DER encoded certificate that has the
 * right fields to be a valid Matter operational certificate.
 *
 * signingKeypair and signingCertificate are the root or intermediate that is
 * signing the operational certificate.
 *
 * nodeID and fabricID are expected to be 64-bit unsigned integers.
 *
 * nodeID must be a valid Matter operational node id.
 *
 * fabricID must be a valid Matter fabric id.
 *
 * caseAuthenticatedTags may be nil to indicate no CASE Authenticated Tags
 * should be used.  If caseAuthenticatedTags is not nil, it must contain at most
 * 3 numbers, which are expected to be 32-bit unsigned Case Authenticated Tag
 * values.
 *
 * validityPeriod specifies when the certificate will be valid. A certificate
 * with no expiration time can be created by specifying [NSDate distantFuture]
 * for the end of the period.
 *
 * On failure returns nil and if "error" is not null sets *error to the relevant
 * error.
 */
+ (MTRCertificateDERBytes _Nullable)createOperationalCertificate:(id<MTRKeypair>)signingKeypair
                                              signingCertificate:(MTRCertificateDERBytes)signingCertificate
                                            operationalPublicKey:(SecKeyRef)operationalPublicKey
                                                        fabricID:(NSNumber *)fabricID
                                                          nodeID:(NSNumber *)nodeID
                                           caseAuthenticatedTags:(NSSet<NSNumber *> * _Nullable)caseAuthenticatedTags
                                                  validityPeriod:(NSDateInterval *)validityPeriod
                                                           error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_AVAILABLE(ios(16.6), macos(13.5), watchos(9.6), tvos(16.6));

/**
 * As above, but defaults to no expiration time.
 */
+ (MTRCertificateDERBytes _Nullable)createOperationalCertificate:(id<MTRKeypair>)signingKeypair
                                              signingCertificate:(MTRCertificateDERBytes)signingCertificate
                                            operationalPublicKey:(SecKeyRef)operationalPublicKey
                                                        fabricID:(NSNumber *)fabricID
                                                          nodeID:(NSNumber *)nodeID
                                           caseAuthenticatedTags:(NSSet<NSNumber *> * _Nullable)caseAuthenticatedTags
                                                           error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));

/**
 * Check whether the given keypair's public key matches the given certificate's
 * public key.  The certificate is expected to be an X.509 DER encoded
 * certificate.
 *
 * Will return NO on failures to extract public keys from the objects.
 */
+ (BOOL)keypair:(id<MTRKeypair>)keypair matchesCertificate:(NSData *)certificate;

/**
 * Check whether two X.509 DER encoded certificates are equivalent, in the sense
 * of having the same public key and the same subject DN.  Returns NO if public
 * keys or subject DNs cannot be extracted from the certificates.
 */
+ (BOOL)isCertificate:(MTRCertificateDERBytes)certificate1 equalTo:(MTRCertificateDERBytes)certificate2;

/**
 * Generate a PKCS#10 certificate signing request from a MTRKeypair.  This can
 * then be used to request an operational or ICA certificate from an external
 * certificate authority.
 *
 * The CSR will have the subject OU DN set to 'CSA', because omitting all
 * identifying information altogether often trips up CSR parsing code.  The CA
 * being used should expect this and ignore the request subject, producing a
 * subject that matches the rules for Matter certificates.
 *
 * On failure returns nil and if "error" is not null sets *error to the relevant
 * error.
 */
+ (MTRCSRDERBytes _Nullable)createCertificateSigningRequest:(id<MTRKeypair>)keypair
                                                      error:(NSError * __autoreleasing _Nullable * _Nullable)error;

/**
 * Convert the given X.509v3 DER encoded certificate to the Matter certificate
 * format.
 *
 * Returns nil if the conversion fails (e.g. if the input data cannot be parsed
 * as a DER encoded X.509 certificate, or if the certificate cannot be
 * represented in the Matter certificate format).
 */
+ (MTRCertificateTLVBytes _Nullable)convertX509Certificate:(MTRCertificateDERBytes)x509Certificate;

/**
 * Convert the given Matter TLV encoded certificate to the X.509v3 DER encoded
 * format.
 *
 * Returns nil if the conversion fails (e.g. if the input data cannot be parsed
 * as a Matter TLV encoded certificate, or if the certificate cannot be
 * represented in the X.509v3 DER format).
 */
+ (MTRCertificateDERBytes _Nullable)convertMatterCertificate:(MTRCertificateTLVBytes)matterCertificate
    MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));

/**
 * Extract the public key from the given PKCS#10 certificate signing request.
 * This is the public key that a certificate issued in response to the request
 * would need to have.
 */
+ (NSData * _Nullable)publicKeyFromCSR:(MTRCSRDERBytes)csr
                                 error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));

@end

@interface MTRCertificates (Deprecated)

+ (nullable NSData *)generateRootCertificate:(id<MTRKeypair>)keypair
                                    issuerId:(nullable NSNumber *)issuerId
                                    fabricId:(nullable NSNumber *)fabricId
                                       error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_DEPRECATED("Please use createRootCertificate:issuerID:fabricID:error:", ios(16.1, 16.4), macos(13.0, 13.3),
        watchos(9.1, 9.4), tvos(16.1, 16.4));

+ (nullable NSData *)generateIntermediateCertificate:(id<MTRKeypair>)rootKeypair
                                     rootCertificate:(NSData *)rootCertificate
                               intermediatePublicKey:(SecKeyRef)intermediatePublicKey
                                            issuerId:(nullable NSNumber *)issuerId
                                            fabricId:(nullable NSNumber *)fabricId
                                               error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_DEPRECATED("Please use createIntermediateCertificate:rootCertificate:intermediatePublicKey:issuerID:fabricID:error:",
        ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));

+ (nullable NSData *)generateOperationalCertificate:(id<MTRKeypair>)signingKeypair
                                 signingCertificate:(NSData *)signingCertificate
                               operationalPublicKey:(SecKeyRef)operationalPublicKey
                                           fabricId:(NSNumber *)fabricId
                                             nodeId:(NSNumber *)nodeId
                              caseAuthenticatedTags:(NSArray<NSNumber *> * _Nullable)caseAuthenticatedTags
                                              error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_DEPRECATED(
        "Plase use "
        "createOperationalCertificate:signingCertificate:operationalPublicKey:fabricID:nodeID:caseAuthenticatedTags:error:",
        ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));

+ (nullable NSData *)generateCertificateSigningRequest:(id<MTRKeypair>)keypair
                                                 error:(NSError * __autoreleasing _Nullable * _Nullable)error
    MTR_DEPRECATED("Please use createCertificateSigningRequest:error:", ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4),
        tvos(16.1, 16.4));

@end

NS_ASSUME_NONNULL_END