SE - Secure Element#
Secure Element peripheral API.
Abstraction of the Secure Element's mailbox interface.
For series 2 devices with a part number that is xG23 or higher, the following step is necessary for basic operation:
Clock enable:
CMU_ClockEnable(cmuClock_SEMAILBOX, true);
Note
The high-level SE API has been moved to the SE manager, and the implementation in em_se should not be used.
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. SE operations should be performed using the SE manager if possible.
Modules#
Typedefs#
SE DMA transfer descriptor.
SE Command structure.
Possible responses to a command.
Functions#
Add input data to a command.
Add output data to a command.
Add a parameter to a command.
Execute the passed command.
Get current SE version.
Get VSE configuration and status bits.
Get the version number of the OTP from the status field of the output mailbox.
Acknowledge and get status and output data of a completed command.
Check whether the running command has completed.
Read the previously executed command.
Read the status of the previously executed command.
Wait for completion of the current command.
Disable one or more SE interrupts.
Enable one or more SE interrupts.
Check whether the VSE Output Mailbox is valid.
Macros#
Root Code Mailbox is invalid.
Root Code Mailbox magic word.
Response status codes for the Secure Element.
Command executed successfully or signature was successfully validated.
Maximum amount of parameters supported by the hardware FIFO.
Stop datatransfer.
Discard datatransfer.
Realign datatransfer.
Datatransfer Const Address.
Stop Length Mask.
Maximum amount of parameters for largest command in defined command set.
Default initialization of data transfer struct.
Default initialization of command struct.
Typedef Documentation#
SE_DataTransfer_t#
typedef sli_se_datatransfer_t SE_DataTransfer_t
SE DMA transfer descriptor.
Can be linked to each other to provide scatter-gather behavior.
129
of file platform/emlib/inc/em_se.h
SE_Command_t#
typedef sli_se_mailbox_command_t SE_Command_t
SE Command structure.
See
142
of file platform/emlib/inc/em_se.h
SE_Response_t#
typedef sli_se_mailbox_response_t SE_Response_t
Possible responses to a command.
155
of file platform/emlib/inc/em_se.h
Function Documentation#
SE_addDataInput#
void SE_addDataInput (SE_Command_t * command, SE_DataTransfer_t * data)
Add input data to a command.
[in] | command | Pointer to an SE command structure. |
[in] | data | Pointer to a data transfer structure. |
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.
184
of file platform/emlib/src/em_se.c
SE_addDataOutput#
void SE_addDataOutput (SE_Command_t * command, SE_DataTransfer_t * data)
Add output data to a command.
[in] | command | Pointer to an SE command structure. |
[in] | data | Pointer to a data transfer structure. |
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.
217
of file platform/emlib/src/em_se.c
SE_addParameter#
void SE_addParameter (SE_Command_t * command, uint32_t parameter)
Add a parameter to a command.
[in] | command | Pointer to a filled-out SE command structure. |
[in] | parameter | Parameter to add. |
This function adds a parameter word to the passed command.
Note
Make sure to not exceed SE_MAX_PARAMETERS.
246
of file platform/emlib/src/em_se.c
SE_executeCommand#
void SE_executeCommand (SE_Command_t * command)
Execute the passed command.
[in] | command | Pointer to a filled-out SE command structure. |
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.
271
of file platform/emlib/src/em_se.c
SE_getVersion#
SE_Response_t SE_getVersion (uint32_t * version)
Get current SE version.
[in] | version | Pointer to location where to copy the version of VSE to. |
This function returns the current VSE version
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
447
of file platform/emlib/src/em_se.c
SE_getConfigStatusBits#
SE_Response_t SE_getConfigStatusBits (uint32_t * cfgStatus)
Get VSE configuration and status bits.
[out] | cfgStatus | Pointer to location to copy Configuration Status bits into. |
This function returns the current VSE configuration and status bits. The following list explains what the different bits in cfgStatus indicate. A bit value of 1 means enabled, while 0 means disabled:
[0]: Secure boot
[1]: Verify secure boot certificate
[2]: Anti-rollback
[3]: Narrow page lock
[4]: Full page lock The following status bits can be read with VSE versions higher than 1.2.2.
[10]: Debug port lock
[11]: Device erase enabled
[12]: Secure debug enabled
[15]: Debug port register state, 1 if the debug port is locked.
Note
This function will check that the mailbox content is valid before reading the status bits. If the command response has already been read with a call to SE_ackCommand(), the validity check will fail, and the config status bits cannot be read before a reset has occurred.
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
506
of file platform/emlib/src/em_se.c
SE_getOTPVersion#
SE_Response_t SE_getOTPVersion (uint32_t * otpVersion)
Get the version number of the OTP from the status field of the output mailbox.
[out] | otpVersion | Pointer to location to copy OTP version number into. |
This function checks if the OTP version number flag is set in the output mailbox. If it is, the version number is writen to otpVersion pointer location. If not, it returns error response.
Returns
One of the SE_RESPONSE return codes.
Return values
SE_RESPONSE_OK: when the command was executed successfully
545
of file platform/emlib/src/em_se.c
SE_ackCommand#
SE_Response_t SE_ackCommand (SE_Command_t * command)
Acknowledge and get status and output data of a completed command.
[in] | command | Pointer to an SE command structure. |
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.
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
695
of file platform/emlib/src/em_se.c
SE_isCommandCompleted#
bool SE_isCommandCompleted (void )
Check whether the running command has completed.
N/A |
This function polls the SE-to-host mailbox interrupt flag.
Returns
True if a command has completed and the result is available
583
of file platform/emlib/src/em_se.c
SE_readExecutedCommand#
uint32_t SE_readExecutedCommand (void )
Read the previously executed command.
N/A |
This function reads the previously executed command.
Returns
One of the SE command words. SE_RESPONSE_MAILBOX_INVALID when the mailbox content is invalid.
612
of file platform/emlib/src/em_se.c
SE_readCommandResponse#
SE_Response_t SE_readCommandResponse (void )
Read the status of the previously executed command.
N/A |
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
649
of file platform/emlib/src/em_se.c
SE_waitCommandCompletion#
void SE_waitCommandCompletion (void )
Wait for completion of the current command.
N/A |
This function "busy"-waits until the execution of the ongoing instruction has completed.
245
of file platform/emlib/inc/em_se.h
SE_disableInterrupt#
void SE_disableInterrupt (uint32_t flags)
Disable one or more SE interrupts.
[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). |
261
of file platform/emlib/inc/em_se.h
SE_enableInterrupt#
void SE_enableInterrupt (uint32_t flags)
Enable one or more SE interrupts.
[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). |
279
of file platform/emlib/inc/em_se.h
rootIsOutputMailboxValid#
bool rootIsOutputMailboxValid (void )
Check whether the VSE Output Mailbox is valid.
N/A |
Returns
True if the VSE Output Mailbox is valid (magic and checksum OK)
391
of file platform/emlib/src/em_se.c
Macro Definition Documentation#
SE_RESPONSE_MAILBOX_INVALID#
#define SE_RESPONSE_MAILBOX_INVALIDValue:
0x00FE0000UL
Root Code Mailbox is invalid.
87
of file platform/emlib/inc/em_se.h
SE_RESPONSE_MAILBOX_VALID#
#define SE_RESPONSE_MAILBOX_VALIDValue:
0xE5ECC0DEUL
Root Code Mailbox magic word.
89
of file platform/emlib/inc/em_se.h
SE_RESPONSE_MASK#
#define SE_RESPONSE_MASKValue:
0x000F0000UL
Response status codes for the Secure Element.
93
of file platform/emlib/inc/em_se.h
SE_RESPONSE_OK#
#define SE_RESPONSE_OKValue:
0x00000000UL
Command executed successfully or signature was successfully validated.
95
of file platform/emlib/inc/em_se.h
SE_FIFO_MAX_PARAMETERS#
#define SE_FIFO_MAX_PARAMETERSValue:
13U
Maximum amount of parameters supported by the hardware FIFO.
98
of file platform/emlib/inc/em_se.h
SE_DATATRANSFER_STOP#
#define SE_DATATRANSFER_STOPValue:
0x00000001UL
Stop datatransfer.
101
of file platform/emlib/inc/em_se.h
SE_DATATRANSFER_DISCARD#
#define SE_DATATRANSFER_DISCARDValue:
0x40000000UL
Discard datatransfer.
103
of file platform/emlib/inc/em_se.h
SE_DATATRANSFER_REALIGN#
#define SE_DATATRANSFER_REALIGNValue:
0x20000000UL
Realign datatransfer.
105
of file platform/emlib/inc/em_se.h
SE_DATATRANSFER_CONSTADDRESS#
#define SE_DATATRANSFER_CONSTADDRESSValue:
0x10000000UL
Datatransfer Const Address.
107
of file platform/emlib/inc/em_se.h
SE_DATATRANSFER_LENGTH_MASK#
#define SE_DATATRANSFER_LENGTH_MASKValue:
0x0FFFFFFFUL
Stop Length Mask.
109
of file platform/emlib/inc/em_se.h
SE_MAX_PARAMETERS#
#define SE_MAX_PARAMETERSValue:
4U
Maximum amount of parameters for largest command in defined command set.
113
of file platform/emlib/inc/em_se.h
SE_DATATRANSFER_DEFAULT#
#define SE_DATATRANSFER_DEFAULTValue:
Default initialization of data transfer struct.
132
of file platform/emlib/inc/em_se.h
SE_COMMAND_DEFAULT#
#define SE_COMMAND_DEFAULTValue:
Default initialization of command struct.
145
of file platform/emlib/inc/em_se.h