Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2021 Project CHIP Authors
4 : *
5 : * Licensed under the Apache License, Version 2.0 (the "License");
6 : * you may not use this file except in compliance with the License.
7 : * You may obtain a copy of the License at
8 : *
9 : * http://www.apache.org/licenses/LICENSE-2.0
10 : *
11 : * Unless required by applicable law or agreed to in writing, software
12 : * distributed under the License is distributed on an "AS IS" BASIS,
13 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 : * See the License for the specific language governing permissions and
15 : * limitations under the License.
16 : */
17 : #pragma once
18 :
19 : #include <crypto/CHIPCryptoPAL.h>
20 : #include <lib/core/CHIPCallback.h>
21 : #include <lib/core/CHIPError.h>
22 : #include <lib/core/CHIPVendorIdentifiers.hpp>
23 : #include <lib/support/ScopedBuffer.h>
24 : #include <lib/support/Span.h>
25 : #include <stdlib.h>
26 :
27 : namespace chip {
28 : namespace Credentials {
29 :
30 : enum class AttestationVerificationResult : uint16_t
31 : {
32 : kSuccess = 0,
33 :
34 : kPaaUntrusted = 100,
35 : kPaaNotFound = 101,
36 : kPaaExpired = 102,
37 : kPaaSignatureInvalid = 103,
38 : kPaaRevoked = 104,
39 : kPaaFormatInvalid = 105,
40 : kPaaArgumentInvalid = 106,
41 :
42 : kPaiExpired = 200,
43 : kPaiSignatureInvalid = 201,
44 : kPaiRevoked = 202,
45 : kPaiFormatInvalid = 203,
46 : kPaiArgumentInvalid = 204,
47 : kPaiVendorIdMismatch = 205,
48 : kPaiAuthorityNotFound = 206,
49 : kPaiMissing = 207,
50 : kPaiAndDacRevoked = 208,
51 :
52 : kDacExpired = 300,
53 : kDacSignatureInvalid = 301,
54 : kDacRevoked = 302,
55 : kDacFormatInvalid = 303,
56 : kDacArgumentInvalid = 304,
57 : kDacVendorIdMismatch = 305,
58 : kDacProductIdMismatch = 306,
59 : kDacAuthorityNotFound = 307,
60 :
61 : kFirmwareInformationMismatch = 400,
62 : kFirmwareInformationMissing = 401,
63 :
64 : kAttestationSignatureInvalid = 500,
65 : kAttestationElementsMalformed = 501,
66 : kAttestationNonceMismatch = 502,
67 : kAttestationSignatureInvalidFormat = 503,
68 :
69 : kCertificationDeclarationNoKeyId = 600,
70 : kCertificationDeclarationNoCertificateFound = 601,
71 : kCertificationDeclarationInvalidSignature = 602,
72 : kCertificationDeclarationInvalidFormat = 603,
73 : kCertificationDeclarationInvalidVendorId = 604,
74 : kCertificationDeclarationInvalidProductId = 605,
75 : kCertificationDeclarationInvalidPAA = 606,
76 :
77 : kNoMemory = 700,
78 :
79 : kInvalidArgument = 800,
80 :
81 : kInternalError = 900,
82 :
83 : kNotImplemented = 0xFFFFU,
84 :
85 : // TODO: Add more attestation verification errors
86 : };
87 :
88 : enum CertificateType : uint8_t
89 : {
90 : kUnknown = 0,
91 : kDAC = 1,
92 : kPAI = 2,
93 : };
94 :
95 : struct DeviceInfoForAttestation
96 : {
97 : // Vendor ID reported by device in Basic Information cluster
98 : uint16_t vendorId = VendorId::NotSpecified;
99 : // Product ID reported by device in Basic Information cluster
100 : uint16_t productId = 0;
101 : // Vendor ID from DAC
102 : uint16_t dacVendorId = VendorId::NotSpecified;
103 : // Product ID from DAC
104 : uint16_t dacProductId = 0;
105 : // Vendor ID from PAI cert
106 : uint16_t paiVendorId = VendorId::NotSpecified;
107 : // Product ID from PAI cert (0 if absent)
108 : uint16_t paiProductId = 0;
109 : // Vendor ID from PAA cert
110 : uint16_t paaVendorId = VendorId::NotSpecified;
111 : // Subject Key Identifier (SKID) from PAA cert
112 : uint8_t paaSKID[Crypto::kSubjectKeyIdentifierLength] = { 0 };
113 : };
114 :
115 : /**
116 : * @brief Helper utility to model a basic trust store usable for device attestation verifiers.
117 : *
118 : * API is synchronous. Real commissioner implementations may entirely
119 : * hide Product Attestation Authority cert lookup behind the DeviceAttestationVerifier and
120 : * never use this interface at all. It is provided as a utility to help build DeviceAttestationVerifier
121 : * implementations suitable for testing or examples.
122 : */
123 : class AttestationTrustStore
124 : {
125 : public:
126 3 : AttestationTrustStore() = default;
127 3 : virtual ~AttestationTrustStore() = default;
128 :
129 : // Not copyable
130 : AttestationTrustStore(const AttestationTrustStore &) = delete;
131 : AttestationTrustStore & operator=(const AttestationTrustStore &) = delete;
132 :
133 : /**
134 : * @brief Look-up a PAA cert by SKID
135 : *
136 : * The implementations of this interface must have access to a set of PAAs to trust.
137 : *
138 : * Interface is synchronous, and therefore this should not be used unless to expose a PAA
139 : * store that is both fully local and quick to access.
140 : *
141 : * @param[in] skid Buffer containing the subject key identifier (SKID) of the PAA to look-up
142 : * @param[in,out] outPaaDerBuffer Buffer to receive the contents of the PAA root cert, if found.
143 : * Size will be updated to match actual size.
144 : *
145 : * @returns CHIP_NO_ERROR on success, CHIP_INVALID_ARGUMENT if `skid` or `outPaaDerBuffer` arguments
146 : * are not usable, CHIP_BUFFER_TOO_SMALL if certificate doesn't fit in `outPaaDerBuffer`
147 : * span, CHIP_ERROR_CA_CERT_NOT_FOUND if no PAA found that matches `skid.
148 : *
149 : */
150 : virtual CHIP_ERROR GetProductAttestationAuthorityCert(const ByteSpan & skid, MutableByteSpan & outPaaDerBuffer) const = 0;
151 : };
152 :
153 : /**
154 : * @brief Helper utility to model obtaining verifying keys by Key ID
155 : *
156 : * API is synchronous. Real commissioner implementations may entirely
157 : * hide key lookup behind the DeviceAttestationVerifier and never use this interface at all.
158 : * It is provided as a utility to help build DeviceAttestationVerifier
159 : * implementations suitable for testing or examples.
160 : */
161 : class WellKnownKeysTrustStore
162 : {
163 : public:
164 2 : WellKnownKeysTrustStore() = default;
165 2 : virtual ~WellKnownKeysTrustStore() = default;
166 :
167 : // Not copyable
168 : WellKnownKeysTrustStore(const WellKnownKeysTrustStore &) = delete;
169 : WellKnownKeysTrustStore & operator=(const WellKnownKeysTrustStore &) = delete;
170 :
171 : /**
172 : * @brief Add a trusted key directly
173 : *
174 : * @param[in] kid - Key ID to use. Usually 20 bytes long, max 32 bytes.
175 : * @param[in] pubKey - Verifying public key to attach to the key ID.
176 : *
177 : * @return CHIP_NO_ERROR on success, CHIP_INVALID_ARGUMENT if `kid` or `pubKey` arguments
178 : * are not usable. CHIP_ERROR_NO_MEMORY if the trust store is full.
179 : */
180 : virtual CHIP_ERROR AddTrustedKey(const ByteSpan & kid, const Crypto::P256PublicKey & pubKey) = 0;
181 :
182 : /**
183 : * @brief Add a trusted key via a public certificate.
184 : *
185 : * The subject public key of the certificate will be used.
186 : * The subject key ID extensions of the certificate will be the `kid`.
187 : *
188 : * Verification of trust chaining is at the discretion of the implementation.
189 : *
190 : * @param[in] derCertBytes - Certificate containing the X.509 DER certificate with the key.
191 : *
192 : * @return CHIP_NO_ERROR on success, CHIP_INVALID_ARGUMENT if derCertBytes is improperly
193 : * formatted or not trusted. CHIP_ERROR_NO_MEMORY if the trust store is full.
194 : */
195 : virtual CHIP_ERROR AddTrustedKey(const ByteSpan & derCertBytes) = 0;
196 :
197 : /**
198 : * @brief Look-up a verifying key by Key ID
199 : *
200 : * Interface is synchronous.
201 : *
202 : * @param[in] kid Buffer containing the key identifier (KID) of the verifying key to look-up. Usually
203 : * a SHA-1-sized buffer (20 bytes).
204 : * @param[out] outPubKey Reference to where the verifying key found will be stored on CHIP_NO_ERROR
205 : *
206 : * @returns CHIP_NO_ERROR on success, CHIP_INVALID_ARGUMENT if `kid` or `pubKey` arguments
207 : * are not usable, CHIP_ERROR_KEY_NOT_FOUND if no key is found that matches `kid`.
208 : */
209 : virtual CHIP_ERROR LookupVerifyingKey(const ByteSpan & kid, Crypto::P256PublicKey & outPubKey) const = 0;
210 :
211 : /**
212 : * @brief Returns true if `kid` identifies a known test key.
213 : *
214 : * @param kid - Key ID to use. Usually 20 bytes long, max 32 bytes.
215 : * @return true if it's a test/development-only signing key identifier, false otherwise
216 : */
217 : virtual bool IsCdTestKey(const ByteSpan & kid) const = 0;
218 : };
219 :
220 : /**
221 : * @brief Basic AttestationTrustStore that holds all data within caller-owned memory.
222 : *
223 : * This is useful to wrap a fixed constant array of certificates into a trust store
224 : * implementation.
225 : */
226 :
227 : class ArrayAttestationTrustStore : public AttestationTrustStore
228 : {
229 : public:
230 3 : ArrayAttestationTrustStore(const ByteSpan * derCerts, size_t numCerts) : mDerCerts(derCerts), mNumCerts(numCerts) {}
231 :
232 99 : CHIP_ERROR GetProductAttestationAuthorityCert(const ByteSpan & skid, MutableByteSpan & outPaaDerBuffer) const override
233 : {
234 99 : VerifyOrReturnError(!skid.empty() && (skid.data() != nullptr), CHIP_ERROR_INVALID_ARGUMENT);
235 98 : VerifyOrReturnError(skid.size() == Crypto::kSubjectKeyIdentifierLength, CHIP_ERROR_INVALID_ARGUMENT);
236 :
237 : size_t paaIdx;
238 97 : ByteSpan candidate;
239 :
240 104 : for (paaIdx = 0; paaIdx < mNumCerts; ++paaIdx)
241 : {
242 102 : uint8_t skidBuf[Crypto::kSubjectKeyIdentifierLength] = { 0 };
243 102 : candidate = mDerCerts[paaIdx];
244 102 : MutableByteSpan candidateSkidSpan{ skidBuf };
245 197 : VerifyOrReturnError(CHIP_NO_ERROR == Crypto::ExtractSKIDFromX509Cert(candidate, candidateSkidSpan),
246 : CHIP_ERROR_INTERNAL);
247 :
248 102 : if (skid.data_equal(candidateSkidSpan))
249 : {
250 : // Found a match
251 95 : return CopySpanToMutableSpan(candidate, outPaaDerBuffer);
252 : }
253 : }
254 :
255 2 : return CHIP_ERROR_CA_CERT_NOT_FOUND;
256 : }
257 :
258 : protected:
259 : const ByteSpan * mDerCerts;
260 : const size_t mNumCerts;
261 : };
262 :
263 : // forward declaration
264 : class DeviceAttestationRevocationDelegate;
265 :
266 : class DeviceAttestationVerifier
267 : {
268 : public:
269 2 : DeviceAttestationVerifier() = default;
270 6 : virtual ~DeviceAttestationVerifier() = default;
271 :
272 : // Not copyable
273 : DeviceAttestationVerifier(const DeviceAttestationVerifier &) = delete;
274 : DeviceAttestationVerifier & operator=(const DeviceAttestationVerifier &) = delete;
275 :
276 : struct AttestationInfo
277 : {
278 0 : AttestationInfo(const ByteSpan & attestationElements, const ByteSpan & attestationChallenge,
279 : const ByteSpan & attestationSignature, const ByteSpan & paiDer, const ByteSpan & dacDer,
280 0 : const ByteSpan & attestationNonce, VendorId remoteVendorId, uint16_t remoteProductId) :
281 0 : attestationElementsBuffer(attestationElements),
282 0 : attestationChallengeBuffer(attestationChallenge), attestationSignatureBuffer(attestationSignature),
283 0 : paiDerBuffer(paiDer), dacDerBuffer(dacDer), attestationNonceBuffer(attestationNonce), vendorId(remoteVendorId),
284 0 : productId(remoteProductId)
285 0 : {}
286 : const ByteSpan
287 : attestationElementsBuffer; // Buffer containing attestation elements portion of Attestation Response (raw TLV)
288 : const ByteSpan attestationChallengeBuffer; // Buffer containing the attestation challenge from the secure session
289 : const ByteSpan attestationSignatureBuffer; // Buffer the signature portion of Attestation Response
290 : const ByteSpan paiDerBuffer; // Buffer containing the PAI certificate from device in DER format.
291 : const ByteSpan dacDerBuffer; // Buffer containing the DAC certificate from device in DER format.
292 : const ByteSpan attestationNonceBuffer; // Buffer containing attestation nonce.
293 : VendorId vendorId;
294 : uint16_t productId;
295 : };
296 :
297 : // Copies the bytes passed to it, and holds the PAI, DAC, and CD for additional verification step
298 : class AttestationDeviceInfo
299 : {
300 : public:
301 : AttestationDeviceInfo(const AttestationInfo & attestationInfo);
302 :
303 0 : ~AttestationDeviceInfo() = default;
304 :
305 : // Returns buffer containing the PAI certificate from device in DER format.
306 : const ByteSpan paiDerBuffer() const { return ByteSpan(mPaiDerBuffer.Get(), mPaiDerBuffer.AllocatedSize()); }
307 :
308 : // Returns buffer containing the DAC certificate from device in DER format.
309 : const ByteSpan dacDerBuffer() const { return ByteSpan(mDacDerBuffer.Get(), mDacDerBuffer.AllocatedSize()); }
310 :
311 : // Returns optional buffer containing the certificate declaration from device.
312 : const Optional<ByteSpan> cdBuffer() const
313 : {
314 : if (mCdBuffer.Get())
315 : {
316 : return MakeOptional(ByteSpan(mDacDerBuffer.Get(), mDacDerBuffer.AllocatedSize()));
317 : }
318 : else
319 : {
320 : return Optional<ByteSpan>();
321 : }
322 : }
323 :
324 : uint16_t BasicInformationVendorId() const { return mBasicInformationVendorId; }
325 :
326 : uint16_t BasicInformationProductId() const { return mBasicInformationProductId; }
327 :
328 : private:
329 : Platform::ScopedMemoryBufferWithSize<uint8_t> mPaiDerBuffer;
330 : Platform::ScopedMemoryBufferWithSize<uint8_t> mDacDerBuffer;
331 : Platform::ScopedMemoryBufferWithSize<uint8_t> mCdBuffer;
332 : uint16_t mBasicInformationVendorId;
333 : uint16_t mBasicInformationProductId;
334 : };
335 :
336 : typedef void (*OnAttestationInformationVerification)(void * context, const AttestationInfo & info,
337 : AttestationVerificationResult result);
338 :
339 : /**
340 : * @brief Verify an attestation information payload against a DAC/PAI chain.
341 : *
342 : * @param[in] info All of the information required to verify the attestation.
343 : * @param[in] onCompletion Callback handler to provide Attestation Information Verification result to the caller of
344 : * VerifyAttestationInformation()
345 : */
346 : virtual void VerifyAttestationInformation(const AttestationInfo & info,
347 : Callback::Callback<OnAttestationInformationVerification> * onCompletion) = 0;
348 :
349 : /**
350 : * @brief Verify a CMS Signed Data signature against the CSA certificate of Subject Key Identifier that matches
351 : * the subjectKeyIdentifier field of cmsEnvelopeBuffer.
352 : *
353 : * @param[in] cmsEnvelopeBuffer A ByteSpan with a CMS signed message.
354 : * @param[out] certDeclBuffer A ByteSpan to hold the CD content extracted from the CMS signed message.
355 : *
356 : * @returns AttestationVerificationResult::kSuccess on success or another specific
357 : * value from AttestationVerificationResult enum on failure.
358 : */
359 : virtual AttestationVerificationResult ValidateCertificationDeclarationSignature(const ByteSpan & cmsEnvelopeBuffer,
360 : ByteSpan & certDeclBuffer) = 0;
361 :
362 : /**
363 : * @brief Verify a CMS Signed Data Payload against the Basic Information Cluster and DAC/PAI's Vendor and Product IDs
364 : *
365 : * @param[in] certDeclBuffer A ByteSpan with the Certification Declaration content.
366 : * @param[in] firmwareInfo A ByteSpan with the Firmware Information content.
367 : * @param[in] deviceInfo The device information
368 : *
369 : * @returns AttestationVerificationResult::kSuccess on success or another specific
370 : * value from AttestationVerificationResult enum on failure.
371 : */
372 : virtual AttestationVerificationResult ValidateCertificateDeclarationPayload(const ByteSpan & certDeclBuffer,
373 : const ByteSpan & firmwareInfo,
374 : const DeviceInfoForAttestation & deviceInfo) = 0;
375 :
376 : // TODO: Validate Firmware Information
377 :
378 : /**
379 : * @brief Verify an operational certificate signing request payload against the DAC's public key.
380 : *
381 : * @param[in] nocsrElementsBuffer Buffer containing CSR elements as per specifications section 11.22.5.6. NOCSR Elements.
382 : * @param[in] attestationChallengeBuffer Buffer containing the attestation challenge from the secure session
383 : * @param[in] attestationSignatureBuffer Buffer containing the signature portion of CSR Response
384 : * @param[in] dacPublicKey Public Key from the DAC's certificate received from device.
385 : * @param[in] csrNonce Buffer containing CSR nonce.
386 : */
387 : virtual CHIP_ERROR VerifyNodeOperationalCSRInformation(const ByteSpan & nocsrElementsBuffer,
388 : const ByteSpan & attestationChallengeBuffer,
389 : const ByteSpan & attestationSignatureBuffer,
390 : const Crypto::P256PublicKey & dacPublicKey,
391 : const ByteSpan & csrNonce) = 0;
392 :
393 : /**
394 : * @brief Verify whether or not the given DAC chain is revoked.
395 : *
396 : * @param[in] info All of the information required to check for revoked DAC chain.
397 : * @param[in] onCompletion Callback handler to provide Attestation Information Verification result to the caller of
398 : * CheckForRevokedDACChain()
399 : */
400 : virtual void CheckForRevokedDACChain(const AttestationInfo & info,
401 : Callback::Callback<OnAttestationInformationVerification> * onCompletion) = 0;
402 :
403 : /**
404 : * @brief Get the trust store used for the attestation verifier.
405 : *
406 : * Returns nullptr if not supported. Be careful not to hold-on to the trust store
407 : * for too long. It is only expected to have same lifetime as the DeviceAttestationVerifier.
408 : *
409 : * @return a pointer to the trust store or nullptr if none is directly accessible.
410 : */
411 0 : virtual WellKnownKeysTrustStore * GetCertificationDeclarationTrustStore() { return nullptr; }
412 :
413 : void EnableCdTestKeySupport(bool enabled) { mEnableCdTestKeySupport = enabled; }
414 84 : bool IsCdTestKeySupported() const { return mEnableCdTestKeySupport; }
415 :
416 : /**
417 : * @brief Try to set the revocation delegate.
418 : *
419 : * @param[in] revocationDelegate The revocation delegate to set.
420 : *
421 : * @return CHIP_NO_ERROR on success, CHIP_ERROR_NOT_IMPLEMENTED if the revocation delegate is not supported.
422 : */
423 0 : virtual CHIP_ERROR SetRevocationDelegate(DeviceAttestationRevocationDelegate * revocationDelegate)
424 : {
425 0 : return CHIP_ERROR_NOT_IMPLEMENTED;
426 : }
427 :
428 : protected:
429 : CHIP_ERROR ValidateAttestationSignature(const Crypto::P256PublicKey & pubkey, const ByteSpan & attestationElements,
430 : const ByteSpan & attestationChallenge, const Crypto::P256ECDSASignature & signature);
431 :
432 : // Default to support the "development" test key for legacy purposes (since the DefaultDACVerifier)
433 : // always supported development keys.
434 : bool mEnableCdTestKeySupport = true;
435 : };
436 :
437 : /**
438 : * @brief Interface for checking the device attestation revocation status
439 : *
440 : */
441 : class DeviceAttestationRevocationDelegate
442 : {
443 : public:
444 : DeviceAttestationRevocationDelegate() = default;
445 0 : virtual ~DeviceAttestationRevocationDelegate() = default;
446 :
447 : /**
448 : * @brief Verify whether or not the given DAC chain is revoked.
449 : *
450 : * @param[in] info All of the information required to check for revoked DAC chain.
451 : * @param[in] onCompletion Callback handler to provide Attestation Information Verification result to the caller of
452 : * CheckForRevokedDACChain().
453 : */
454 : virtual void
455 : CheckForRevokedDACChain(const DeviceAttestationVerifier::AttestationInfo & info,
456 : Callback::Callback<DeviceAttestationVerifier::OnAttestationInformationVerification> * onCompletion) = 0;
457 : };
458 :
459 : /**
460 : * Instance getter for the global DeviceAttestationVerifier.
461 : *
462 : * Callers have to externally synchronize usage of this function.
463 : *
464 : * @return The global device attestation verifier. Assume never null.
465 : */
466 : DeviceAttestationVerifier * GetDeviceAttestationVerifier();
467 :
468 : /**
469 : * Instance setter for the global DeviceAttestationVerifier.
470 : *
471 : * Callers have to externally synchronize usage of this function.
472 : *
473 : * If the `verifier` is nullptr, no change is done.
474 : *
475 : * @param[in] verifier the DeviceAttestationVerifier to start returning with the getter
476 : */
477 : void SetDeviceAttestationVerifier(DeviceAttestationVerifier * verifier);
478 :
479 : } // namespace Credentials
480 : } // namespace chip
|
