SE - Secure Element

Description

Secure Element peripheral API.

Abstraction of the Secure Element's mailbox interface.

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
Deprecated Functions.
 

Data Structures

struct  SE_DataTransfer_t
 SE DMA transfer descriptor.
 
struct  SE_Command_t
 SE Command structure to which all commands to the SE must adhere.
 

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.
 

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.
 

Typedefs

typedef uint32_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.

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.

◆ SE_addDataOutput()

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.

◆ SE_addParameter()

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.

◆ SE_executeCommand()

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.

◆ SE_isCommandCompleted()

bool SE_isCommandCompleted ( void  )
inline

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

◆ SE_readCommandResponse()

SE_Response_t SE_readCommandResponse ( void  )
inline

Read the status of the previously executed command.

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  )
inline

Wait for completion of the current command.

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

◆ SE_disableInterrupt()

void SE_disableInterrupt ( uint32_t  flags)
inline

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

◆ SE_enableInterrupt()

void SE_enableInterrupt ( uint32_t  flags)
inline

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

Macro Definition Documentation

◆ SE_RESPONSE_MASK

#define SE_RESPONSE_MASK   0x000F0000UL

Response status codes for the Secure Element.

◆ SE_RESPONSE_OK

#define SE_RESPONSE_OK   0x00000000UL

Command executed successfully or signature was successfully validated.

◆ SE_FIFO_MAX_PARAMETERS

#define SE_FIFO_MAX_PARAMETERS   13U

Maximum amount of parameters supported by the hardware FIFO.

◆ SE_DATATRANSFER_STOP

#define SE_DATATRANSFER_STOP   0x00000001UL

Stop datatransfer.

◆ SE_DATATRANSFER_DISCARD

#define SE_DATATRANSFER_DISCARD   0x40000000UL

Discard datatransfer.

◆ SE_DATATRANSFER_REALIGN

#define SE_DATATRANSFER_REALIGN   0x20000000UL

Realign datatransfer.

◆ SE_DATATRANSFER_CONSTADDRESS

#define SE_DATATRANSFER_CONSTADDRESS   0x10000000UL

Datatransfer Const Address.

◆ SE_DATATRANSFER_LENGTH_MASK

#define SE_DATATRANSFER_LENGTH_MASK   0x0FFFFFFFUL

Stop Length Mask.

◆ SE_MAX_PARAMETERS

#define SE_MAX_PARAMETERS   4U

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

◆ SE_DATATRANSFER_DEFAULT

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

◆ SE_COMMAND_DEFAULT

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

Typedef Documentation

◆ SE_Response_t

typedef uint32_t SE_Response_t

Possible responses to a command.