Description

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

SE_Response_t	SE_getVersion (uint32_t *version)
	Get current SE version.

SE_Response_t	SE_getConfigStatusBits (uint32_t *cfgStatus)
	Get VSE configuration and status bits.

SE_Response_t	SE_getOTPVersion (uint32_t *otpVersion)
	Get the version number of the OTP from the status field of the output mailbox.

SE_Response_t	SE_ackCommand ( SE_Command_t *command)
	Acknowledge and get status and output data of a completed command.

bool	SE_isCommandCompleted (void)
	Check whether the running command has completed.

uint32_t	SE_readExecutedCommand (void)
	Read the previously executed command.

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.

bool	rootIsOutputMailboxValid (void)
	Check whether the VSE Output Mailbox is valid.

Macros
#define	SE_RESPONSE_MAILBOX_INVALID 0x00FE0000UL
	Root Code Mailbox is invalid.

#define	SE_RESPONSE_MAILBOX_VALID 0xE5ECC0DEUL
	Root Code Mailbox magic word.

#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]	`command`	Pointer to an SE command structure.
[in]	`data`	Pointer 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]	`command`	Pointer to an SE command structure.
[in]	`data`	Pointer 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]	`command`	Pointer to a filled-out SE command structure.
[in]	`parameter`	Parameter 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] command Pointer to a filled-out SE command structure.

◆ SE_getVersion()

SE_Response_t SE_getVersion ( uint32_t * version )

Get current SE version.

This function returns the current VSE version

Parameters

[in] version Pointer to location where to copy the version of VSE 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

◆ SE_getConfigStatusBits()

SE_Response_t SE_getConfigStatusBits ( uint32_t * cfgStatus )

Get VSE configuration and status bits.

This function returns the current VSE configuration and status bits. The following list explains what the different bits in cfgStatus indicate. A bit value of 1 means enabled, while 0 means disabled:

[0]: Secure boot
[1]: Verify secure boot certificate
[2]: Anti-rollback
[3]: Narrow page lock
[4]: Full page lock The following status bits can be read with VSE versions higher than 1.2.2.
[10]: Debug port lock
[11]: Device erase enabled
[12]: Secure debug enabled
[15]: Debug port register state, 1 if the debug port is locked.

Parameters

[out] cfgStatus Pointer to location to copy Configuration Status bits into.

Note: This function will check that the mailbox content is valid before reading the status bits. If the command response has already been read with a call to SE_ackCommand() , the validity check will fail, and the config status bits cannot be read before a reset has occurred.

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

◆ SE_getOTPVersion()

SE_Response_t SE_getOTPVersion ( uint32_t * otpVersion )

Get the version number of the OTP from the status field of the output mailbox.

This function checks if the OTP version number flag is set in the output mailbox. If it is, the version number is writen to otpVersion pointer location. If not, it returns error response.

Parameters

[out] otpVersion Pointer to location to copy OTP version number into.

Returns: One of the SE_RESPONSE return codes.

Return values

SE_RESPONSE_OK when the command was executed successfully

◆ SE_ackCommand()

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 an 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

◆ SE_isCommandCompleted()

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

◆ SE_readExecutedCommand()

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.

◆ SE_readCommandResponse()

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

◆ 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] 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 )

inline

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

◆ rootIsOutputMailboxValid()

bool rootIsOutputMailboxValid ( void )

Check whether the VSE Output Mailbox is valid.

Returns: True if the VSE Output Mailbox is valid (magic and checksum OK)

Macro Definition Documentation

◆ SE_RESPONSE_MAILBOX_INVALID

#define SE_RESPONSE_MAILBOX_INVALID 0x00FE0000UL

Root Code Mailbox is invalid.

◆ SE_RESPONSE_MAILBOX_VALID

#define SE_RESPONSE_MAILBOX_VALID 0xE5ECC0DEUL

Root Code Mailbox magic word.

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

SE - Secure Element

Description

Modules

Data Structures

Functions

Macros

Typedefs

Function Documentation

◆ SE_addDataInput()

◆ SE_addDataOutput()

◆ SE_addParameter()

◆ SE_executeCommand()

◆ SE_getVersion()

◆ SE_getConfigStatusBits()

◆ SE_getOTPVersion()

◆ SE_ackCommand()

◆ SE_isCommandCompleted()

◆ SE_readExecutedCommand()

◆ SE_readCommandResponse()

◆ SE_waitCommandCompletion()

◆ SE_disableInterrupt()

◆ SE_enableInterrupt()

◆ rootIsOutputMailboxValid()

Macro Definition Documentation

◆ SE_RESPONSE_MAILBOX_INVALID

◆ SE_RESPONSE_MAILBOX_VALID

◆ SE_RESPONSE_MASK

◆ SE_RESPONSE_OK

◆ SE_FIFO_MAX_PARAMETERS

◆ SE_DATATRANSFER_STOP

◆ SE_DATATRANSFER_DISCARD

◆ SE_DATATRANSFER_REALIGN

◆ SE_DATATRANSFER_CONSTADDRESS

◆ SE_DATATRANSFER_LENGTH_MASK

◆ SE_MAX_PARAMETERS

◆ SE_DATATRANSFER_DEFAULT

◆ SE_COMMAND_DEFAULT

Typedef Documentation

◆ SE_Response_t