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)
Value:
{ \
(command), /* Given command */ \
NULL, /* No data in */ \
NULL, /* No data out */ \
{ 0, 0, 0, 0 }, /* No parameters */ \
0 /* No parameters */ \
}

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 
)
Value:
{ \
(void*)(address), /* Pointer to data block */ \
(void*)SE_DATATRANSFER_STOP, /* This is the last block by default */ \
(length) | SE_DATATRANSFER_REALIGN /* Add size, use realign by default */ \
}

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]commandPointer to a filled-out SE command structure.
Returns
One of the SE_RESPONSE return codes.
Return values
SE_RESPONSE_OKwhen the command was executed successfully or a signature was successfully verified,
SE_RESPONSE_INVALID_COMMANDwhen the command ID was not recognized,
SE_RESPONSE_AUTHORIZATION_ERRORwhen the command is not authorized,
SE_RESPONSE_INVALID_SIGNATUREwhen signature verification failed,
SE_RESPONSE_BUS_ERRORwhen a bus error was thrown during the command, e.g. because of conflicting Secure/Non-Secure memory accesses,
SE_RESPONSE_CRYPTO_ERRORon an internal SE failure, or
SE_RESPONSE_INVALID_PARAMETERwhen an invalid parameter was passed
SE_RESPONSE_MAILBOX_INVALIDwhen 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]commandPointer to an SE command structure.
[in]dataPointer 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]commandPointer to an SE command structure.
[in]dataPointer 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]commandPointer to a filled-out SE command structure.
[in]parameterParameter 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]flagsSE 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]flagsSE 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]commandPointer 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]cfgStatusPointer 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]versionPointer 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().