1 /*
2  * Copyright 2018-2021 NXP
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 #ifndef FSL_SSS_MGMT_H
8 #define FSL_SSS_MGMT_H
9 
10 #if !defined(SSS_CONFIG_FILE)
11 #include "fsl_sss_config.h"
12 #else
13 #include SSS_CONFIG_FILE
14 #endif
15 
16 #include "fsl_sss_api.h"
17 #include "fsl_sss_sscp.h"
18 
19 typedef struct
20 {
21     sss_sscp_session_t *session;
22     uint32_t clockFrequency;
23     uint32_t ctx;
24 } sss_mgmt_t;
25 
26 /*******************************************************************************
27  * API
28  ******************************************************************************/
29 #if defined(__cplusplus)
30 extern "C" {
31 #endif
32 
33 /*!
34  * @addtogroup sss_management
35  * @{
36  */
37 
38 /*! @brief Mgmt context init.
39  *  The function initializes mgmt context with initial values.
40  *
41  * @param context Pointer to mgmt crypto context.
42  * @param session Associate SSS session with mgmt context.
43  *
44  * @returns Status of the operation
45  * @retval kStatus_SSS_Success The operation has completed successfully.
46  * @retval kStatus_SSS_Fail The operation has failed.
47  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
48  */
49 sss_status_t sss_mgmt_context_init(sss_mgmt_t *context, sss_sscp_session_t *session);
50 
51 /*! @brief Get property
52  *  The function provides get property service
53  *
54  * @param context Pointer to mgmt crypto context.
55  * @param propertyId Id of the property to read
56  * @param destData Address of the destination data
57  * @param dataLen Input size of the destData buffer, output actual no of bytes written to destData
58  *
59  * @returns Status of the operation
60  * @retval kStatus_SSS_Success The operation has completed successfully.
61  * @retval kStatus_SSS_Fail The operation has failed.
62  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
63  */
64 sss_status_t sss_mgmt_get_property(sss_mgmt_t *context, uint32_t propertyId, uint8_t *destData, size_t *dataLen);
65 
66 /*! @brief Set property
67  *  The function provides set property service
68  *
69  * @param context Pointer to mgmt crypto context.
70  * @param propertyId Id of the property to write
71  * @param srcData Address of the source data
72  * @param dataLen Input size of the srcData buffer
73  *
74  * @returns Status of the operation
75  * @retval kStatus_SSS_Success The operation has completed successfully.
76  * @retval kStatus_SSS_Fail The operation has failed.
77  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
78  */
79 sss_status_t sss_mgmt_set_property(sss_mgmt_t *context, uint32_t propertyId, const uint8_t *srcData, size_t dataLen);
80 
81 /*! @brief Read fuse
82  *  The function provides read fuse shadow register read service
83  *
84  * @param context Pointer to mgmt crypto context.
85  * @param shadowRegisterId Id of the shadow register to read
86  * @param destData Destination address of the read value
87  *
88  * @returns Status of the operation
89  * @retval kStatus_SSS_Success The operation has completed successfully.
90  * @retval kStatus_SSS_Fail The operation has failed.
91  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
92  */
93 sss_status_t sss_mgmt_fuse_shadow_register_read(sss_mgmt_t *context, uint32_t shadowRegisterId, uint32_t *destData);
94 
95 /*! @brief Read fuse
96  *  The function provides read fuse service
97  *
98  * @param context Pointer to mgmt crypto context.
99  * @param fuseId Id of the fuse to read
100  * @param destData Destination address of the read value
101  * @param destDataLen Input length of the destData buffer in bytes, actual number of output bytes written to destData
102  * @param options Address of the implementation specific data buffer
103  * @param optionsLen Input length of the options buffer in bytes, actual number of output bytes written to options
104  *
105  * @returns Status of the operation
106  * @retval kStatus_SSS_Success The operation has completed successfully.
107  * @retval kStatus_SSS_Fail The operation has failed.
108  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
109  */
110 sss_status_t sss_mgmt_fuse_read(sss_mgmt_t *context,
111                                 uint32_t fuseId,
112                                 uint32_t *destData,
113                                 size_t *destDataLen,
114                                 uintptr_t options,
115                                 size_t *optionsLen);
116 
117 /*! @brief Program fuse
118  *  The function provides program fuse service
119  *
120  * @param context Pointer to mgmt crypto context.
121  * @param fuseId Id of the fuse to write
122  * @param srcData Fuse write value
123  * @param srcDataLen Input length of the srcData buffer in bytes, actual number of bytes written to OTP
124  * @param options Address of the implementation specific data buffer
125  * @param optionsLen Input length of the options buffer in bytes, actual number of output bytes written to options
126  *
127  * @returns Status of the operation
128  * @retval kStatus_SSS_Success The operation has completed successfully.
129  * @retval kStatus_SSS_Fail The operation has failed.
130  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
131  */
132 sss_status_t sss_mgmt_fuse_program(
133     sss_mgmt_t *context, uint32_t fuseId, uint32_t *srcData, size_t *srcDataLen, uintptr_t options, size_t *optionsLen);
134 
135 /*! @brief Get lifecycle
136  *  The function provides read lifecycle service
137  *
138  * @param context Pointer to mgmt crypto context.
139  * @param lifecycleData Destination address of the read value
140  *
141  * @returns Status of the operation
142  * @retval kStatus_SSS_Success The operation has completed successfully.
143  * @retval kStatus_SSS_Fail The operation has failed.
144  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
145  */
146 sss_status_t sss_mgmt_get_lifecycle(sss_mgmt_t *context, uint32_t *lifecycleData);
147 /*! @brief Advance lifecycle
148  *  The function provides advance lifecycle service
149  *
150  * @param context Pointer to mgmt crypto context.
151  *
152  * @returns Status of the operation
153  * @retval kStatus_SSS_Success The operation has completed successfully.
154  * @retval kStatus_SSS_Fail The operation has failed.
155  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
156  */
157 sss_status_t sss_mgmt_advance_lifecycle(sss_mgmt_t *context,
158                                         uint32_t *lifecycleData,
159                                         uintptr_t options,
160                                         size_t *optionsLen);
161 
162 /*! @brief Import non-key sensitive data
163  *  The function loads non-key sensitive data in plain to security sub-system
164  *  to temporary storage space
165  *
166  * @param context Pointer to mgmt crypto context.
167  * @param srcData Address of the source data buffer
168  * @param dataLen Length of the source data buffer in bytes
169  *
170  * @returns Status of the operation
171  * @retval kStatus_SSS_Success The operation has completed successfully.
172  * @retval kStatus_SSS_Fail The operation has failed.
173  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
174  */
175 sss_status_t sss_mgmt_import_secret(sss_mgmt_t *context, const uint8_t *srcData, size_t dataLen);
176 
177 /*! @brief Export non-key sensitive data
178  *  The function exports non-key sensitive data in plain out from security sub-system
179  *  from temporary storage space
180  *
181  * @param context Pointer to mgmt crypto context.
182  * @param destData Address of the destination data buffer
183  * @param dataLen Input length of the destination data buffer, output actual number of bytes written to destData
184  *
185  * @returns Status of the operation
186  * @retval kStatus_SSS_Success The operation has completed successfully.
187  * @retval kStatus_SSS_Fail The operation has failed.
188  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
189  */
190 sss_status_t sss_mgmt_export_secret(sss_mgmt_t *context, uint8_t *destData, size_t *dataLen);
191 
192 /*! @brief Attestation
193  *  The function provides attestation service.
194  *  This service provides a measurement of the security sub-system firmware, version and lifecycle.
195  *
196  * @param context Pointer to mgmt crypto context.
197  * @param destData Address of the destination data buffer
198  * @param dataLen Input length of the destination data buffer in bytes, output actual number of bytes written to
199  * destData
200  *
201  * @returns Status of the operation
202  * @retval kStatus_SSS_Success The operation has completed successfully.
203  * @retval kStatus_SSS_Fail The operation has failed.
204  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
205  */
206 sss_status_t sss_mgmt_attest(sss_mgmt_t *context, uint8_t *destData, size_t *dataLen);
207 
208 /*! @brief Load data for data-sealing
209  *  The function loads data to security sub-system that shall be encapsulated
210  *  into a cryptographical blob by @ref sss_mgmt_blob_export_secret().
211  *  The data is implementation specific.
212  *
213  * @param context Pointer to mgmt crypto context.
214  * @param srcData Address of the source data buffer
215  * @param dataLen Length of the source data buffer in bytes
216  *
217  * @returns Status of the operation
218  * @retval kStatus_SSS_Success The operation has completed successfully.
219  * @retval kStatus_SSS_Fail The operation has failed.
220  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
221  */
222 sss_status_t sss_mgmt_blob_load_secret(sss_mgmt_t *context, const uint8_t *srcData, size_t dataLen);
223 
224 /*! @brief Export data in a cryptographical blob
225  *  The function exports previously loaded data by @ref sss_mgmt_blob_load_secret from security sub-system
226  *  as a cryptographical blob. Such a blob shall be stored in a non-volatile memory
227  *  for later use by @ref sss_mgmt_blob_import_secret
228  *
229  * @param context Pointer to mgmt crypto context.
230  * @param destData Address of the destination data buffer
231  * @param dataLen Input length of the destination data buffer, output actual number of bytes written to destData
232  *
233  * @returns Status of the operation
234  * @retval kStatus_SSS_Success The operation has completed successfully.
235  * @retval kStatus_SSS_Fail The operation has failed.
236  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
237  */
238 sss_status_t sss_mgmt_blob_export_secret(sss_mgmt_t *context, uint8_t *destData, size_t *dataLen);
239 
240 /*! @brief Install a blob into security sub-system internal memory
241  *  The function install a blob into internal memory of the sucurity sub-system
242  *
243  * @param context Pointer to mgmt crypto context.
244  * @param srcData Address of the source data buffer
245  * @param dataLen Length of the source data buffer in bytes
246  *
247  * @returns Status of the operation
248  * @retval kStatus_SSS_Success The operation has completed successfully.
249  * @retval kStatus_SSS_Fail The operation has failed.
250  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
251  */
252 sss_status_t sss_mgmt_blob_import_secret(sss_mgmt_t *context, const uint8_t *srcData, size_t dataLen);
253 
254 /*! @brief Read software version counter
255  *  The function provides read software version service
256  *
257  * @param context Pointer to mgmt crypto context.
258  * @param version Array of 32-bit version words
259  * @param versionWordCount Number of output 32-bit version words
260  *
261  * @returns Status of the operation
262  * @retval kStatus_SSS_Success The operation has completed successfully.
263  * @retval kStatus_SSS_Fail The operation has failed.
264  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
265  */
266 sss_status_t sss_mgmt_get_software_version(sss_mgmt_t *context,
267                                            uint32_t *version,
268                                            size_t versionWordCount,
269                                            uint32_t options);
270 
271 /*! @brief Update software version counter
272  *  The function provides write software version service
273  *
274  * @param context Pointer to mgmt crypto context.
275  * @param version Array of 32-bit version words
276  * @param versionWordCount Number of output 32-bit version words
277  *
278  * @returns Status of the operation
279  * @retval kStatus_SSS_Success The operation has completed successfully.
280  * @retval kStatus_SSS_Fail The operation has failed.
281  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
282  */
283 sss_status_t sss_mgmt_set_software_version(sss_mgmt_t *context,
284                                            uint32_t *version,
285                                            size_t versionWordCount,
286                                            uint32_t options);
287 
288 /*! @brief Move the security sub-system to field return state
289  *  The function sends a request for field return
290  *
291  * @param context Pointer to mgmt crypto context.
292  *
293  * @returns Status of the operation
294  * @retval kStatus_SSS_Success The operation has completed successfully.
295  * @retval kStatus_SSS_Fail The operation has failed.
296  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
297  */
298 sss_status_t sss_mgmt_set_return_fa(sss_mgmt_t *context,
299                                     const uint8_t *request,
300                                     size_t requestSize,
301                                     uintptr_t options,
302                                     size_t *optionsLen,
303                                     uint32_t *resultState);
304 
305 /*! @brief Configure host access permissions
306  *
307  * @param context Pointer to mgmt crypto context.
308  * @param secLvl Required security level, must be either equal or lower as security level of the host sending this
309  * command
310  *
311  * @returns Status of the operation
312  * @retval kStatus_SSS_Success The operation has completed successfully.
313  * @retval kStatus_SSS_Fail The operation has failed.
314  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
315  */
316 sss_status_t sss_mgmt_set_host_access_permission(sss_mgmt_t *context, const sss_mgmt_security_level_t secLvl);
317 
318 /*! @brief Enable runtime integrity checks
319  *  The function sends a request to enable runtime integrity checks within security sub-system
320  *
321  * @param context Pointer to mgmt crypto context.
322  *
323  * @returns Status of the operation
324  * @retval kStatus_SSS_Success The operation has completed successfully.
325  * @retval kStatus_SSS_Fail The operation has failed.
326  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
327  */
328 sss_status_t sss_mgmt_integrity_check_enable(sss_mgmt_t *context);
329 
330 /*! @brief Attestation
331  *  The function provides attestation service.
332  *  This service provides a measurement of the security sub-system firmware, version and lifecycle.
333  *
334  * @param context Pointer to mgmt crypto context.
335  * @param destData Address of the destination data buffer
336  * @param dataLen Input length of the destination data buffer in bytes, output actual number of bytes written to
337  * destData
338  *
339  * @returns Status of the operation
340  * @retval kStatus_SSS_Success The operation has completed successfully.
341  * @retval kStatus_SSS_Fail The operation has failed.
342  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
343  */
344 sss_status_t sss_mgmt_ping(sss_mgmt_t *context);
345 
346 /*! @brief Removes all keys in SSS
347  *  The function sends a request to remove all keys within security sub-system
348  *
349  * @param context Pointer to mgmt crypto context.
350  *
351  * @returns Status of the operation
352  * @retval kStatus_SSS_Success The operation has completed successfully.
353  * @retval kStatus_SSS_Fail The operation has failed.
354  * @retval kStatus_SSS_InvalidArgument One of the arguments is invalid for the function to execute.
355  */
356 sss_status_t sss_mgmt_clear_all_keys(sss_mgmt_t *context);
357 
358 /*! @brief Mgmt context release.
359  *  The function frees Mgmt context.
360  *
361  * @param context Pointer to Mgmt crypto context.
362  */
363 sss_status_t sss_mgmt_context_free(sss_mgmt_t *context);
364 /*!
365  *@}
366  */ /* end of sss_management */
367 
368 #if defined(__cplusplus)
369 }
370 #endif
371 
372 #endif /* FSL_SSS_MGMT_H */
373