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#

SE_DataTransfer_t

SE_Command_t

Deprecated Functions

Typedefs#

typedef uint32_t

Possible responses to a command.

Functions#

void
writeToFifo(uint32_t value)

Write to FIFO.

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

Check whether the running command has completed.

Read the status of the previously executed command.

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

Maximum amount of parameters supported by the hardware FIFO.

#define

Stop datatransfer.

#define

Discard datatransfer.

#define

Realign datatransfer.

#define

Datatransfer Const Address.

#define

Stop Length Mask.

#define

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

#define
SE_DATATRANSFER_DEFAULT (address, length)

Default initialization of data transfer struct.

#define

Default initialization of command struct.

Typedef Documentation#

SE_Response_t#

typedef uint32_t SE_Response_t

Possible responses to a command.


Definition at line 164 of file platform/emlib/inc/em_se.h

Function Documentation#

writeToFifo#

void writeToFifo (uint32_t value)

Write to FIFO.

Parameters
N/Avalue

Value to write to FIFO


Definition at line 153 of file platform/emlib/src/em_se.c

SE_addDataInput#

void SE_addDataInput (SE_Command_t * command, SE_DataTransfer_t * data)

Add input data to a command.

Parameters
[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.


Definition at line 185 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.

Parameters
[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.


Definition at line 218 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.

Parameters
[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


Definition at line 247 of file platform/emlib/src/em_se.c

SE_executeCommand#

void SE_executeCommand (SE_Command_t * command)

Execute the passed command.

Parameters
[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.


Definition at line 272 of file platform/emlib/src/em_se.c

SE_isCommandCompleted#

bool SE_isCommandCompleted (void )

Check whether the running command has completed.

Parameters
N/A

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 215 of file platform/emlib/inc/em_se.h

SE_readCommandResponse#

SE_Response_t SE_readCommandResponse (void )

Read the status of the previously executed command.

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


Definition at line 238 of file platform/emlib/inc/em_se.h

SE_waitCommandCompletion#

void SE_waitCommandCompletion (void )

Wait for completion of the current command.

Parameters
N/A

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


Definition at line 254 of file platform/emlib/inc/em_se.h

SE_disableInterrupt#

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 270 of file platform/emlib/inc/em_se.h

SE_enableInterrupt#

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 288 of file platform/emlib/inc/em_se.h

Macro Definition Documentation#

SE_RESPONSE_MASK#

#define SE_RESPONSE_MASK
Value:
0x000F0000UL

Response status codes for the Secure Element.


Definition at line 92 of file platform/emlib/inc/em_se.h

SE_RESPONSE_OK#

#define SE_RESPONSE_OK
Value:
0x00000000UL

Command executed successfully or signature was successfully validated.


Definition at line 94 of file platform/emlib/inc/em_se.h

SE_FIFO_MAX_PARAMETERS#

#define SE_FIFO_MAX_PARAMETERS
Value:
13U

Maximum amount of parameters supported by the hardware FIFO.


Definition at line 97 of file platform/emlib/inc/em_se.h

SE_DATATRANSFER_STOP#

#define SE_DATATRANSFER_STOP
Value:
0x00000001UL

Stop datatransfer.


Definition at line 100 of file platform/emlib/inc/em_se.h

SE_DATATRANSFER_DISCARD#

#define SE_DATATRANSFER_DISCARD
Value:
0x40000000UL

Discard datatransfer.


Definition at line 102 of file platform/emlib/inc/em_se.h

SE_DATATRANSFER_REALIGN#

#define SE_DATATRANSFER_REALIGN
Value:
0x20000000UL

Realign datatransfer.


Definition at line 104 of file platform/emlib/inc/em_se.h

SE_DATATRANSFER_CONSTADDRESS#

#define SE_DATATRANSFER_CONSTADDRESS
Value:
0x10000000UL

Datatransfer Const Address.


Definition at line 106 of file platform/emlib/inc/em_se.h

SE_DATATRANSFER_LENGTH_MASK#

#define SE_DATATRANSFER_LENGTH_MASK
Value:
0x0FFFFFFFUL

Stop Length Mask.


Definition at line 108 of file platform/emlib/inc/em_se.h

SE_MAX_PARAMETERS#

#define SE_MAX_PARAMETERS
Value:
4U

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


Definition at line 112 of file platform/emlib/inc/em_se.h

SE_DATATRANSFER_DEFAULT#

#define SE_DATATRANSFER_DEFAULT
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 135 of file platform/emlib/inc/em_se.h

SE_COMMAND_DEFAULT#

#define SE_COMMAND_DEFAULT
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 154 of file platform/emlib/inc/em_se.h