1 /***************************************************************************//**
2 * @file
3 * @brief SE Mailbox API
4 *******************************************************************************
5 * # License
6 * <b>Copyright 2024 Silicon Laboratories Inc. www.silabs.com</b>
7 *******************************************************************************
8 *
9 * SPDX-License-Identifier: Zlib
10 *
11 * The licensor of this software is Silicon Laboratories Inc.
12 *
13 * This software is provided 'as-is', without any express or implied
14 * warranty. In no event will the authors be held liable for any damages
15 * arising from the use of this software.
16 *
17 * Permission is granted to anyone to use this software for any purpose,
18 * including commercial applications, and to alter it and redistribute it
19 * freely, subject to the following restrictions:
20 *
21 * 1. The origin of this software must not be misrepresented; you must not
22 * claim that you wrote the original software. If you use this software
23 * in a product, an acknowledgment in the product documentation would be
24 * appreciated but is not required.
25 * 2. Altered source versions must be plainly marked as such, and must not be
26 * misrepresented as being the original software.
27 * 3. This notice may not be removed or altered from any source distribution.
28 *
29 ******************************************************************************/
30 #ifndef SLI_SE_MANAGER_MAILBOX_H
31 #define SLI_SE_MANAGER_MAILBOX_H
32
33 #if defined(__linux__)
34 #define SLI_SE_MAILBOX_HOST_SYSTEM
35 #else
36
37 #include "em_device.h"
38
39 #endif // __linux__
40
41 #include "sl_common.h"
42
43 #if defined(SLI_SE_MAILBOX_HOST_SYSTEM) || defined(SEMAILBOX_PRESENT) || defined(CRYPTOACC_PRESENT)
44
45 #include <stdint.h>
46 #include <stdbool.h>
47 #include <stddef.h>
48
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52
53 /*******************************************************************************
54 ****************************** DEFINES ***********************************
55 ******************************************************************************/
56
57 // -----------------------------------------------------------------------------
58 // SE status codes
59
60 /// Response status codes for the Secure Engine
61 #define SLI_SE_RESPONSE_MASK 0x000F0000UL
62 /// Command executed successfully or signature was successfully validated.
63 #define SLI_SE_RESPONSE_OK 0x00000000UL
64
65 /// Command was not recognized as a valid command, or is not allowed in the
66 /// current context.
67 #define SLI_SE_RESPONSE_INVALID_COMMAND 0x00010000UL
68 /// User did not provide the required credentials to be allowed to execute the
69 /// command.
70 #define SLI_SE_RESPONSE_AUTHORIZATION_ERROR 0x00020000UL
71 /// Signature validation command (e.g. SE_COMMAND_SIGNATURE_VERIFY) failed to
72 /// verify the given signature as being correct.
73 #define SLI_SE_RESPONSE_INVALID_SIGNATURE 0x00030000UL
74 /// A command started in non-secure mode is trying to access secure memory.
75 #define SLI_SE_RESPONSE_BUS_ERROR 0x00040000UL
76 /// Internal error
77 #define SLI_SE_RESPONSE_INTERNAL_ERROR 0x00050000UL
78 /// An internal error was raised and the command did not execute.
79 #define SLI_SE_RESPONSE_CRYPTO_ERROR 0x00060000UL
80 /// One of the passed parameters is deemed invalid (e.g. out of bounds).
81 #define SLI_SE_RESPONSE_INVALID_PARAMETER 0x00070000UL
82 /// Failure while checking the host for secure boot
83 #define SLI_SE_RESPONSE_SECUREBOOT_ERROR 0x00090000UL
84 /// Failure during selftest
85 #define SLI_SE_RESPONSE_SELFTEST_ERROR 0x000A0000UL
86 /// Feature/item not initialized or not present
87 #define SLI_SE_RESPONSE_NOT_INITIALIZED 0x000B0000UL
88 /// Abort status code is given when no operation is attempted.
89 #define SLI_SE_RESPONSE_ABORT 0x00FF0000UL
90 #if defined(CRYPTOACC_PRESENT)
91 /// Root Code Mailbox is invalid.
92 #define SLI_SE_RESPONSE_MAILBOX_INVALID 0x00FE0000UL
93 /// Root Code Mailbox is valid
94 #define SLI_SE_RESPONSE_MAILBOX_VALID 0xE5ECC0DEUL
95 #endif // CRYPTOACC_PRESENT
96
97 // -----------------------------------------------------------------------------
98 // SE command words
99 // Commands are grouped based on availability
100 #define SLI_SE_COMMAND_CHECK_SE_IMAGE 0x43020000UL
101 #define SLI_SE_COMMAND_APPLY_SE_IMAGE 0x43030000UL
102 #define SLI_SE_COMMAND_STATUS_SE_IMAGE 0x43040000UL
103 #define SLI_SE_COMMAND_CHECK_HOST_IMAGE 0x43050001UL
104 #define SLI_SE_COMMAND_APPLY_HOST_IMAGE 0x43060001UL
105 #define SLI_SE_COMMAND_STATUS_HOST_IMAGE 0x43070000UL
106
107 #define SLI_SE_COMMAND_READ_OTP 0xFE040000UL
108
109 #define SLI_SE_COMMAND_INIT_OTP 0xFF000001UL
110 #define SLI_SE_COMMAND_INIT_PUBKEY 0xFF070001UL
111 #define SLI_SE_COMMAND_READ_PUBKEY 0xFF080001UL
112
113 #define SLI_SE_COMMAND_READ_PUBKEY 0xFF080001UL
114 #define SLI_SE_COMMAND_READ_OTP 0xFE040000UL
115
116 #define SLI_SE_COMMAND_DBG_LOCK_APPLY 0x430C0000UL
117
118 // Commands limited to SE devices
119 #if defined(SEMAILBOX_PRESENT)
120 #define SLI_SE_COMMAND_CREATE_KEY 0x02000000UL
121 #define SLI_SE_COMMAND_READPUB_KEY 0x02010000UL
122
123 #define SLI_SE_COMMAND_HASH 0x03000000UL
124 #define SLI_SE_COMMAND_HASHUPDATE 0x03010000UL
125 #define SLI_SE_COMMAND_HMAC 0x03020000UL
126 #if defined(_SILICON_LABS_32B_SERIES_3)
127 #define SLI_SE_COMMAND_HMAC_STREAMING_START 0x03040000UL
128 #define SLI_SE_COMMAND_HMAC_STREAMING_UPDATE 0x03050000UL
129 #define SLI_SE_COMMAND_HMAC_STREAMING_FINISH 0x03060000UL
130 #endif // _SILICON_LABS_32B_SERIES_3
131 #define SLI_SE_COMMAND_HASHFINISH 0x03030000UL
132
133 #define SLI_SE_COMMAND_AES_ENCRYPT 0x04000000UL
134 #define SLI_SE_COMMAND_AES_DECRYPT 0x04010000UL
135 #define SLI_SE_COMMAND_AES_GCM_ENCRYPT 0x04020000UL
136 #define SLI_SE_COMMAND_AES_GCM_DECRYPT 0x04030000UL
137 #define SLI_SE_COMMAND_AES_CMAC 0x04040000UL
138 #define SLI_SE_COMMAND_AES_CCM_ENCRYPT 0x04050000UL
139 #define SLI_SE_COMMAND_AES_CCM_DECRYPT 0x04060000UL
140
141 #define SLI_SE_COMMAND_SIGNATURE_SIGN 0x06000000UL
142 #define SLI_SE_COMMAND_SIGNATURE_VERIFY 0x06010000UL
143 #define SLI_SE_COMMAND_EDDSA_SIGN 0x06020000UL
144 #define SLI_SE_COMMAND_EDDSA_VERIFY 0x06030000UL
145
146 #define SLI_SE_COMMAND_TRNG_GET_RANDOM 0x07000000UL
147
148 #define SLI_SE_COMMAND_JPAKE_R1_GENERATE 0x0B000000UL
149 #define SLI_SE_COMMAND_JPAKE_R1_VERIFY 0x0B000100UL
150 #define SLI_SE_COMMAND_JPAKE_R2_GENERATE 0x0B010000UL
151 #define SLI_SE_COMMAND_JPAKE_R2_VERIFY 0x0B010100UL
152 #define SLI_SE_COMMAND_JPAKE_GEN_SESSIONKEY 0x0B020000UL
153
154 #define SLI_SE_COMMAND_DH 0x0E000000UL
155
156 #define SLI_SE_COMMAND_STATUS_SE_VERSION 0x43080000UL
157 #define SLI_SE_COMMAND_STATUS_OTP_VERSION 0x43080100UL
158 #define SLI_SE_COMMAND_WRITE_USER_DATA 0x43090000UL
159 #define SLI_SE_COMMAND_ERASE_USER_DATA 0x430A0000UL
160 #define SLI_SE_COMMAND_DBG_LOCK_ENABLE_SECURE 0x430D0000UL
161 #define SLI_SE_COMMAND_DBG_LOCK_DISABLE_SECURE 0x430E0000UL
162 #define SLI_SE_COMMAND_DEVICE_ERASE 0x430F0000UL
163 #define SLI_SE_COMMAND_DEVICE_ERASE_DISABLE 0x43100000UL
164 #define SLI_SE_COMMAND_DBG_LOCK_STATUS 0x43110000UL
165 #define SLI_SE_COMMAND_DBG_SET_RESTRICTIONS 0x43120000UL
166 #define SLI_SE_COMMAND_PROTECTED_REGISTER 0x43210000UL
167 #if defined(_SILICON_LABS_32B_SERIES_3)
168 #define SLI_SE_COMMAND_READ_DEVICE_DATA 0x43300000UL
169 #endif
170 #if defined(SLI_SE_COMMAND_STATUS_READ_RSTCAUSE_AVAILABLE)
171 // SLI_SE_COMMAND_STATUS_READ_RSTCAUSE is only available on xG21 devices (series-2-config-1)
172 #define SLI_SE_COMMAND_STATUS_READ_RSTCAUSE 0x43220000UL
173 #endif // SLI_SE_COMMAND_STATUS_READ_RSTCAUSE_AVAILABLE
174 #define SLI_SE_COMMAND_READ_USER_CERT_SIZE 0x43FA0000UL
175 #define SLI_SE_COMMAND_READ_USER_CERT 0x43FB0000UL
176
177 #if defined(_SILICON_LABS_32B_SERIES_3)
178 #define SLI_SE_COMMAND_GET_HOST_UPGRADE_FILE_VERSION 0x44000000UL
179 #define SLI_SE_COMMAND_SET_HOST_UPGRADE_FILE_VERSION 0x44010000UL
180 #endif // _SILICON_LABS_32B_SERIES_3
181
182 #define SLI_SE_COMMAND_ENTER_ACTIVE_MODE 0x45000000UL
183 #define SLI_SE_COMMAND_EXIT_ACTIVE_MODE 0x45010000UL
184
185 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT)
186 #define SLI_SE_COMMAND_ATTEST_PSA_IAT 0x0A030000UL
187 #define SLI_SE_COMMAND_ATTEST_CONFIG 0x0A040000UL
188 #endif // _SILICON_LABS_SECURITY_FEATURE_VAULT)
189
190 #define SLI_SE_COMMAND_GET_CHALLENGE 0xFD000001UL
191 #define SLI_SE_COMMAND_ROLL_CHALLENGE 0xFD000101UL
192 #define SLI_SE_COMMAND_OPEN_DEBUG 0xFD010001UL
193
194 #define SLI_SE_COMMAND_READ_SERIAL 0xFE000000UL
195 #define SLI_SE_COMMAND_GET_STATUS 0xFE010000UL
196 #define SLI_SE_COMMAND_READ_PUBKEYBOOT 0xFE020001UL
197 #define SLI_SE_COMMAND_SET_UPGRADEFLAG_SE 0xFE030000UL
198 #define SLI_SE_COMMAND_SET_UPGRADEFLAG_HOST 0xFE030001UL
199 #define SLI_SE_COMMAND_READ_TAMPER_RESET_CAUSE 0xFE050000UL
200
201 #define SLI_SE_COMMAND_INIT_PUBKEY_SIGNATURE 0xFF090001UL
202 #define SLI_SE_COMMAND_READ_PUBKEY_SIGNATURE 0xFF0A0001UL
203 #define SLI_SE_COMMAND_INIT_AES_128_KEY 0xFF0B0001UL
204 #if defined(_SILICON_LABS_32B_SERIES_3)
205 #define SLI_SE_COMMAND_CONFIGURE_QSPI_REF_CLOCK 0xFF150000UL
206 #define SLI_SE_COMMAND_CONFIGURE_QSPI_REGS 0xFF160000UL
207 #define SLI_SE_COMMAND_GET_QSPI_FLPLL_CONFIG 0xFF170000UL
208 #define SLI_SE_COMMAND_APPLY_CODE_REGION_CONFIG 0xFF500000UL
209 #define SLI_SE_COMMAND_CLOSE_CODE_REGION 0xFF510000UL
210 #define SLI_SE_COMMAND_ERASE_CODE_REGION 0xFF520000UL
211 #define SLI_SE_COMMAND_GET_CODE_REGION_CONFIG 0xFF530000UL
212 #define SLI_SE_COMMAND_GET_CODE_REGION_VERSION 0xFF540000UL
213 #define SLI_SE_COMMAND_SET_ACTIVE_BANKED_CODE_REGION 0xFF550000UL
214 #define SLI_SE_COMMAND_WRITE_CODE_REGION 0xFF560000UL
215 #define SLI_SE_COMMAND_ERASE_DATA_REGION 0xFF620000UL
216 #define SLI_SE_COMMAND_WRITE_DATA_REGION 0xFF630000UL
217 #define SLI_SE_COMMAND_GET_DATA_REGION_LOCATION 0xFF640000UL
218 #endif
219 #endif // SLI_MAILBOX_COMMAND_SUPPORTED
220
221 // Commands limited to SE Vault High devices
222 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT)
223 #define SLI_SE_COMMAND_WRAP_KEY 0x01000000UL
224 #define SLI_SE_COMMAND_UNWRAP_KEY 0x01020000UL
225 #define SLI_SE_COMMAND_DELETE_KEY 0x01050000UL
226 #define SLI_SE_COMMAND_TRANSFER_KEY 0x01060000UL
227
228 #define SLI_SE_COMMAND_DERIVE_KEY_PBKDF2_HMAC 0x02020002UL
229 #define SLI_SE_COMMAND_DERIVE_KEY_HKDF 0x02020003UL
230 #define SLI_SE_COMMAND_DERIVE_KEY_PBKDF2_CMAC 0x02020010UL
231
232 #define SLI_SE_COMMAND_CHACHAPOLY_ENCRYPT 0x0C000000UL
233 #define SLI_SE_COMMAND_CHACHAPOLY_DECRYPT 0x0C010000UL
234 #define SLI_SE_COMMAND_CHACHA20_ENCRYPT 0x0C020000UL
235 #define SLI_SE_COMMAND_CHACHA20_DECRYPT 0x0C030000UL
236 #define SLI_SE_COMMAND_POLY1305_KEY_MAC 0x0C040000UL
237
238 #define SLI_SE_COMMAND_DISABLE_TAMPER 0xFD020001UL
239 #endif // _SILICON_LABS_SECURITY_FEATURE_VAULT
240
241 // -----------------------------------------------------------------------------
242 // SE command options
243 // Commands are grouped based on availability
244
245 /// Secure boot pubkey
246 #define SLI_SE_KEY_TYPE_BOOT 0x00000100UL
247 /// Secure authorization (debug) pubkey
248 #define SLI_SE_KEY_TYPE_AUTH 0x00000200UL
249
250 // Options limited to SE devices
251 #if defined(SEMAILBOX_PRESENT)
252 /// Root pubkey
253 #define SLI_SE_KEY_TYPE_ROOT 0x00000300UL
254 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT)
255 /// Attestation pubkey
256 #define SLI_SE_KEY_TYPE_ATTEST 0x00000400UL
257 #endif // _SILICON_LABS_SECURITY_FEATURE_VAULT
258 /// BGL encryption key
259 #define SLI_SE_IMMUTABLE_KEY_TYPE_AES_128 0x00000500UL
260
261 /// Use MD5 as hash algorithm
262 #define SLI_SE_COMMAND_OPTION_HASH_MD5 0x00000100UL
263 /// Use SHA1 as hash algorithm
264 #define SLI_SE_COMMAND_OPTION_HASH_SHA1 0x00000200UL
265 /// Use SHA224 as hash algorithm
266 #define SLI_SE_COMMAND_OPTION_HASH_SHA224 0x00000300UL
267 /// Use SHA256 as hash algorithm
268 #define SLI_SE_COMMAND_OPTION_HASH_SHA256 0x00000400UL
269 #if defined(_SILICON_LABS_32B_SERIES_3)
270 /// Use SHA1 as hash algorithm for HMAC streaming operation
271 #define SLI_SE_COMMAND_OPTION_HMAC_HASH_SHA1 0x00000700UL
272 /// Use SHA224 as hash algorithm for HMAC streaming operation
273 #define SLI_SE_COMMAND_OPTION_HMAC_HASH_SHA224 0x00000800UL
274 /// Use SHA256 as hash algorithm for HMAC streaming operation
275 #define SLI_SE_COMMAND_OPTION_HMAC_HASH_SHA256 0x00000900UL
276 #endif // _SILICON_LABS_32B_SERIES_3
277
278 /// Execute algorithm in ECB mode
279 #define SLI_SE_COMMAND_OPTION_MODE_ECB 0x00000100UL
280 /// Execute algorithm in CBC mode
281 #define SLI_SE_COMMAND_OPTION_MODE_CBC 0x00000200UL
282 /// Execute algorithm in CTR mode
283 #define SLI_SE_COMMAND_OPTION_MODE_CTR 0x00000300UL
284 /// Execute algorithm in CFB mode
285 #define SLI_SE_COMMAND_OPTION_MODE_CFB 0x00000400UL
286
287 /// Run the whole algorithm, all data present
288 #define SLI_SE_COMMAND_OPTION_CONTEXT_WHOLE 0x00000000UL
289 /// Start the algorithm, but get a context to later add more data
290 #define SLI_SE_COMMAND_OPTION_CONTEXT_START 0x00000001UL
291 /// End the algorithm, get the result
292 #define SLI_SE_COMMAND_OPTION_CONTEXT_END 0x00000002UL
293 /// Add more data input to the algorithm. Need to supply previous context,
294 /// and get a context back
295 #define SLI_SE_COMMAND_OPTION_CONTEXT_ADD 0x00000003UL
296
297 /// User data command options
298 /// Magic paramater for deleting user data
299 #define SLI_SE_COMMAND_OPTION_ERASE_UD 0xDE1E7EADUL
300 #define SLI_SE_COMMAND_OPTION_WRITE 0x00000100UL
301 #define SLI_SE_COMMAND_OPTION_READ 0x00000000UL
302
303 #define SLI_SE_COMMAND_CERT_BATCH 0x00000100UL
304 #define SLI_SE_COMMAND_CERT_SE 0x00000200UL
305 #define SLI_SE_COMMAND_CERT_HOST 0x00000300UL
306
307 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT)
308 /// Use SHA384 as hash algorithm
309 #define SLI_SE_COMMAND_OPTION_HASH_SHA384 0x00000500UL
310 /// Use SHA512 as hash algorithm
311 #define SLI_SE_COMMAND_OPTION_HASH_SHA512 0x00000600UL
312 #if defined(_SILICON_LABS_32B_SERIES_3)
313 /// Use SHA384 as hash algorithm for HMAC streaming operation
314 #define SLI_SE_COMMAND_OPTION_HMAC_HASH_SHA384 0x00000A00UL
315 /// Use SHA512 as hash algorithm for HMAC streaming operation
316 #define SLI_SE_COMMAND_OPTION_HMAC_HASH_SHA512 0x00000B00UL
317 #endif // _SILICON_LABS_32B_SERIES_3
318 #endif // _SILICON_LABS_SECURITY_FEATURE_VAULT
319 #endif // SLI_MAILBOX_COMMAND_SUPPORTED
320
321 // -----------------------------------------------------------------------------
322 // Other defines
323
324 /** Maximum amount of parameters supported by the hardware FIFO */
325 #define SE_FIFO_MAX_PARAMETERS 13U
326
327 /** Stop datatransfer */
328 #define SLI_SE_DATATRANSFER_STOP 0x00000001UL
329 /** Discard datatransfer */
330 #define SLI_SE_DATATRANSFER_DISCARD 0x40000000UL
331 /** Realign datatransfer */
332 #define SLI_SE_DATATRANSFER_REALIGN 0x20000000UL
333 /** Datatransfer Const Address*/
334 #define SLI_SE_DATATRANSFER_CONSTADDRESS 0x10000000UL
335 /** Stop Length Mask */
336 #define SLI_SE_DATATRANSFER_LENGTH_MASK 0x0FFFFFFFUL
337
338 /** Maximum amount of parameters for largest command in defined command set */
339 #ifndef SLI_SE_COMMAND_MAX_PARAMETERS
340 #define SLI_SE_COMMAND_MAX_PARAMETERS 4U
341 #endif
342
343 /* Sanity-check defines */
344 #if SLI_SE_COMMAND_MAX_PARAMETERS > SE_FIFO_MAX_PARAMETERS
345 #error "Trying to configure more parameters than supported by the hardware"
346 #endif
347
348 /*******************************************************************************
349 ****************************** TYPEDEFS ***********************************
350 ******************************************************************************/
351
352 /***************************************************************************//**
353 * @brief SE DMA transfer descriptor.
354
355 * Can be linked to each other to provide scatter-gather behavior.
356 ******************************************************************************/
357 typedef struct {
358 volatile void* volatile data; /**< Data pointer */
359 void* volatile next; /**< Next descriptor */
360 volatile uint32_t length; /**< Length */
361 } sli_se_datatransfer_t;
362
363 /** Default initialization of data transfer struct */
364 #define SLI_SE_DATATRANSFER_DEFAULT(address, data_size) \
365 { \
366 .data = (void*)(address), /* Pointer to data block */ \
367 .next = (void*)SLI_SE_DATATRANSFER_STOP, /* This is the last block by default */ \
368 .length = (data_size) | SLI_SE_DATATRANSFER_REALIGN /* Add size, use realign by default */ \
369 }
370
371 /***************************************************************************//**
372 * @brief SE mailbox command structure
373 *
374 * @details
375 * This structure defines the command structure used by the SE mailbox
376 ******************************************************************************/
377 typedef struct {
378 uint32_t command; /**< SE Command */
379 sli_se_datatransfer_t* data_in; /**< Input data */
380 sli_se_datatransfer_t* data_out; /**< Output data */
381 uint32_t parameters[SLI_SE_COMMAND_MAX_PARAMETERS]; /**< Parameters */
382 size_t num_parameters; /**< Number of parameters */
383 } sli_se_mailbox_command_t;
384
385 /** Default initialization of command struct */
386 #define SLI_SE_MAILBOX_COMMAND_DEFAULT(command_word) \
387 { \
388 .command = command_word, /* Given command word */ \
389 .data_in = NULL, /* No data in */ \
390 .data_out = NULL, /* No data out */ \
391 .parameters = { 0, 0, 0, 0 }, /* No parameters */ \
392 .num_parameters = 0 /* No parameters */ \
393 }
394
395 /** Possible responses to a command */
396 typedef uint32_t sli_se_mailbox_response_t;
397
398 /*******************************************************************************
399 ***************************** PROTOTYPES **********************************
400 ******************************************************************************/
401
402 /***************************************************************************//**
403 * @brief
404 * Add input data to a mailbox command
405 *
406 * @details
407 * This function adds a buffer of input data to the given SE command structure
408 * The buffer gets appended by reference at the end of the list of already
409 * added buffers.
410 *
411 * @note
412 * Note that this function does not copy either the data buffer or the buffer
413 * structure, so make sure to keep the data object in scope until the command
414 * has been executed by the secure element.
415 *
416 * @param[in] command
417 * Pointer to an SE Mailbox command structure.
418 *
419 * @param[in] data
420 * Pointer to a data transfer structure.
421 ******************************************************************************/
422 void sli_se_mailbox_command_add_input(sli_se_mailbox_command_t *command, sli_se_datatransfer_t *data);
423
424 /***************************************************************************//**
425 * @brief
426 * Add output data to a mailbox command
427 *
428 * @details
429 * This function adds a buffer of output data to the given command structure
430 * The buffer gets appended by reference at the end of the list of already
431 * added buffers.
432 *
433 * @note
434 * Note that this function does not copy either the data buffer or the buffer
435 * structure, so make sure to keep the data object in scope until the command
436 * has been executed by the secure element.
437 *
438 * @param[in] command
439 * Pointer to an SE mailbox command structure.
440 *
441 * @param[in] data
442 * Pointer to a data transfer structure.
443 ******************************************************************************/
444 void sli_se_mailbox_command_add_output(sli_se_mailbox_command_t *command, sli_se_datatransfer_t *data);
445
446 /***************************************************************************//**
447 * @brief
448 * Add a parameter to a mailbox command
449 *
450 * @details
451 * This function adds a parameter word to the passed command.
452 *
453 * @note
454 * Make sure to not exceed @ref SE_MAX_PARAMETERS.
455 *
456 * @param[in] command
457 * Pointer to a filled-out SE command structure.
458 * @param[in] parameter
459 * Parameter to add.
460 ******************************************************************************/
461 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_SE_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
462 void sli_se_mailbox_command_add_parameter(sli_se_mailbox_command_t *command, uint32_t parameter);
463
464 #if !defined(SLI_SE_MAILBOX_HOST_SYSTEM)
465 /***************************************************************************//**
466 * @brief
467 * Execute the passed command
468 *
469 * @details
470 * This function starts the execution of the passed command by the secure
471 * element. The RXINT interrupt flag will be set upon completion. Call
472 * @ref sli_se_mailbox_read_response to wait for completion and retrieve the
473 * command's execution status.
474 *
475 * @param[in] command
476 * Pointer to a filled-out SE command structure.
477 ******************************************************************************/
478 SL_CODE_CLASSIFY(SL_CODE_COMPONENT_SE_MANAGER, SL_CODE_CLASS_TIME_CRITICAL)
479 void sli_se_mailbox_execute_command(sli_se_mailbox_command_t *command);
480 #endif //!defined(SLI_SE_MAILBOX_HOST_SYSTEM)
481
482 #if defined(SEMAILBOX_PRESENT)
483 /***************************************************************************//**
484 * @brief
485 * Read the status of the previously executed command.
486 *
487 * @details
488 * This function waits for any running command to complete before reading the
489 * status of the previously executed command.
490 *
491 * @note
492 * The command response needs to be read for every executed command, and can
493 * only be read once per executed command (FIFO behavior).
494 *
495 * @return
496 * One of the SE_RESPONSE return codes:
497 * SE_RESPONSE_OK when the command was executed successfully or a signature
498 * was successfully verified.
499 ******************************************************************************/
sli_se_mailbox_read_response(void)500 __STATIC_INLINE sli_se_mailbox_response_t sli_se_mailbox_read_response(void)
501 {
502 while (!(SEMAILBOX_HOST->RX_STATUS & SEMAILBOX_RX_STATUS_RXINT)) {
503 // Wait for command completion by polling SE Mailbox RX interrupt flag
504 }
505 // Return command response
506 return (sli_se_mailbox_response_t)(SEMAILBOX_HOST->RX_HEADER & SLI_SE_RESPONSE_MASK);
507 }
508 #elif defined(CRYPTOACC_PRESENT)
509 sli_se_mailbox_response_t sli_se_mailbox_read_response(void);
510 #endif // #if defined(SEMAILBOX_PRESENT)
511
512 /***************************************************************************//**
513 * @brief
514 * Disable one or more SE interrupts.
515 *
516 * @param[in] flags
517 * SE interrupt sources to disable. Use a bitwise logic OR combination of
518 * valid interrupt flags for the Secure Element module
519 * (SE_CONFIGURATION_(TX/RX)INTEN).
520 ******************************************************************************/
sli_se_mailbox_disable_interrupt(uint32_t flags)521 __STATIC_INLINE void sli_se_mailbox_disable_interrupt(uint32_t flags)
522 {
523 #if defined(SEMAILBOX_PRESENT)
524 SEMAILBOX_HOST->CONFIGURATION &= ~flags;
525 #else
526 (void) flags;
527 #endif
528 }
529
530 /***************************************************************************//**
531 * @brief
532 * Enable one or more SE interrupts.
533 *
534 * @param[in] flags
535 * SE interrupt sources to enable. Use a bitwise logic OR combination of
536 * valid interrupt flags for the Secure Element module
537 * (SEMAILBOX_CONFIGURATION_TXINTEN or SEMAILBOX_CONFIGURATION_RXINTEN).
538 ******************************************************************************/
sli_se_mailbox_enable_interrupt(uint32_t flags)539 __STATIC_INLINE void sli_se_mailbox_enable_interrupt(uint32_t flags)
540 {
541 #if defined(SEMAILBOX_PRESENT)
542 SEMAILBOX_HOST->CONFIGURATION |= flags;
543 #else
544 (void) flags;
545 #endif
546 }
547
548 #if defined(CRYPTOACC_PRESENT)
549 /***************************************************************************//**
550 * @brief
551 * Get current SE version
552 *
553 * @details
554 * This function returns the current VSE version
555 *
556 * @param[in] version
557 * Pointer to location where to copy the version of VSE to.
558 *
559 * @return
560 * One of the SE_RESPONSE return codes:
561 * SLI_SE_RESPONSE_OK when the command was executed successfully
562 * SLI_SE_RESPONSE_INVALID_PARAMETER when an invalid parameter was passed
563 * SLI_SE_RESPONSE_MAILBOX_INVALID when the mailbox content is invalid
564 ******************************************************************************/
565 sli_se_mailbox_response_t sli_vse_mailbox_get_version(uint32_t *version);
566
567 /***************************************************************************//**
568 * @brief
569 * Get VSE configuration and status bits
570 *
571 * @details
572 * This function returns the current VSE configuration and status bits.
573 * The following list explains what the different bits in cfg_status indicate.
574 * A bit value of 1 means enabled, while 0 means disabled:
575 * * [0]: Secure boot
576 * * [1]: Verify secure boot certificate
577 * * [2]: Anti-rollback
578 * * [3]: Narrow page lock
579 * * [4]: Full page lock
580 * The following status bits can be read with VSE versions
581 * higher than 1.2.2.
582 * * [10]: Debug port lock
583 * * [11]: Device erase enabled
584 * * [12]: Secure debug enabled
585 * * [15]: Debug port register state, 1 if the debug port is locked.
586 *
587 * @param[out] cfg_status
588 * Pointer to location to copy Configuration Status bits into.
589 *
590 * @note
591 * This function will check that the mailbox content is valid before
592 * reading the status bits. If the command response has already been read
593 * with a call to @ref sli_vse_mailbox_ack_command(), the validity check will fail, and
594 * the config status bits cannot be read before a reset has occurred.
595 *
596 * @return
597 * One of the SE_RESPONSE return codes:
598 * SLI_SE_RESPONSE_OK when the command was executed successfully
599 * SLI_SE_RESPONSE_INVALID_PARAMETER when an invalid parameter was passed
600 * SLI_SE_RESPONSE_MAILBOX_INVALID when the mailbox content is invalid
601 ******************************************************************************/
602 sli_se_mailbox_response_t sli_vse_mailbox_get_cfg_status(uint32_t *cfg_status);
603
604 /***************************************************************************//**
605 * @brief
606 * Get the version number of the OTP from the status field of the output
607 * mailbox
608 * @details
609 * This function checks if the OTP version number flag is set in the output
610 * mailbox. If it is, the version number is writen to @ref otp_version pointer
611 * location. If not, it returns error response.
612 *
613 * @param[out] otp_version
614 * Pointer to location to copy OTP version number into.
615 * @return
616 * One of the SE_RESPONSE return codes.
617 * @retval SLI_SE_RESPONSE_OK when the command was executed successfully
618 ******************************************************************************/
619 sli_se_mailbox_response_t sli_vse_mailbox_get_otp_version(uint32_t *otp_version);
620
621 /***************************************************************************//**
622 * @brief
623 * Acknowledge and get status and output data of a completed command.
624 *
625 * @details
626 * This function acknowledges and gets the status and output data of a
627 * completed mailbox command.
628 * The mailbox command is acknowledged by inverting all bits in the checksum
629 * (XOR with 0xFFFFFFFF).
630 * The output data is copied into the linked list of output buffers pointed
631 * to in the given command data structure.
632 *
633 * @param[in] command
634 * Pointer to an SE command structure.
635 *
636 * @return
637 * One of the SE_RESPONSE return codes.
638 * @retval SLI_SE_RESPONSE_OK when the command was executed successfully or a
639 * signature was successfully verified,
640 * @retval SLI_SE_RESPONSE_INVALID_COMMAND when the command ID was not recognized,
641 * @retval SE_RESPONSE_AUTHORIZATION_ERROR when the command is not authorized,
642 * @retval SE_RESPONSE_INVALID_SIGNATURE when signature verification failed,
643 * @retval SE_RESPONSE_BUS_ERROR when a bus error was thrown during the command,
644 * e.g. because of conflicting Secure/Non-Secure
645 * memory accesses,
646 * @retval SE_RESPONSE_CRYPTO_ERROR on an internal SE failure, or
647 * @retval SLI_SE_RESPONSE_INVALID_PARAMETER when an invalid parameter was passed
648 * @retval SLI_SE_RESPONSE_MAILBOX_INVALID when mailbox command not done or invalid
649 ******************************************************************************/
650 sli_se_mailbox_response_t sli_vse_mailbox_ack_command(sli_se_mailbox_command_t *command);
651
652 /***************************************************************************//**
653 * @brief
654 * Read the previously executed command.
655 *
656 * @details
657 * This function reads the previously executed command.
658 *
659 * @return
660 * One of the SE command words.
661 * SLI_SE_RESPONSE_MAILBOX_INVALID when the mailbox content is invalid.
662 ******************************************************************************/
663 uint32_t sli_vse_mailbox_read_executed_command(void);
664
665 /***************************************************************************//**
666 * @brief
667 * Check whether the VSE Output Mailbox is valid.
668 *
669 * @return True if the VSE Output Mailbox is valid (magic and checksum OK)
670 ******************************************************************************/
671 bool sli_vse_mailbox_is_output_valid(void);
672
673 #endif // #if defined(CRYPTOACC_PRESENT)
674
675 #ifdef __cplusplus
676 }
677 #endif
678
679 #endif // #if defined(SLI_SE_MAILBOX_HOST_SYSTEM) || defined(SEMAILBOX_PRESENT) || defined(CRYPTOACC_PRESENT)
680
681 #endif /* SLI_SE_MANAGER_MAILBOX_H */
682
