Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2022 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 <lib/core/CHIPError.h>
20 : #include <lib/support/Span.h>
21 :
22 : namespace chip {
23 :
24 : // The largest value of the 12-bit Payload discriminator
25 : inline constexpr uint16_t kMaxDiscriminatorValue = 0xFFF;
26 :
27 : inline constexpr uint32_t kMinSetupPasscode = 1;
28 : inline constexpr uint32_t kMaxSetupPasscode = 0x5F5E0FE;
29 :
30 : namespace DeviceLayer {
31 :
32 : class CommissionableDataProvider
33 : {
34 : public:
35 2 : CommissionableDataProvider() = default;
36 2 : virtual ~CommissionableDataProvider() = default;
37 :
38 : // Not copyable
39 : CommissionableDataProvider(const CommissionableDataProvider &) = delete;
40 : CommissionableDataProvider & operator=(const CommissionableDataProvider &) = delete;
41 :
42 : /**
43 : * @brief Obtain the default setup discriminator for the device used for commissionable advertising
44 : *
45 : * @param[in,out] setupDiscriminator Reference to location where discriminator will be copied
46 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
47 : * if access fails.
48 : */
49 : virtual CHIP_ERROR GetSetupDiscriminator(uint16_t & setupDiscriminator) = 0;
50 :
51 : /**
52 : * @brief Set the setup discriminator *if supported*.
53 : *
54 : * This API is optional to support, but present to support integration with some examples
55 : * which use a common test PAKE verifier but want to disambiguate multiple instances at
56 : * runtime. This is generally not applicable to production usecases of commissionable
57 : * devices with nominal random discriminator. There are no guarantees that this API,
58 : * in general, will persist the discriminator across restarts.
59 : *
60 : * If not supported, return CHIP_ERROR_NOT_IMPLEMENTED.
61 : *
62 : * @param[in] setupDiscriminator Setup discriminator to set.
63 : * @returns CHIP_NO_ERROR on success, CHIP_ERROR_INVALID_ARGUMENT if discriminator is out of range,
64 : * CHIP_ERROR_NOT_IMPLEMENTED if not implemented, or another CHIP_ERROR from the underlying
65 : * implementation if storage fails.
66 : */
67 : virtual CHIP_ERROR SetSetupDiscriminator(uint16_t setupDiscriminator) = 0;
68 :
69 : /**
70 : * @brief Obtain the default PAKE verifier's PBKDF2 iteration count
71 : *
72 : * @param[in,out] iterationCount Reference to location where the iteration count will be stored
73 : * @returns CHIP_NO_ERROR on success, or another CHIP_ERROR from the underlying implementation
74 : * if access fails.
75 : */
76 : virtual CHIP_ERROR GetSpake2pIterationCount(uint32_t & iterationCount) = 0;
77 :
78 : /**
79 : * @brief Obtain the default PAKE verifier's PBKDF2 salt in the provided `saltBuf`
80 : *
81 : * The `saltBuf` must be large enough to contain the salt. It will be resized on success to
82 : * reflect the actual size of the salt.
83 : *
84 : * @param[in,out] saltBuf Reference to buffer where the salt value will be copied.
85 : *
86 : * @returns CHIP_NO_ERROR on success, CHIP_ERROR_BUFFER_TOO_SMALL if saltBuf was too small, or another
87 : * CHIP_ERROR from the underlying implementation if access fails.
88 : */
89 : virtual CHIP_ERROR GetSpake2pSalt(MutableByteSpan & saltBuf) = 0;
90 :
91 : /**
92 : * @brief Obtain the default PAKE verifier in the provided `verifierBuf`
93 : *
94 : * The `verifierBuf` must be large enough to contain the verifier. It will be resized on
95 : * success to reflect the actual size of the verifier and match the value in verifierLen.
96 : *
97 : * @param[in,out] verifierBuf Reference to buffer where the verifier value will be copied.
98 : * @param[out] outVerifierLen Reference to location where the length of the verifier will be stored,
99 : * including if the buffer provided is too small. This value is valid
100 : * if the return value is either CHIP_NO_ERROR or CHIP_ERROR_BUFFER_TOO_SMALL.
101 : *
102 : * @returns CHIP_NO_ERROR on success, CHIP_ERROR_BUFFER_TOO_SMALL if verifierBuf was too small, or another
103 : * CHIP_ERROR from the underlying implementation if access fails.
104 : */
105 : virtual CHIP_ERROR GetSpake2pVerifier(MutableByteSpan & verifierBuf, size_t & outVerifierLen) = 0;
106 :
107 : /**
108 : * @brief Obtain the default setup passcode for the device *if supported*
109 : *
110 : * This API is optional to support, but present to support integration with some examples
111 : * which allow runtime setting of a passcode to generate onboarding payloads and QR codes
112 : * as well as PAKE verifier. This is generally not applicable to production usecases of
113 : * commissionable devices with nominal random verifier/passcode and with usage of verifier
114 : * rather than passcode (which safeguards the passcode from ever leaking). There are no
115 : * guarantees that this API, in general, will persist the passcode across restarts.
116 : *
117 : * If not supported, return CHIP_ERROR_NOT_IMPLEMENTED.
118 : *
119 : * @param[in,out] setupPasscode Reference to location where passcode will be copied
120 : * @returns CHIP_NO_ERROR on success, CHIP_ERROR_NOT_IMPLEMENTED if not implemented
121 : * or not available, or another CHIP_ERROR from the underlying implementation
122 : * if access fails.
123 : */
124 : virtual CHIP_ERROR GetSetupPasscode(uint32_t & setupPasscode) = 0;
125 :
126 : /**
127 : * @brief Set the setup discriminator *if supported*.
128 : *
129 : * This API is optional to support, but present to support integration with some examples
130 : * which allow runtime setting of a passcode to generate onboarding payloads and QR codes
131 : * as well as PAKE verifier. This is generally not applicable to production usecases of
132 : * commissionable devices with nominal random verifier/passcode and with usage of verifier
133 : * rather than passcode (which safeguards the passcode from ever leaking). There are no
134 : * guarantees that this API, in general, will persist the passcode across restarts.
135 : *
136 : * If not supported, return CHIP_ERROR_NOT_IMPLEMENTED.
137 : *
138 : * @param[in] setupPasscode Setup passcode to set
139 : * @returns CHIP_NO_ERROR on success, CHIP_ERROR_INVALID_ARGUMENT if discriminator is invalid
140 : * according to spec (out of range or forbidden value), CHIP_ERROR_NOT_IMPLEMENTED
141 : * if not implemented, or another CHIP_ERROR from the underlying implementation if
142 : * storage fails.
143 : */
144 : virtual CHIP_ERROR SetSetupPasscode(uint32_t setupPasscode) = 0;
145 : };
146 :
147 : /**
148 : * Instance getter for the global CommissionableDataProvider.
149 : *
150 : * Callers have to externally synchronize usage of this function.
151 : *
152 : * @return The global device attestation credentials provider. Assume never null.
153 : */
154 : CommissionableDataProvider * GetCommissionableDataProvider();
155 :
156 : /**
157 : * Instance setter for the global CommissionableDataProvider.
158 : *
159 : * Callers have to externally synchronize usage of this function.
160 : *
161 : * If the `provider` is nullptr, no change is done.
162 : *
163 : * @param[in] provider the CommissionableDataProvider to start returning with the getter
164 : */
165 : void SetCommissionableDataProvider(CommissionableDataProvider * provider);
166 :
167 : } // namespace DeviceLayer
168 : } // namespace chip
|
