SEEMLIB
Detailed Description
Secure Element peripheral API.
Abstraction of the Secure Element's mailbox interface.
- Note
- Although commands to interact with the mailbox directly are available, it is always recommended to use the higher level APIs available in em_se and through mbedTLS.
- Using the SE's mailbox is not thread-safe in emlib, and accessing the SE's mailbox both in regular and IRQ context is not safe, either. If mbedTLS is compiled into the application, SE operations should be wrapped in se_management_acquire()/se_management_release() calls to synchronize access. If mbedTLS is not in use, it is the user's responsibility to not trigger simultaneous use of the SE mailbox.
Data Structures |
|
struct | root_InputMailbox_t |
struct | root_OutputMailbox_t |
struct | SE_Command_t |
struct | SE_DataTransfer_t |
struct | SE_DebugStatus_t |
struct | SE_OTPInit_t |
struct | SE_Status_t |
Macros |
|
#define | ROOT_MAILBOX_INPUT_BASE (ROOT_MAILBOX_OUTPUT_BASE - ROOT_MAILBOX_SIZE) |
#define | ROOT_MAILBOX_OUTPUT_BASE (RDMEM_FRCRAM_S_MEM_END + 1 - ROOT_MAILBOX_SIZE) |
#define | ROOT_MAILBOX_SIZE (512UL) |
#define | ROOT_MB_DONE (1 << 23) |
#define | ROOT_MB_LENGTH_PARAM_NUM_SHIFT (24) |
#define | ROOT_MB_OUTPUT_STATUS_CONFIG_BITS_MASK (0xFFFF) |
#define | SE_COMMAND_APPLY_HOST_IMAGE 0x43060001UL |
#define | SE_COMMAND_APPLY_SE_IMAGE 0x43030000UL |
#define | SE_COMMAND_CHECK_HOST_IMAGE 0x43050001UL |
#define | SE_COMMAND_CHECK_SE_IMAGE 0x43020000UL |
#define | SE_COMMAND_DEFAULT (command) |
#define | SE_COMMAND_STATUS_HOST_IMAGE 0x43070000UL |
#define | SE_COMMAND_STATUS_SE_IMAGE 0x43040000UL |
#define | SE_DATATRANSFER_CONSTADDRESS 0x10000000UL |
#define | SE_DATATRANSFER_DEFAULT (address, length) |
#define | SE_DATATRANSFER_DISCARD 0x40000000UL |
#define | SE_DATATRANSFER_LENGTH_MASK 0x0FFFFFFFUL |
#define | SE_DATATRANSFER_REALIGN 0x20000000UL |
#define | SE_DATATRANSFER_STOP 0x00000001UL |
#define | SE_FIFO_MAX_PARAMETERS 13U |
#define | SE_MAX_PARAMETERS 4U |
#define | SE_RESPONSE_ABORT 0x00090000UL |
#define | SE_RESPONSE_AUTHORIZATION_ERROR 0x00020000UL |
#define | SE_RESPONSE_BUS_ERROR 0x00040000UL |
#define | SE_RESPONSE_CRYPTO_ERROR 0x00060000UL |
#define | SE_RESPONSE_INTERNAL_ERROR 0x00050000UL |
#define | SE_RESPONSE_INVALID_COMMAND 0x00010000UL |
#define | SE_RESPONSE_INVALID_PARAMETER 0x00070000UL |
#define | SE_RESPONSE_INVALID_SIGNATURE 0x00030000UL |
#define | SE_RESPONSE_MAILBOX_INVALID 0x000A0000UL |
#define | SE_RESPONSE_MAILBOX_VALID 0xE5ECC0DEUL |
#define | SE_RESPONSE_MASK 0x000F0000UL |
#define | SE_RESPONSE_OK 0x00000000UL |
Typedefs |
|
typedef uint32_t | SE_Response_t |
Functions |
|
bool | rootIsOutputMailboxValid (void) |
Check whether the Root Code Output Mailbox is valid.
|
|
SE_Response_t | SE_ackCommand ( SE_Command_t *command) |
Acknowledge and get status and output data of a completed command.
|
|
void | SE_addDataInput ( SE_Command_t *command, SE_DataTransfer_t *data) |
Add input data to a command.
|
|
void | SE_addDataOutput ( SE_Command_t *command, SE_DataTransfer_t *data) |
Add output data to a command.
|
|
void | SE_addParameter ( SE_Command_t *command, uint32_t parameter) |
Add a parameter to a command.
|
|
__STATIC_INLINE void | SE_disableInterrupt (uint32_t flags) |
Disable one or more SE interrupts.
|
|
__STATIC_INLINE void | SE_enableInterrupt (uint32_t flags) |
Enable one or more SE interrupts.
|
|
void | SE_executeCommand ( SE_Command_t *command) |
Execute the passed command.
|
|
SE_Response_t | SE_getConfigStatusBits (uint32_t *cfgStatus) |
Get Root Code Configuration Status bits.
|
|
SE_Response_t | SE_getVersion (uint32_t *version) |
Get current SE version.
|
|
bool | SE_isCommandCompleted (void) |
Check whether the running command has completed.
|
|
SE_Response_t | SE_readCommandResponse (void) |
Read the status of the previously executed command.
|
|
uint32_t | SE_readExecutedCommand (void) |
Read the previously executed command.
|
|
__STATIC_INLINE void | SE_waitCommandCompletion (void) |
Wait for completion of the current command.
|
|
Macro Definition Documentation
#define SE_COMMAND_DEFAULT | ( |
command
|
) |
Default initialization of command struct
Definition at line
339
of file
em_se.h
.
Referenced by sl_efp_emu_ldo_enable() .
#define SE_DATATRANSFER_DEFAULT | ( |
address,
|
|
length
|
|||
) |
Default initialization of data transfer struct
Definition at line
320
of file
em_se.h
.
#define SE_FIFO_MAX_PARAMETERS 13U |
Maximum amount of parameters supported by the hardware FIFO
Definition at line
298
of file
em_se.h
.
#define SE_MAX_PARAMETERS 4U |
Maximum amount of parameters for largest command in defined command set
Definition at line
294
of file
em_se.h
.
Referenced by SE_addParameter() , and SE_executeCommand() .
#define SE_RESPONSE_AUTHORIZATION_ERROR 0x00020000UL |
User did not provide the required credentials to be allowed to execute the command.
Definition at line
263
of file
em_se.h
.
#define SE_RESPONSE_BUS_ERROR 0x00040000UL |
A command started in non-secure mode is trying to access secure memory.
Definition at line
270
of file
em_se.h
.
#define SE_RESPONSE_CRYPTO_ERROR 0x00060000UL |
An internal error was raised and the command did not execute.
Definition at line
274
of file
em_se.h
.
#define SE_RESPONSE_INTERNAL_ERROR 0x00050000UL |
Internal error
Definition at line
272
of file
em_se.h
.
#define SE_RESPONSE_INVALID_COMMAND 0x00010000UL |
Command was not recognized as a valid command, or is not allowed in the current context.
Definition at line
258
of file
em_se.h
.
#define SE_RESPONSE_INVALID_PARAMETER 0x00070000UL |
One of the passed parameters is deemed invalid (e.g. out of bounds).
Definition at line
276
of file
em_se.h
.
Referenced by SE_ackCommand() , SE_getConfigStatusBits() , and SE_getVersion() .
#define SE_RESPONSE_INVALID_SIGNATURE 0x00030000UL |
Signature validation command (e.g. SE_COMMAND_SIGNATURE_VERIFY) failed to verify the given signature as being correct.
Definition at line
268
of file
em_se.h
.
#define SE_RESPONSE_OK 0x00000000UL |
Command executed successfully or signature was successfully validated.
Definition at line
253
of file
em_se.h
.
Referenced by SE_ackCommand() , SE_getConfigStatusBits() , SE_getVersion() , and sl_efp_emu_ldo_enable() .
Typedef Documentation
typedef uint32_t SE_Response_t |
Possible responses to a command
Definition at line
349
of file
em_se.h
.
Function Documentation
bool rootIsOutputMailboxValid | ( | void |
|
) |
Check whether the Root Code Output Mailbox is valid.
- Returns
- True if the Root Code Output Mailbox is valid (magic and checksum OK)
Definition at line
322
of file
em_se.c
.
Referenced by SE_getConfigStatusBits() , SE_getVersion() , and SE_isCommandCompleted() .
SE_Response_t SE_ackCommand | ( | SE_Command_t * |
command
|
) |
Acknowledge and get status and output data of a completed command.
This function acknowledges and gets the status and output data of a completed mailbox command. The mailbox command is acknowledged by inverting all bits in the checksum (XOR with 0xFFFFFFFF). The output data is copied into the linked list of output buffers pointed to in the given command data structure.
- Parameters
-
[in] command
Pointer to a filled-out SE command structure.
- Returns
- One of the SE_RESPONSE return codes.
- Return values
-
SE_RESPONSE_OK
when the command was executed successfully or a signature was successfully verified, SE_RESPONSE_INVALID_COMMAND
when the command ID was not recognized, SE_RESPONSE_AUTHORIZATION_ERROR
when the command is not authorized, SE_RESPONSE_INVALID_SIGNATURE
when signature verification failed, SE_RESPONSE_BUS_ERROR
when a bus error was thrown during the command, e.g. because of conflicting Secure/Non-Secure memory accesses, SE_RESPONSE_CRYPTO_ERROR
on an internal SE failure, or SE_RESPONSE_INVALID_PARAMETER
when an invalid parameter was passed SE_RESPONSE_MAILBOX_INVALID
when mailbox command not done or invalid
Definition at line
559
of file
em_se.c
.
References SE_isCommandCompleted() , SE_RESPONSE_INVALID_PARAMETER , and SE_RESPONSE_OK .
void SE_addDataInput | ( | SE_Command_t * |
command,
|
SE_DataTransfer_t * |
data
|
||
) |
Add input data to a command.
This function adds a buffer of input data to the given SE command structure The buffer gets appended by reference at the end of the list of already added buffers.
- Note
- Note that this function does not copy either the data buffer or the buffer structure, so make sure to keep the data object in scope until the command has been executed by the secure element.
- Parameters
-
[in] command
Pointer to an SE command structure. [in] data
Pointer to a data transfer structure.
Definition at line
133
of file
em_se.c
.
void SE_addDataOutput | ( | SE_Command_t * |
command,
|
SE_DataTransfer_t * |
data
|
||
) |
Add output data to a command.
This function adds a buffer of output data to the given command structure The buffer gets appended by reference at the end of the list of already added buffers.
- Note
- Note that this function does not copy either the data buffer or the buffer structure, so make sure to keep the data object in scope until the command has been executed by the secure element.
- Parameters
-
[in] command
Pointer to an SE command structure. [in] data
Pointer to a data transfer structure.
Definition at line
166
of file
em_se.c
.
void SE_addParameter | ( | SE_Command_t * |
command,
|
uint32_t |
parameter
|
||
) |
Add a parameter to a command.
This function adds a parameter word to the passed command.
- Note
- Make sure to not exceed SE_MAX_PARAMETERS .
- Parameters
-
[in] command
Pointer to a filled-out SE command structure. [in] parameter
Parameter to add.
Definition at line
195
of file
em_se.c
.
References SE_MAX_PARAMETERS .
Referenced by sl_efp_emu_ldo_enable() .
__STATIC_INLINE void SE_disableInterrupt | ( | uint32_t |
flags
|
) |
Disable one or more SE interrupts.
- Parameters
-
[in] flags
SE interrupt sources to disable. Use a bitwise logic OR combination of valid interrupt flags for the Secure Element module (SE_CONFIGURATION_(TX/RX)INTEN).
Definition at line
530
of file
em_se.h
.
__STATIC_INLINE void SE_enableInterrupt | ( | uint32_t |
flags
|
) |
Enable one or more SE interrupts.
- Parameters
-
[in] flags
SE interrupt sources to enable. Use a bitwise logic OR combination of valid interrupt flags for the Secure Element module (SEMAILBOX_CONFIGURATION_TXINTEN or SEMAILBOX_CONFIGURATION_RXINTEN).
Definition at line
548
of file
em_se.h
.
void SE_executeCommand | ( | SE_Command_t * |
command
|
) |
Execute the passed command.
This function starts the execution of the passed command by the secure element. When started, wait for the RXINT interrupt flag, or call SE_waitCommandCompletion to busy-wait. After completion, you have to call SE_readCommandResponse to get the command's execution status.
- Parameters
-
[in] command
Pointer to a filled-out SE command structure.
Definition at line
219
of file
em_se.c
.
References SE_MAX_PARAMETERS .
Referenced by sl_efp_emu_ldo_enable() .
SE_Response_t SE_getConfigStatusBits | ( | uint32_t * |
cfgStatus
|
) |
Get Root Code Configuration Status bits.
This function returns the current Root Code Configuration Status bits
- Parameters
-
[in] cfgStatus
Pointer to location where to copy Configuration Status bits of the root code.
- Returns
- One of the SE_RESPONSE return codes: SE_RESPONSE_OK when the command was executed successfully SE_RESPONSE_INVALID_PARAMETER when an invalid parameter was passed SE_RESPONSE_MAILBOX_INVALID when the mailbox content is invalid
Definition at line
414
of file
em_se.c
.
References rootIsOutputMailboxValid() , SE_RESPONSE_INVALID_PARAMETER , and SE_RESPONSE_OK .
SE_Response_t SE_getVersion | ( | uint32_t * |
version
|
) |
Get current SE version.
This function returns the current root code version
- Parameters
-
[in] version
Pointer to location where to copy the version of root code to.
- Returns
- One of the SE_RESPONSE return codes: SE_RESPONSE_OK when the command was executed successfully SE_RESPONSE_INVALID_PARAMETER when an invalid parameter was passed SE_RESPONSE_MAILBOX_INVALID when the mailbox content is invalid
Definition at line
373
of file
em_se.c
.
References rootIsOutputMailboxValid() , SE_RESPONSE_INVALID_PARAMETER , and SE_RESPONSE_OK .
bool SE_isCommandCompleted | ( | void |
|
) |
Check whether the running command has completed.
This function polls the SE-to-host mailbox interrupt flag.
- Returns
- True if a command has completed and the result is available
Definition at line
447
of file
em_se.c
.
References rootIsOutputMailboxValid() .
Referenced by SE_ackCommand() , SE_readCommandResponse() , SE_readExecutedCommand() , and SE_waitCommandCompletion() .
SE_Response_t SE_readCommandResponse | ( | void |
|
) |
Read the status of the previously executed command.
This function reads the status of the previously executed command.
- Returns
- One of the SE_RESPONSE return codes: SE_RESPONSE_OK when the command was executed successfully or a signature was successfully verified, SE_RESPONSE_INVALID_COMMAND when the command ID was not recognized, SE_RESPONSE_AUTHORIZATION_ERROR when the command is not authorized, SE_RESPONSE_INVALID_SIGNATURE when signature verification failed, SE_RESPONSE_BUS_ERROR when a bus error was thrown during the command, e.g. because of conflicting Secure/Non-Secure memory accesses, SE_RESPONSE_CRYPTO_ERROR on an internal SE failure, or SE_RESPONSE_INVALID_PARAMETER when an invalid parameter was passed SE_RESPONSE_MAILBOX_INVALID when the mailbox content is invalid
Definition at line
513
of file
em_se.c
.
References SE_isCommandCompleted() .
Referenced by sl_efp_emu_ldo_enable() .
uint32_t SE_readExecutedCommand | ( | void |
|
) |
Read the previously executed command.
This function reads the previously executed command.
- Returns
- One of the SE command words. SE_RESPONSE_MAILBOX_INVALID when the mailbox content is invalid.
Definition at line
476
of file
em_se.c
.
References SE_isCommandCompleted() .
__STATIC_INLINE void SE_waitCommandCompletion | ( | void |
|
) |
Wait for completion of the current command.
This function "busy"-waits until the execution of the ongoing instruction has completed.
Definition at line
483
of file
em_se.h
.
References SE_isCommandCompleted() .