1 /*
2  * Copyright 2018-2021 NXP
3  * All rights reserved.
4  *
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 
9 #ifndef _PUF_H_
10 #define _PUF_H_
11 
12 #include <stddef.h>
13 #include <stdint.h>
14 
15 #include "fsl_common.h"
16 
17 /*******************************************************************************
18  * Definitions
19  *******************************************************************************/
20 
21 /*!
22  * @addtogroup puf_driver
23  * @{
24  */
25 /*! @name Driver version */
26 /*@{*/
27 /*! @brief PUF driver version. Version 2.1.6.
28  *
29  * Current version: 2.1.6
30  *
31  * Change log:
32  * - 2.0.0
33  *   - Initial version.
34  * - 2.0.1
35  *   - Fixed puf_wait_usec function optimization issue.
36  * - 2.0.2
37  *   - Add PUF configuration structure and support for PUF SRAM controller.
38  *     Remove magic constants.
39  * - 2.0.3
40  *   - Fix MISRA C-2012 issue.
41  * - 2.1.0
42  *   - Align driver with PUF SRAM controller registers on LPCXpresso55s16.
43  *   - Update initizalition logic .
44  * - 2.1.1
45  *   - Fix ARMGCC build warning .
46  * - 2.1.2
47  *   - Update: Add automatic big to little endian swap for user
48  *     (pre-shared) keys destinated to secret hardware bus (PUF key index 0).
49  * - 2.1.3
50  *   - Fix MISRA C-2012 issue.
51  * - 2.1.4
52  *   - Replace register uint32_t ticksCount with volatile uint32_t ticksCount in puf_wait_usec() to prevent optimization
53  * out delay loop.
54  * - 2.1.5
55  *   - Use common SDK delay in puf_wait_usec()
56  * - 2.1.6
57  *   - Changed wait time in PUF_Init(), when initialization fails it will try PUF_Powercycle() with shorter time. If
58  * this shorter time will also fail, initialization will be tried with worst case time as before.
59  */
60 #define FSL_PUF_DRIVER_VERSION (MAKE_VERSION(2, 1, 6))
61 /*@}*/
62 
63 typedef enum _puf_key_index_register
64 {
65     kPUF_KeyIndex_00 = 0x00U,
66     kPUF_KeyIndex_01 = 0x01U,
67     kPUF_KeyIndex_02 = 0x02U,
68     kPUF_KeyIndex_03 = 0x03U,
69     kPUF_KeyIndex_04 = 0x04U,
70     kPUF_KeyIndex_05 = 0x05U,
71     kPUF_KeyIndex_06 = 0x06U,
72     kPUF_KeyIndex_07 = 0x07U,
73     kPUF_KeyIndex_08 = 0x08U,
74     kPUF_KeyIndex_09 = 0x09U,
75     kPUF_KeyIndex_10 = 0x0AU,
76     kPUF_KeyIndex_11 = 0x0BU,
77     kPUF_KeyIndex_12 = 0x0CU,
78     kPUF_KeyIndex_13 = 0x0DU,
79     kPUF_KeyIndex_14 = 0x0EU,
80     kPUF_KeyIndex_15 = 0x0FU,
81 } puf_key_index_register_t;
82 
83 typedef enum _puf_min_max
84 {
85     kPUF_KeySizeMin  = 8u,
86     kPUF_KeySizeMax  = 512u,
87     kPUF_KeyIndexMax = kPUF_KeyIndex_15,
88 } puf_min_max_t;
89 
90 /*! @brief PUF key slot. */
91 typedef enum _puf_key_slot
92 {
93     kPUF_KeySlot0 = 0U, /*!< PUF key slot 0 */
94     kPUF_KeySlot1 = 1U, /*!< PUF key slot 1 */
95 #if defined(PUF_KEYMASK_COUNT) && (PUF_KEYMASK_COUNT > 2)
96     kPUF_KeySlot2 = 2U, /*!< PUF key slot 2 */
97     kPUF_KeySlot3 = 3U, /*!< PUF key slot 3 */
98 #endif
99 } puf_key_slot_t;
100 
101 typedef struct
102 {
103     uint32_t dischargeTimeMsec;
104     uint32_t coreClockFrequencyHz;
105 #if defined(FSL_FEATURE_PUF_HAS_SRAM_CTRL) && (FSL_FEATURE_PUF_HAS_SRAM_CTRL > 0)
106     /* LPCXpresso55s16 */
107     PUF_SRAM_CTRL_Type *puf_sram_base;
108     uint8_t CKGATING;
109 #endif /* FSL_FEATURE_PUF_HAS_SRAM_CTRL */
110 } puf_config_t;
111 /*! @brief Get Key Code size in bytes from key size in bytes at compile time. */
112 #define PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(x)    ((160u + (((((x) << 3) + 255u) >> 8) << 8)) >> 3)
113 #define PUF_MIN_KEY_CODE_SIZE                    PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(8UL)
114 #define PUF_ACTIVATION_CODE_SIZE                 1192U
115 #define KEYSTORE_PUF_DISCHARGE_TIME_FIRST_TRY_MS 50
116 #define KEYSTORE_PUF_DISCHARGE_TIME_MAX_MS       400
117 
118 /*! PUF status return codes. */
119 enum
120 {
121     kStatus_EnrollNotAllowed = MAKE_STATUS(kStatusGroup_PUF, 1),
122     kStatus_StartNotAllowed  = MAKE_STATUS(kStatusGroup_PUF, 2)
123 };
124 
125 /*! @} */
126 /*******************************************************************************
127  * API
128  *******************************************************************************/
129 
130 #if defined(__cplusplus)
131 extern "C" {
132 #endif /* __cplusplus */
133 
134 /*!
135  * @brief Sets the default configuration of PUF
136  *
137  * This function initialize PUF config structure to default values.
138  *
139  * @param conf PUF configuration structure
140  */
141 void PUF_GetDefaultConfig(puf_config_t *conf);
142 
143 /*!
144  * @brief Initialize PUF
145  *
146  * This function enables power to PUF block and waits until the block initializes.
147  *
148  * @param base PUF peripheral base address
149  * @param conf PUF configuration structure
150  * @return Status of the init operation
151  */
152 status_t PUF_Init(PUF_Type *base, puf_config_t *conf);
153 
154 /*!
155  * @brief Denitialize PUF
156  *
157  * This function disables power to PUF SRAM and peripheral clock.
158  *
159  * @param base PUF peripheral base address
160  * @param conf PUF configuration structure
161  */
162 void PUF_Deinit(PUF_Type *base, puf_config_t *conf);
163 
164 /*!
165  * @brief Enroll PUF
166  *
167  * This function derives a digital fingerprint, generates the corresponding Activation Code (AC)
168  * and returns it to be stored in an NVM or a file. This step needs to be
169  * performed only once for each device. This function may be permanently disallowed by a fuse.
170  *
171  * @param base PUF peripheral base address
172  * @param[out] activationCode Word aligned address of the resulting activation code.
173  * @param activationCodeSize Size of the activationCode buffer in bytes. Shall be 1192 bytes.
174  * @return Status of enroll operation.
175  */
176 status_t PUF_Enroll(PUF_Type *base, uint8_t *activationCode, size_t activationCodeSize);
177 
178 /*!
179  * @brief Start PUF
180  *
181  * The Activation Code generated during the Enroll operation is used to
182  * reconstruct the digital fingerprint. This needs to be done after every power-up
183  * and reset.
184  *
185  * @param base PUF peripheral base address
186  * @param activationCode Word aligned address of the input activation code.
187  * @param activationCodeSize Size of the activationCode buffer in bytes. Shall be 1192 bytes.
188  * @return Status of start operation.
189  */
190 status_t PUF_Start(PUF_Type *base, const uint8_t *activationCode, size_t activationCodeSize);
191 
192 /*!
193  * @brief Set intrinsic key
194  *
195  * The digital fingerprint generated during the Enroll/Start
196  * operations is used to generate a Key Code (KC) that defines a unique intrinsic
197  * key. This KC is returned to be stored in an NVM or a file. This operation
198  * needs to be done only once for each intrinsic key.
199  * Each time a Set Intrinsic Key operation is executed a new unique key is
200  * generated.
201  *
202  * @param base PUF peripheral base address
203  * @param keyIndex PUF key index register
204  * @param keySize Size of the intrinsic key to generate in bytes.
205  * @param[out] keyCode Word aligned address of the resulting key code.
206  * @param keyCodeSize Size of the keyCode buffer in bytes. Shall be PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(keySize).
207  * @return Status of set intrinsic key operation.
208  */
209 status_t PUF_SetIntrinsicKey(
210     PUF_Type *base, puf_key_index_register_t keyIndex, size_t keySize, uint8_t *keyCode, size_t keyCodeSize);
211 
212 /*!
213  * @brief Set user key
214  *
215  * The digital fingerprint generated during the Enroll/Start
216  * operations and a user key (UK) provided as input are used to
217  * generate a Key Code (KC). This KC is sent returned to be stored
218  * in an NVM or a file. This operation needs to be done only once for each user key.
219  *
220  * @param base PUF peripheral base address
221  * @param keyIndex PUF key index register
222  * @param userKey Word aligned address of input user key.
223  * @param userKeySize Size of the input user key in bytes.
224  * @param[out] keyCode Word aligned address of the resulting key code.
225  * @param keyCodeSize Size of the keyCode buffer in bytes. Shall be PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(userKeySize).
226  * @return Status of set user key operation.
227  */
228 status_t PUF_SetUserKey(PUF_Type *base,
229                         puf_key_index_register_t keyIndex,
230                         const uint8_t *userKey,
231                         size_t userKeySize,
232                         uint8_t *keyCode,
233                         size_t keyCodeSize);
234 
235 /*!
236  * @brief Reconstruct key from a key code
237  *
238  * The digital fingerprint generated during the Start operation and the KC
239  * generated during a Set Key operation (Set intrinsic key or Set user key) are used to retrieve a stored key. This
240  * operation needs to be done every time a key is needed.
241  * This function accepts only Key Codes created for PUF index registers kPUF_KeyIndex_01 to kPUF_KeyIndex_15.
242  *
243  * @param base PUF peripheral base address
244  * @param keyCode Word aligned address of the input key code.
245  * @param keyCodeSize Size of the keyCode buffer in bytes. Shall be PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(keySize).
246  * @param[out] key Word aligned address of output key.
247  * @param keySize Size of the output key in bytes.
248  * @return Status of get key operation.
249  */
250 status_t PUF_GetKey(PUF_Type *base, const uint8_t *keyCode, size_t keyCodeSize, uint8_t *key, size_t keySize);
251 
252 /*!
253  * @brief Reconstruct hw bus key from a key code
254  *
255  * The digital fingerprint generated during the Start operation and the KC
256  * generated during a Set Key operation (Set intrinsic key or Set user key) are used to retrieve a stored key. This
257  * operation needs to be done every time a key is needed.
258  * This function accepts only Key Codes created for PUF index register kPUF_KeyIndex_00.
259  * Such a key is output directly to a dedicated hardware bus. The reconstructed key is not exposed to system memory.
260  *
261  * @param base PUF peripheral base address
262  * @param keyCode Word aligned address of the input key code.
263  * @param keyCodeSize Size of the keyCode buffer in bytes. Shall be PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(keySize).
264  * @param keySlot key slot to output on hw bus. Parameter is ignored on devices with less than two key slots.
265  * @param keyMask key masking value. Shall be random for each POR/reset. Value does not have to be cryptographicaly
266  * secure.
267  * @return Status of get key operation.
268  */
269 status_t PUF_GetHwKey(
270     PUF_Type *base, const uint8_t *keyCode, size_t keyCodeSize, puf_key_slot_t keySlot, uint32_t keyMask);
271 
272 /*!
273  * @brief Zeroize PUF
274  *
275  * This function clears all PUF internal logic and puts the PUF to error state.
276  *
277  * @param base PUF peripheral base address
278  * @return Status of the zeroize operation.
279  */
280 status_t PUF_Zeroize(PUF_Type *base);
281 
282 /*!
283  * @brief Checks if Get Key operation is allowed.
284  *
285  * This function returns true if get key operation is allowed.
286  *
287  * @param base PUF peripheral base address
288  * @return true if get key operation is allowed
289  */
290 bool PUF_IsGetKeyAllowed(PUF_Type *base);
291 
292 #if defined(PUF_CFG_BLOCKKEYOUTPUT_MASK) && PUF_CFG_BLOCKKEYOUTPUT_MASK
PUF_BlockSetKey(PUF_Type * base)293 static inline void PUF_BlockSetKey(PUF_Type *base)
294 {
295     base->CFG |= PUF_CFG_BLOCKKEYOUTPUT_MASK; /* block set key */
296 }
297 #endif /* PUF_CFG_BLOCKKEYOUTPUT_MASK */
298 
299 #if defined(PUF_CFG_PUF_BLOCK_SET_KEY_MASK) && PUF_CFG_PUF_BLOCK_SET_KEY_MASK
PUF_BlockSetKey(PUF_Type * base)300 static inline void PUF_BlockSetKey(PUF_Type *base)
301 {
302     base->CFG |= PUF_CFG_PUF_BLOCK_SET_KEY_MASK; /* block set key */
303 }
304 #endif /* PUF_CFG_PUF_BLOCK_SET_KEY_MASK */
305 
306 #if defined(PUF_CFG_BLOCKENROLL_SETKEY_MASK) && PUF_CFG_BLOCKENROLL_SETKEY_MASK
PUF_BlockEnroll(PUF_Type * base)307 static inline void PUF_BlockEnroll(PUF_Type *base)
308 {
309     base->CFG |= PUF_CFG_BLOCKENROLL_SETKEY_MASK; /* block enroll */
310 }
311 #endif /* PUF_CFG_BLOCKENROLL_SETKEY_MASK */
312 
313 #if defined(PUF_CFG_PUF_BLOCK_ENROLL_MASK) && PUF_CFG_PUF_BLOCK_ENROLL_MASK
PUF_BlockEnroll(PUF_Type * base)314 static inline void PUF_BlockEnroll(PUF_Type *base)
315 {
316     base->CFG |= PUF_CFG_PUF_BLOCK_ENROLL_MASK; /* block enroll */
317 }
318 #endif /* PUF_CFG_PUF_BLOCK_ENROLL_MASK */
319 
320 /*!
321  * @brief Powercycle PUF
322  *
323  * This function make powercycle.
324  *
325  * @param base PUF peripheral base address
326  * @param conf PUF configuration structure
327  * @return Status of the powercycle operation.
328  */
329 status_t PUF_PowerCycle(PUF_Type *base, puf_config_t *conf);
330 
331 #if defined(__cplusplus)
332 }
333 #endif /* __cplusplus */
334 
335 #endif /* _PUF_H_ */
336