PDC: Identifier calculation, Identity generation, and handling of compact-pdc-identity format (project-chip#30159)

* PDC: Add key id calculation for network identities

* PDC: Add identity generation and parsing for the compact TLV format

* PDC: Add support for identity generation to the chip-cert tool

* Address review comments

* Address further review comments

* Prefix out parameters in new APIs

Fixes project-chip#29856

Author: ksperling-apple

src/credentials/CHIPCert.cpp

@@ -1095,12 +1095,19 @@ DLL_EXPORT CHIP_ERROR ChipEpochToASN1Time(uint32_t epochTime, chip::ASN1::ASN1Un
     return CHIP_NO_ERROR;
 }
 
+static CHIP_ERROR ValidateCertificateType(const ChipCertificateData & certData, CertType expectedType)
+{
+    CertType certType;
+    ReturnErrorOnFailure(certData.mSubjectDN.GetCertType(certType));
+    VerifyOrReturnError(certType == expectedType, CHIP_ERROR_WRONG_CERT_TYPE);
+    return CHIP_NO_ERROR;
+}
+
 CHIP_ERROR ValidateChipRCAC(const ByteSpan & rcac)
 {
     ChipCertificateSet certSet;
     ChipCertificateData certData;
     ValidationContext validContext;
-    CertType certType;
 
     // Note that this function doesn't check RCAC NotBefore / NotAfter time validity.
     // It is assumed that RCAC should be valid at the time of installation by definition.
@@ -1109,8 +1116,7 @@ CHIP_ERROR ValidateChipRCAC(const ByteSpan & rcac)
 
     ReturnErrorOnFailure(certSet.LoadCert(rcac, CertDecodeFlags::kGenerateTBSHash));
 
-    ReturnErrorOnFailure(certData.mSubjectDN.GetCertType(certType));
-    VerifyOrReturnError(certType == CertType::kRoot, CHIP_ERROR_WRONG_CERT_TYPE);
+    ReturnErrorOnFailure(ValidateCertificateType(certData, CertType::kRoot));
 
     VerifyOrReturnError(certData.mSubjectDN.IsEqual(certData.mIssuerDN), CHIP_ERROR_WRONG_CERT_TYPE);
 
@@ -1427,16 +1433,27 @@ CHIP_ERROR CertificateValidityPolicy::ApplyDefaultPolicy(const ChipCertificateDa
     }
 }
 
-CHIP_ERROR ValidateChipNetworkIdentity(const ByteSpan & cert)
+void InitNetworkIdentitySubject(ChipDN & name)
 {
-    ChipCertificateData certData;
-    ReturnErrorOnFailure(DecodeChipCert(cert, certData, CertDecodeFlags::kGenerateTBSHash));
+    name.Clear();
+    CHIP_ERROR err = name.AddAttribute_CommonName(kNetworkIdentityCN, /* not printable */ false);
+    VerifyOrDie(err == CHIP_NO_ERROR); // AddAttribute can't fail in this case
+}
 
-    CertType certType;
-    ReturnErrorOnFailure(certData.mSubjectDN.GetCertType(certType));
-    VerifyOrReturnError(certType == CertType::kNetworkIdentity, CHIP_ERROR_WRONG_CERT_TYPE);
+static CHIP_ERROR CalculateKeyIdentifierSha256(const P256PublicKeySpan & publicKey, MutableCertificateKeyId outKeyId)
+{
+    uint8_t hash[kSHA256_Hash_Length];
+    static_assert(outKeyId.size() <= sizeof(hash)); // truncating 32 bytes down to 20
+    ReturnErrorOnFailure(Hash_SHA256(publicKey.data(), publicKey.size(), hash));
+    memcpy(outKeyId.data(), hash, outKeyId.size());
+    return CHIP_NO_ERROR;
+}
+
+static CHIP_ERROR ValidateChipNetworkIdentity(const ChipCertificateData & certData)
+{
+    ReturnErrorOnFailure(ValidateCertificateType(certData, CertType::kNetworkIdentity));
 
-    VerifyOrReturnError(certData.mSerialNumber.data_equal(kNetworkIdentitySerialNumber), CHIP_ERROR_WRONG_CERT_TYPE);
+    VerifyOrReturnError(certData.mSerialNumber.data_equal(kNetworkIdentitySerialNumberBytes), CHIP_ERROR_WRONG_CERT_TYPE);
     VerifyOrReturnError(certData.mNotBeforeTime == kNetworkIdentityNotBeforeTime, CHIP_ERROR_WRONG_CERT_TYPE);
     VerifyOrReturnError(certData.mNotAfterTime == kNetworkIdentityNotAfterTime, CHIP_ERROR_WRONG_CERT_TYPE);
     VerifyOrReturnError(certData.mIssuerDN.IsEqual(certData.mSubjectDN), CHIP_ERROR_WRONG_CERT_TYPE);
@@ -1455,5 +1472,77 @@ CHIP_ERROR ValidateChipNetworkIdentity(const ByteSpan & cert)
     return CHIP_NO_ERROR;
 }
 
+CHIP_ERROR ValidateChipNetworkIdentity(const ByteSpan & cert)
+{
+    ChipCertificateData certData;
+    ReturnErrorOnFailure(DecodeChipCert(cert, certData, CertDecodeFlags::kGenerateTBSHash));
+    ReturnErrorOnFailure(ValidateChipNetworkIdentity(certData));
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR ValidateChipNetworkIdentity(const ByteSpan & cert, MutableCertificateKeyId outKeyId)
+{
+    ChipCertificateData certData;
+    ReturnErrorOnFailure(DecodeChipCert(cert, certData, CertDecodeFlags::kGenerateTBSHash));
+    ReturnErrorOnFailure(ValidateChipNetworkIdentity(certData));
+    ReturnErrorOnFailure(CalculateKeyIdentifierSha256(certData.mPublicKey, outKeyId));
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR ExtractIdentifierFromChipNetworkIdentity(const ByteSpan & cert, MutableCertificateKeyId outKeyId)
+{
+    ChipCertificateData certData;
+    ReturnErrorOnFailure(DecodeChipCert(cert, certData));
+    ReturnErrorOnFailure(ValidateCertificateType(certData, CertType::kNetworkIdentity));
+    ReturnErrorOnFailure(CalculateKeyIdentifierSha256(certData.mPublicKey, outKeyId));
+    return CHIP_NO_ERROR;
+}
+
+static CHIP_ERROR GenerateNetworkIdentitySignature(const P256Keypair & keypair, P256ECDSASignature & signature)
+{
+    // Create a buffer and writer to capture the TBS (to-be-signed) portion of the certificate.
+    chip::Platform::ScopedMemoryBuffer<uint8_t> asn1TBSBuf;
+    VerifyOrReturnError(asn1TBSBuf.Alloc(kNetworkIdentityTBSLength), CHIP_ERROR_NO_MEMORY);
+
+    ASN1Writer writer;
+    writer.Init(asn1TBSBuf.Get(), kNetworkIdentityTBSLength);
+
+    // Generate the TBSCertificate and sign it
+    ReturnErrorOnFailure(EncodeNetworkIdentityTBSCert(keypair.Pubkey(), writer));
+    ReturnErrorOnFailure(keypair.ECDSA_sign_msg(asn1TBSBuf.Get(), writer.GetLengthWritten(), signature));
+
+    return CHIP_NO_ERROR;
+}
+
+static CHIP_ERROR EncodeCompactIdentityCert(TLVWriter & writer, Tag tag, const P256PublicKeySpan & publicKey,
+                                            const P256ECDSASignatureSpan & signature)
+{
+    TLVType containerType;
+    ReturnErrorOnFailure(writer.StartContainer(tag, kTLVType_Structure, containerType));
+    ReturnErrorOnFailure(writer.Put(ContextTag(kTag_EllipticCurvePublicKey), publicKey));
+    ReturnErrorOnFailure(writer.Put(ContextTag(kTag_ECDSASignature), signature));
+    ReturnErrorOnFailure(writer.EndContainer(containerType));
+    return CHIP_NO_ERROR;
+}
+
+CHIP_ERROR NewChipNetworkIdentity(const Crypto::P256Keypair & keypair, MutableByteSpan & outCompactCert)
+{
+    VerifyOrReturnError(!outCompactCert.empty(), CHIP_ERROR_INVALID_ARGUMENT);
+    VerifyOrReturnError(CanCastTo<uint32_t>(outCompactCert.size()), CHIP_ERROR_INVALID_ARGUMENT);
+
+    Crypto::P256ECDSASignature signature;
+    ReturnErrorOnFailure(GenerateNetworkIdentitySignature(keypair, signature));
+
+    TLVWriter writer;
+    writer.Init(outCompactCert);
+
+    P256PublicKeySpan publicKeySpan(keypair.Pubkey().ConstBytes());
+    P256ECDSASignatureSpan signatureSpan(signature.ConstBytes());
+    ReturnErrorOnFailure(EncodeCompactIdentityCert(writer, AnonymousTag(), publicKeySpan, signatureSpan));
+
+    outCompactCert.reduce_size(writer.GetLengthWritten());
+    return CHIP_NO_ERROR;
+}
+
 } // namespace Credentials
 } // namespace chip

src/credentials/CHIPCert.h

@@ -53,8 +53,8 @@ static constexpr uint16_t kX509NoWellDefinedExpirationDateYear = 9999;
 static constexpr uint32_t kMaxCHIPCertLength = 400;
 static constexpr uint32_t kMaxDERCertLength  = 600;
 
-// The decode buffer is used to reconstruct TBS section of X.509 certificate, which doesn't include signature.
-static constexpr uint32_t kMaxCHIPCertDecodeBufLength = kMaxDERCertLength - Crypto::kMax_ECDSA_Signature_Length_Der;
+// As per spec section 11.24 (Wi-Fi Authentication with Per-Device Credentials)
+inline constexpr uint32_t kMaxCHIPCompactNetworkIdentityLength = 137;
 
 /** Data Element Tags for the CHIP Certificate
  */
@@ -395,6 +395,16 @@ class ChipDN
  */
 using CertificateKeyId = FixedByteSpan<kKeyIdentifierLength>;
 
+/**
+ *  @brief  A mutable `CertificateKeyId`.
+ */
+using MutableCertificateKeyId = FixedSpan<uint8_t, kKeyIdentifierLength>;
+
+/**
+ *  @brief  A storage type for `CertificateKeyId` and `MutableCertificateKeyId`.
+ */
+using CertificateKeyIdStorage = std::array<uint8_t, kKeyIdentifierLength>;
+
 /**
  *  @brief  A data structure for holding a P256 ECDSA signature, without the ownership of it.
  */
@@ -532,10 +542,13 @@ CHIP_ERROR ValidateChipRCAC(const ByteSpan & rcac);
 
 /**
  * Validates a Network (Client) Identity in TLV-encoded form.
+ * Accepts either a full certificate or the compact-pdc-identity format.
  *
  * This function parses the certificate, ensures the rigid fields have the values mandated by the
  * specification, and validates the certificate signature.
  *
+ * @param cert The network identity certificate to validate.
+ *
  * @return CHIP_NO_ERROR on success, CHIP_ERROR_WRONG_CERT_TYPE if the certificate does
  *         not conform to the requirements for a Network Identity, CHIP_ERROR_INVALID_SIGNATURE
  *         if the certificate has an invalid signature, or another CHIP_ERROR.
@@ -544,6 +557,14 @@ CHIP_ERROR ValidateChipRCAC(const ByteSpan & rcac);
  */
 CHIP_ERROR ValidateChipNetworkIdentity(const ByteSpan & cert);
 
+/**
+ * Convenience variant of `ValidateChipNetworkIdentity` that, upon successful validation, also
+ * calculates the key identifier for the Network (Client) Identity.
+ * @see ValidateChipNetworkIdentity
+ * @see ExtractIdentifierFromChipNetworkIdentity
+ */
+CHIP_ERROR ValidateChipNetworkIdentity(const ByteSpan & cert, MutableCertificateKeyId outKeyId);
+
 struct FutureExtension
 {
     ByteSpan OID;
@@ -598,6 +619,17 @@ CHIP_ERROR NewICAX509Cert(const X509CertRequestParams & requestParams, const Cry
 CHIP_ERROR NewNodeOperationalX509Cert(const X509CertRequestParams & requestParams, const Crypto::P256PublicKey & subjectPubkey,
                                       const Crypto::P256Keypair & issuerKeypair, MutableByteSpan & x509Cert);
 
+/**
+ * @brief Generates a Network (Client) Identity certificate in TLV-encoded form.
+ *
+ * @param keypair The key pair underlying the identity.
+ * @param outCompactCert Buffer to store the signed certificate in compact-pdc-identity TLV format.
+ *                       Must be at least `kMaxCHIPCompactNetworkIdentityLength` bytes long.
+ *
+ * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
+ **/
+CHIP_ERROR NewChipNetworkIdentity(const Crypto::P256Keypair & keypair, MutableByteSpan & outCompactCert);
+
 /**
  * @brief
  *   Convert a certificate date/time (in the form of an ASN.1 universal time structure) into a CHIP Epoch time.
@@ -827,5 +859,14 @@ CHIP_ERROR ExtractSubjectDNFromChipCert(const ByteSpan & chipCert, ChipDN & dn);
  */
 CHIP_ERROR ExtractSubjectDNFromX509Cert(const ByteSpan & x509Cert, ChipDN & dn);
 
+/**
+ * Extracts the key identifier from a Network (Client) Identity in TLV-encoded form.
+ * Does NOT perform full validation of the identity certificate.
+ *
+ * @return CHIP_NO_ERROR on success, CHIP_ERROR_WRONG_CERT_TYPE if the certificate is
+ *         not a Network (Client) Identity, or another CHIP_ERROR if parsing fails.
+ */
+CHIP_ERROR ExtractIdentifierFromChipNetworkIdentity(const ByteSpan & cert, MutableCertificateKeyId outKeyId);
+
 } // namespace Credentials
 } // namespace chip

src/credentials/CHIPCertToX509.cpp

@@ -31,7 +31,7 @@
 #include <inttypes.h>
 #include <stddef.h>
 
-#include <credentials/CHIPCert.h>
+#include <credentials/CHIPCert_Internal.h>
 #include <lib/asn1/ASN1.h>
 #include <lib/asn1/ASN1Macros.h>
 #include <lib/core/CHIPCore.h>
@@ -482,6 +482,8 @@ static CHIP_ERROR DecodeConvertECDSASignature(TLVReader & reader, ASN1Writer & w
  * @param certData  Structure containing data extracted from the TBS portion of the
  *                  CHIP certificate.
  *
+ * Note: The reader must be positioned on the SerialNumber element.
+ *
  * @return Returns a CHIP_ERROR on error, CHIP_NO_ERROR otherwise
  **/
 static CHIP_ERROR DecodeConvertTBSCert(TLVReader & reader, ASN1Writer & writer, ChipCertificateData & certData)
@@ -502,7 +504,7 @@ static CHIP_ERROR DecodeConvertTBSCert(TLVReader & reader, ASN1Writer & writer,
 
         // serialNumber CertificateSerialNumber
         // CertificateSerialNumber ::= INTEGER
-        ReturnErrorOnFailure(reader.Next(kTLVType_ByteString, ContextTag(kTag_SerialNumber)));
+        ReturnErrorOnFailure(reader.Expect(kTLVType_ByteString, ContextTag(kTag_SerialNumber)));
         ReturnErrorOnFailure(reader.Get(certData.mSerialNumber));
         ReturnErrorOnFailure(writer.PutValue(kASN1TagClass_Universal, kASN1UniversalTag_Integer, false,
                                              certData.mSerialNumber.data(), static_cast<uint16_t>(certData.mSerialNumber.size())));
@@ -543,6 +545,41 @@ static CHIP_ERROR DecodeConvertTBSCert(TLVReader & reader, ASN1Writer & writer,
     return err;
 }
 
+/**
+ * Variant of DecodeConvertTBSCert that handles reading a compact-pdc-identity
+ * where only the subject public key is actually encoded. All other values are
+ * populated / written as the well-known values mandated by the specification.
+ *
+ * Note: The reader must be positioned on the EllipticCurvePublicKey element.
+ */
+static CHIP_ERROR DecodeConvertTBSCertCompactIdentity(TLVReader & reader, ASN1Writer & writer, ChipCertificateData & certData)
+{
+    // Decode the public key, everything else is rigid
+    ReturnErrorOnFailure(reader.Expect(kTLVType_ByteString, ContextTag(kTag_EllipticCurvePublicKey)));
+    ReturnErrorOnFailure(reader.Get(certData.mPublicKey));
+
+    // Populate rigid ChipCertificateData fields
+    certData.mSerialNumber = kNetworkIdentitySerialNumberBytes;
+    certData.mSigAlgoOID   = kOID_SigAlgo_ECDSAWithSHA256;
+    InitNetworkIdentitySubject(certData.mIssuerDN);
+    certData.mNotBeforeTime = kNetworkIdentityNotBeforeTime;
+    certData.mNotAfterTime  = kNetworkIdentityNotAfterTime;
+    InitNetworkIdentitySubject(certData.mSubjectDN);
+    certData.mPubKeyAlgoOID  = kOID_PubKeyAlgo_ECPublicKey;
+    certData.mPubKeyCurveOID = kOID_EllipticCurve_prime256v1;
+    certData.mCertFlags.Set(CertFlags::kExtPresent_BasicConstraints);
+    certData.mCertFlags.Set(CertFlags::kExtPresent_KeyUsage);
+    certData.mKeyUsageFlags = kNetworkIdentityKeyUsage;
+    certData.mCertFlags.Set(CertFlags::kExtPresent_ExtendedKeyUsage);
+    certData.mKeyPurposeFlags = kNetworkIdentityKeyPurpose;
+
+    if (!writer.IsNullWriter())
+    {
+        ReturnErrorOnFailure(EncodeNetworkIdentityTBSCert(certData.mPublicKey, writer));
+    }
+    return CHIP_NO_ERROR;
+}
+
 /**
  * Decode a CHIP TLV certificate and convert it to X.509 DER form.
  *
@@ -570,7 +607,17 @@ static CHIP_ERROR DecodeConvertCert(TLVReader & reader, ASN1Writer & writer, ASN
     ASN1_START_SEQUENCE
     {
         // tbsCertificate TBSCertificate,
-        ReturnErrorOnFailure(DecodeConvertTBSCert(reader, tbsWriter, certData));
+        reader.Next();
+        if (reader.GetTag() == ContextTag(kTag_EllipticCurvePublicKey))
+        {
+            // If the struct starts with the ec-pub-key we're dealing with a
+            // Network (Client) Identity in compact-pdc-identity format.
+            DecodeConvertTBSCertCompactIdentity(reader, tbsWriter, certData);
+        }
+        else
+        {
+            ReturnErrorOnFailure(DecodeConvertTBSCert(reader, tbsWriter, certData));
+        }
 
         // signatureAlgorithm   AlgorithmIdentifier
         // AlgorithmIdentifier ::= SEQUENCE
@@ -640,7 +687,7 @@ CHIP_ERROR DecodeChipCert(TLVReader & reader, ChipCertificateData & certData, Bi
 
         // Hash the encoded TBS certificate. Only SHA256 is supported.
         VerifyOrReturnError(certData.mSigAlgoOID == kOID_SigAlgo_ECDSAWithSHA256, CHIP_ERROR_UNSUPPORTED_SIGNATURE_TYPE);
-        chip::Crypto::Hash_SHA256(asn1TBSBuf.Get(), tbsWriter.GetLengthWritten(), certData.mTBSHash);
+        ReturnErrorOnFailure(Hash_SHA256(asn1TBSBuf.Get(), tbsWriter.GetLengthWritten(), certData.mTBSHash));
         certData.mCertFlags.Set(CertFlags::kTBSHashPresent);
     }
     else

src/credentials/CHIPCert_Internal.h

@@ -23,10 +23,17 @@
 namespace chip {
 namespace Credentials {
 
+// The decode buffer is used to reconstruct TBS section of X.509 certificate, which doesn't include signature.
+inline constexpr size_t kMaxCHIPCertDecodeBufLength = kMaxDERCertLength - Crypto::kMax_ECDSA_Signature_Length_Der;
+
+// The TBSCerticate of a Network (Client) Identity has a fixed (smaller) size.
+inline constexpr size_t kNetworkIdentityTBSLength = 244;
+
 // Constants for Network (Client) Identities as per section 11.24 (Wi-Fi
 // Authentication with Per-Device Credentials) of the Matter spec.
-inline constexpr CharSpan kNetworkIdentityCN           = "*"_span;
-inline constexpr ByteSpan kNetworkIdentitySerialNumber = ByteSpan((uint8_t[1]){ 1 });
+inline constexpr CharSpan kNetworkIdentityCN                = "*"_span;
+inline constexpr uint8_t kNetworkIdentitySerialNumber       = 1;
+inline constexpr ByteSpan kNetworkIdentitySerialNumberBytes = ByteSpan((uint8_t[1]){ kNetworkIdentitySerialNumber });
 
 inline constexpr uint32_t kNetworkIdentityNotBeforeTime = 1;
 inline constexpr uint32_t kNetworkIdentityNotAfterTime  = kNullCertTime;
@@ -35,5 +42,11 @@ inline constexpr auto kNetworkIdentityKeyUsage = BitFlags<KeyUsageFlags>(KeyUsag
 inline constexpr auto kNetworkIdentityKeyPurpose =
     BitFlags<KeyPurposeFlags>(KeyPurposeFlags::kClientAuth, KeyPurposeFlags::kServerAuth);
 
+// Initializes a ChipDN as CN=kNetworkIdentityCN
+void InitNetworkIdentitySubject(ChipDN & name);
+
+// Emits a X.509 TBSCertificate for a Network (Client) Identity based on the specified key.
+CHIP_ERROR EncodeNetworkIdentityTBSCert(const Crypto::P256PublicKey & pubkey, ASN1::ASN1Writer & writer);
+
 } // namespace Credentials
 } // namespace chip