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] 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.