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#

Deprecated Functions

Typedefs#

typedef sli_se_datatransfer_t

SE_DataTransfer_t

SE DMA transfer descriptor.

typedef sli_se_mailbox_command_t

SE_Command_t

SE Command structure.

typedef sli_se_mailbox_response_t

SE_Response_t

Possible responses to a command.

Functions#

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.

void

SE_executeCommand(SE_Command_t *command)

Execute the passed command.

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.

void

SE_waitCommandCompletion(void)

Wait for completion of the current command.

void

SE_disableInterrupt(uint32_t flags)

Disable one or more SE interrupts.

void

SE_enableInterrupt(uint32_t flags)

Enable one or more SE interrupts.

void

writeToFifo(uint32_t value)

Write to FIFO.

Macros#

#define

SE_RESPONSE_MASK 0x000F0000UL

Response status codes for the Secure Element.

#define

SE_RESPONSE_OK 0x00000000UL

Command executed successfully or signature was successfully validated.

#define

SE_FIFO_MAX_PARAMETERS 13U

Maximum amount of parameters supported by the hardware FIFO.

#define

SE_DATATRANSFER_STOP 0x00000001UL

Stop datatransfer.

#define

SE_DATATRANSFER_DISCARD 0x40000000UL

Discard datatransfer.

#define

SE_DATATRANSFER_REALIGN 0x20000000UL

Realign datatransfer.

#define

SE_DATATRANSFER_CONSTADDRESS 0x10000000UL

Datatransfer Const Address.

#define

SE_DATATRANSFER_LENGTH_MASK 0x0FFFFFFFUL

Stop Length Mask.

#define

SE_MAX_PARAMETERS 4U

Maximum amount of parameters for largest command in defined command set.

#define

SE_DATATRANSFER_DEFAULT (address, length)

Default initialization of data transfer struct.

#define

SE_COMMAND_DEFAULT (command)

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.

SE_Command_t#

typedef sli_se_mailbox_command_t SE_Command_t

SE Command structure.

See

SE_Response_t#

typedef sli_se_mailbox_response_t SE_Response_t

Possible responses to a command.

Function Documentation#

SE_addDataInput#

void SE_addDataInput (SE_Command_t * command, SE_DataTransfer_t * data)

Add input data to a command.

Parameters

Type	Direction	Argument Name	Description
SE_Command_t *	[in]	command	Pointer to an SE command structure.
SE_DataTransfer_t *	[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.

SE_addDataOutput#

void SE_addDataOutput (SE_Command_t * command, SE_DataTransfer_t * data)

Add output data to a command.

Parameters

Type	Direction	Argument Name	Description
SE_Command_t *	[in]	command	Pointer to an SE command structure.
SE_DataTransfer_t *	[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.

SE_addParameter#

void SE_addParameter (SE_Command_t * command, uint32_t parameter)

Add a parameter to a command.

Parameters

Type	Direction	Argument Name	Description
SE_Command_t *	[in]	command	Pointer to a filled-out SE command structure.
uint32_t	[in]	parameter	Parameter to add.

This function adds a parameter word to the passed command.

Note

Make sure to not exceed SE_MAX_PARAMETERS.

SE_executeCommand#

void SE_executeCommand (SE_Command_t * command)

Execute the passed command.

Parameters

Type	Direction	Argument Name	Description
SE_Command_t *	[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.

SE_isCommandCompleted#

bool SE_isCommandCompleted (void )

Check whether the running command has completed.

Parameters

Type	Direction	Argument Name	Description
void	N/A

This function polls the SE-to-host mailbox interrupt flag.

Returns

True if a command has completed and the result is available

SE_readCommandResponse#

SE_Response_t SE_readCommandResponse (void )

Read the status of the previously executed command.

Parameters

Type	Direction	Argument Name	Description
void	N/A

This function reads the status of the previously executed command.

Note

The command response needs to be read for every executed command, and can only be read once per executed command (FIFO behavior).

Returns

One of the SE_RESPONSE return codes: SE_RESPONSE_OK when the command was executed successfully or a signature was successfully verified.

SE_waitCommandCompletion#

void SE_waitCommandCompletion (void )

Wait for completion of the current command.

Parameters

Type	Direction	Argument Name	Description
void	N/A

This function "busy"-waits until the execution of the ongoing instruction has completed.

SE_disableInterrupt#

void SE_disableInterrupt (uint32_t flags)

Disable one or more SE interrupts.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[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).

SE_enableInterrupt#

void SE_enableInterrupt (uint32_t flags)

Enable one or more SE interrupts.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[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).

writeToFifo#

void writeToFifo (uint32_t value)

Write to FIFO.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	value	Value to write to FIFO