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	SE_Command_t

struct	SE_DataTransfer_t

struct	SE_DebugStatus_t

struct	SE_OTPInit_t

struct	SE_Status_t

Macros
#define	SE_COMMAND_AES_CCM_DECRYPT 0x04060000UL

#define	SE_COMMAND_AES_CCM_ENCRYPT 0x04050000UL

#define	SE_COMMAND_AES_CMAC 0x04040000UL

#define	SE_COMMAND_AES_DECRYPT 0x04010000UL

#define	SE_COMMAND_AES_ENCRYPT 0x04000000UL

#define	SE_COMMAND_AES_GCM_DECRYPT 0x04030000UL

#define	SE_COMMAND_AES_GCM_ENCRYPT 0x04020000UL

#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_CREATE_KEY 0x02000000UL

#define	SE_COMMAND_DBG_LOCK_APPLY 0x430C0000

#define	SE_COMMAND_DBG_LOCK_DISABLE_SECURE 0x430E0000

#define	SE_COMMAND_DBG_LOCK_ENABLE_SECURE 0x430D0000

#define	SE_COMMAND_DBG_LOCK_STATUS 0x43110000

#define	SE_COMMAND_DEFAULT (command)

#define	SE_COMMAND_DEVICE_ERASE 0x430F0000

#define	SE_COMMAND_DEVICE_ERASE_DISABLE 0x43100000

#define	SE_COMMAND_DH 0x0E000000UL

#define	SE_COMMAND_DISABLE_TAMPER 0xFD020001UL

#define	SE_COMMAND_ERASE_USER_DATA 0x430A0000UL

#define	SE_COMMAND_GET_CHALLENGE 0xFD000000UL

#define	SE_COMMAND_GET_STATUS 0xFE010000UL

#define	SE_COMMAND_HASH 0x03000000UL

#define	SE_COMMAND_HASHUPDATE 0x03010000UL

#define	SE_COMMAND_HMAC 0x03020000UL

#define	SE_COMMAND_INIT_OTP 0xFF000001UL

#define	SE_COMMAND_INIT_PUBKEY 0xFF070001UL

#define	SE_COMMAND_INIT_PUBKEY_SIGNATURE 0xFF090001UL

#define	SE_COMMAND_JPAKE_GEN_SESSIONKEY 0x0B020000UL

#define	SE_COMMAND_JPAKE_R1_GENERATE 0x0B000000UL

#define	SE_COMMAND_JPAKE_R1_VERIFY 0x0B000100UL

#define	SE_COMMAND_JPAKE_R2_GENERATE 0x0B010000UL

#define	SE_COMMAND_JPAKE_R2_VERIFY 0x0B010100UL

#define	SE_COMMAND_OPEN_DEBUG 0xFD010001UL

#define	SE_COMMAND_OPTION_CERT_BATCH 0x00000200UL

#define	SE_COMMAND_OPTION_CERT_DEVICE 0x00000100UL

#define	SE_COMMAND_OPTION_CERT_FACTORY 0x00000300UL

#define	SE_COMMAND_OPTION_CONTEXT_ADD 0x00000003UL

#define	SE_COMMAND_OPTION_CONTEXT_END 0x00000002UL

#define	SE_COMMAND_OPTION_CONTEXT_START 0x00000001UL

#define	SE_COMMAND_OPTION_CONTEXT_WHOLE 0x00000000UL

#define	SE_COMMAND_OPTION_ERASE_UD 0xDE1E7EADUL

#define	SE_COMMAND_OPTION_HASH_MD5 0x00000100UL

#define	SE_COMMAND_OPTION_HASH_SHA1 0x00000200UL

#define	SE_COMMAND_OPTION_HASH_SHA224 0x00000300UL

#define	SE_COMMAND_OPTION_HASH_SHA256 0x00000400UL

#define	SE_COMMAND_OPTION_MODE_CBC 0x00000200UL

#define	SE_COMMAND_OPTION_MODE_CFB 0x00000400UL

#define	SE_COMMAND_OPTION_MODE_CTR 0x00000300UL

#define	SE_COMMAND_OPTION_MODE_ECB 0x00000100UL

#define	SE_COMMAND_OPTION_MODE_OFB 0x00000500UL

#define	SE_COMMAND_OPTION_MODE_XTS 0x00000800UL

#define	SE_COMMAND_OPTION_PADDING_EMSA_PKCS 0x00000003UL

#define	SE_COMMAND_OPTION_PADDING_NONE 0x00000000UL

#define	SE_COMMAND_OPTION_PADDING_PSS 0x00000004UL

#define	SE_COMMAND_OPTION_READ 0x00000000UL

#define	SE_COMMAND_OPTION_WRITE 0x00000100UL

#define	SE_COMMAND_PROTECTED_REGISTER 0x43210000

#define	SE_COMMAND_READ_CLOCK 0x07020000UL

#define	SE_COMMAND_READ_PUBKEY 0xFF080001UL

#define	SE_COMMAND_READ_PUBKEY_SIGNATURE 0xFF0A0001UL

#define	SE_COMMAND_READ_PUBKEYBOOT 0xFE020001UL

#define	SE_COMMAND_READ_SERIAL 0xFE000000UL

#define	SE_COMMAND_READPUB_KEY 0x02010000UL

#define	SE_COMMAND_ROLL_CHALLENGE 0xFD000100UL

#define	SE_COMMAND_SET_UPGRADEFLAG_HOST 0xFE030001UL

#define	SE_COMMAND_SET_UPGRADEFLAG_SE 0xFE030000UL

#define	SE_COMMAND_SIGNATURE_SIGN 0x06000000UL

#define	SE_COMMAND_SIGNATURE_VERIFY 0x06010000UL

#define	SE_COMMAND_STATUS_HOST_IMAGE 0x43070000UL

#define	SE_COMMAND_STATUS_OTP_VERSION 0x43080100UL

#define	SE_COMMAND_STATUS_SE_IMAGE 0x43040000UL

#define	SE_COMMAND_STATUS_SE_VERSION 0x43080000UL

#define	SE_COMMAND_TRNG_GET_RANDOM 0x07000000UL

#define	SE_COMMAND_WRITE_USER_DATA 0x43090000UL

#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_KEY_TYPE_AUTH 0x00000200UL

#define	SE_KEY_TYPE_BOOT 0x00000100UL

#define	SE_KEY_TYPE_ROOT 0x00000300UL

#define	SE_MAX_PARAMETERS 4U

#define	SE_OTP_MCU_SETTINGS_FLAG_SECURE_BOOT_ANTI_ROLLBACK (1 << 18)

#define	SE_OTP_MCU_SETTINGS_FLAG_SECURE_BOOT_ENABLE (1 << 16)

#define	SE_OTP_MCU_SETTINGS_FLAG_SECURE_BOOT_PAGE_LOCK_FULL (1 << 20)

#define	SE_OTP_MCU_SETTINGS_FLAG_SECURE_BOOT_PAGE_LOCK_NARROW (1 << 19)

#define	SE_OTP_MCU_SETTINGS_FLAG_SECURE_BOOT_VERIFY_CERTIFICATE (1 << 17)

#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_MASK 0x000F0000UL

#define	SE_RESPONSE_OK 0x00000000UL

Typedefs
typedef uint32_t	SE_Response_t

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.

SE_Response_t	SE_debugLockApply (void)
	Enables the debug lock for the part.

SE_Response_t	SE_debugLockStatus ( SE_DebugStatus_t *status)
	Returns the current debug lock configuration.

SE_Response_t	SE_debugSecureDisable (void)
	Disables the secure debug functionality.

SE_Response_t	SE_debugSecureEnable (void)
	Enables the secure debug functionality.

SE_Response_t	SE_deviceErase (void)
	Performs a device mass erase and debug unlock.

SE_Response_t	SE_deviceEraseDisable (void)
	Disabled device erase functionality.

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

SE_Response_t	SE_eraseUserData ()
	Erases User Data section in MTP.

void	SE_executeCommand ( SE_Command_t *command)
	Execute the passed command.

SE_Response_t	SE_getStatus ( SE_Status_t *status)
	Returns the current boot status, versions and system configuration.

SE_Response_t	SE_initOTP ( SE_OTPInit_t *otp_init)
	Initialize SE one-time-programmable (OTP) configuration.

SE_Response_t	SE_initPubkey (uint32_t key_type, void *pubkey, uint32_t numBytes, bool signature)
	Init pubkey or pubkey signature.

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

__STATIC_INLINE SE_Response_t	SE_readCommandResponse (void)
	Read the status of the previously executed command.

SE_Response_t	SE_readPubkey (uint32_t key_type, void *pubkey, uint32_t numBytes, bool signature)
	Read pubkey or pubkey signature.

SE_Response_t	SE_serialNumber (void *serial)
	Read the serial number of the SE module.

__STATIC_INLINE void	SE_waitCommandCompletion (void)
	Wait for completion of the current command.

SE_Response_t	SE_writeUserData (uint32_t offset, void *data, uint32_t numBytes)
	Writes data to User Data section in MTP. Write data must be aligned to word size and contain a number of bytes that is divisable by four.

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 SE_debugLockApply() , SE_debugLockStatus() , SE_debugSecureDisable() , SE_debugSecureEnable() , SE_deviceErase() , SE_deviceEraseDisable() , SE_eraseUserData() , SE_getStatus() , SE_initOTP() , SE_initPubkey() , SE_readPubkey() , SE_serialNumber() , SE_writeUserData() , and sl_efp_emu_ldo_enable() .

#define SE_COMMAND_OPTION_CONTEXT_ADD 0x00000003UL

Add more data input to the algorithm. Need to supply previous context, and get a context back

Definition at line 234 of file em_se.h .

#define SE_COMMAND_OPTION_CONTEXT_END 0x00000002UL

End the algorithm, get the result

Definition at line 231 of file em_se.h .

#define SE_COMMAND_OPTION_CONTEXT_START 0x00000001UL

Start the algorithm, but get a context to later add more data

Definition at line 229 of file em_se.h .

#define SE_COMMAND_OPTION_CONTEXT_WHOLE 0x00000000UL

Run the whole algorithm, all data present

Definition at line 227 of file em_se.h .

#define SE_COMMAND_OPTION_ERASE_UD 0xDE1E7EADUL

Magic paramater for deleting user data

Definition at line 246 of file em_se.h .

Referenced by SE_eraseUserData() .

#define SE_COMMAND_OPTION_HASH_MD5 0x00000100UL

Use MD5 as hash algorithm

Definition at line 188 of file em_se.h .

#define SE_COMMAND_OPTION_HASH_SHA1 0x00000200UL

Use SHA1 as hash algorithm

Definition at line 190 of file em_se.h .

#define SE_COMMAND_OPTION_HASH_SHA224 0x00000300UL

Use SHA224 as hash algorithm

Definition at line 192 of file em_se.h .

#define SE_COMMAND_OPTION_HASH_SHA256 0x00000400UL

Use SHA256 as hash algorithm

Definition at line 194 of file em_se.h .

#define SE_COMMAND_OPTION_MODE_CBC 0x00000200UL

Execute algorithm in CBC mode

Definition at line 207 of file em_se.h .

#define SE_COMMAND_OPTION_MODE_CFB 0x00000400UL

Execute algorithm in CFB mode

Definition at line 211 of file em_se.h .

#define SE_COMMAND_OPTION_MODE_CTR 0x00000300UL

Execute algorithm in CTR mode

Definition at line 209 of file em_se.h .

#define SE_COMMAND_OPTION_MODE_ECB 0x00000100UL

Execute algorithm in ECB mode

Definition at line 205 of file em_se.h .

#define SE_COMMAND_OPTION_MODE_OFB 0x00000500UL

Execute algorithm in OFB mode

Definition at line 213 of file em_se.h .

#define SE_COMMAND_OPTION_MODE_XTS 0x00000800UL

Execute algorithm in XTS mode

Definition at line 215 of file em_se.h .

#define SE_COMMAND_OPTION_PADDING_NONE 0x00000000UL

Padding options for signature functionality.

Definition at line 237 of file em_se.h .

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

Referenced by SE_debugLockStatus() , SE_getStatus() , SE_initOTP() , SE_initPubkey() , SE_readPubkey() , SE_serialNumber() , and SE_writeUserData() .

#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_KEY_TYPE_BOOT 0x00000100UL

Pubkey types

Definition at line 222 of file em_se.h .

Referenced by SE_initOTP() , SE_initPubkey() , and SE_readPubkey() .

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

#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_initOTP() , 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

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 .

Referenced by SE_initOTP() , SE_initPubkey() , and SE_writeUserData() .

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 .

Referenced by SE_debugLockStatus() , SE_getStatus() , SE_readPubkey() , and SE_serialNumber() .

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 SE_eraseUserData() , SE_writeUserData() , and sl_efp_emu_ldo_enable() .

SE_Response_t SE_debugLockApply ( void )

Enables the debug lock for the part.

The debug port will be closed and the only way to open it is through device erase (if enabled) or temporarily through secure debug unlock (if enabled).

Returns: One of the SE_RESPONSE return codes.

Return values

`SE_RESPONSE_OK`	when the command was executed successfully.
`SE_RESPONSE_INTERNAL_ERROR`	there was a problem locking the debug port.

Definition at line 1017 of file em_se.c .

References SE_COMMAND_DEFAULT , SE_executeCommand() , and SE_readCommandResponse() .

SE_Response_t SE_debugLockStatus ( SE_DebugStatus_t * status )

Returns the current debug lock configuration.

Parameters

[out] status The command returns a DebugStatus_t with the current status of the debug configuration.

Returns: One of the SE_RESPONSE return codes.

Return values

`SE_RESPONSE_OK`	when the command was executed successfully.
`SE_RESPONSE_INTERNAL_ERROR`	if there are configuration errors.

Definition at line 983 of file em_se.c .

References SE_DebugStatus_t::debugLockEnabled , SE_DebugStatus_t::deviceEraseEnabled , SE_addDataOutput() , SE_COMMAND_DEFAULT , SE_DATATRANSFER_DEFAULT , SE_executeCommand() , SE_readCommandResponse() , and SE_DebugStatus_t::secureDebugEnabled .

SE_Response_t SE_debugSecureDisable ( void )

Disables the secure debug functionality.

Disables the secure debug functionality that can be used to open a locked debug port.

Returns: One of the SE_RESPONSE return codes.

Return values

`SE_RESPONSE_OK`	when the command was executed successfully.
`SE_RESPONSE_INTERNAL_ERROR`	if there was a problem during execution.

Definition at line 1064 of file em_se.c .

References SE_COMMAND_DEFAULT , SE_executeCommand() , and SE_readCommandResponse() .

SE_Response_t SE_debugSecureEnable ( void )

Enables the secure debug functionality.

Enables the secure debug functionality. This functionality makes it possible to open a locked debug port by signing a cryptographic challenge and using the debug command interface (DCI).

This command can only be executed before the debug port is locked, and after a secure debug public key has been installed in the SE using SE_initPubkey() or the corresponding DCI command.

Returns: One of the SE_RESPONSE return codes.

Return values

`SE_RESPONSE_OK`	when the command was executed successfully.
`SE_RESPONSE_INVALID_COMMAND`	if debug port is locked.
`SE_RESPONSE_INVALID_PARAMETER`	if secure debug certificates are missing.
`SE_RESPONSE_INTERNAL_ERROR`	if there was a problem during execution.

Definition at line 1045 of file em_se.c .

References SE_COMMAND_DEFAULT , SE_executeCommand() , and SE_readCommandResponse() .

SE_Response_t SE_deviceErase ( void )

Performs a device mass erase and debug unlock.

Performs a device mass erase and resets the debug configuration to its initial unlocked state. Only available before SE_deviceEraseDisable or the corresponding DCI command has been executed.

Note: This command clears and verifies the complete flash and ram of the system, excluding the user data pages and one-time programmable commissioning information in the secure element.

Returns: One of the SE_RESPONSE return codes.

Return values

`SE_RESPONSE_OK`	when the command was executed successfully.
`SE_RESPONSE_INVALID_COMMAND`	if device erase is disabled.
`SE_RESPONSE_INTERNAL_ERROR`	if there was a problem during execution.

Definition at line 1092 of file em_se.c .

References SE_COMMAND_DEFAULT , SE_executeCommand() , and SE_readCommandResponse() .

SE_Response_t SE_deviceEraseDisable ( void )

Disabled device erase functionality.

This command disables the device erase command. It does not lock the debug interface to the part, but it is a permanent action for the part. If device erase is disabled and the device is debug locked, there is no way to permanently unlock the part. If secure debug unlock is enabled, secure debug unlock can still be used to temporarily open the debug port.

Warning: This command permanently disables the device erase functionality!

Returns: One of the SE_RESPONSE return codes.

Return values

`SE_RESPONSE_OK`	when the command was executed successfully.
`SE_RESPONSE_INTERNAL_ERROR`	if there was a problem during execution.

Definition at line 1119 of file em_se.c .

References SE_COMMAND_DEFAULT , SE_executeCommand() , and SE_readCommandResponse() .

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

SE_Response_t SE_eraseUserData ( )

Erases User Data section in MTP.

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

Definition at line 680 of file em_se.c .

References SE_addParameter() , SE_COMMAND_DEFAULT , SE_COMMAND_OPTION_ERASE_UD , SE_executeCommand() , and SE_readCommandResponse() .

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 SE_debugLockApply() , SE_debugLockStatus() , SE_debugSecureDisable() , SE_debugSecureEnable() , SE_deviceErase() , SE_deviceEraseDisable() , SE_eraseUserData() , SE_getStatus() , SE_initOTP() , SE_initPubkey() , SE_readPubkey() , SE_serialNumber() , SE_writeUserData() , and sl_efp_emu_ldo_enable() .

SE_Response_t SE_getStatus ( SE_Status_t * status )

Returns the current boot status, versions and system configuration.

Parameters

[out] status SE_Status_t containing current SE status.

Returns: One of the SE_RESPONSE return codes.

Return values

SE_RESPONSE_OK upon command completion. Errors are encoded in the different parts of the returned status object.

Definition at line 703 of file em_se.c .

References SE_Status_t::bootStatus , SE_DebugStatus_t::debugLockEnabled , SE_Status_t::debugStatus , SE_DebugStatus_t::deviceEraseEnabled , SE_Status_t::hostFwVersion , SE_addDataOutput() , SE_COMMAND_DEFAULT , SE_DATATRANSFER_DEFAULT , SE_executeCommand() , SE_readCommandResponse() , SE_Status_t::secureBootEnabled , SE_DebugStatus_t::secureDebugEnabled , and SE_Status_t::seFwVersion .

SE_Response_t SE_initOTP ( SE_OTPInit_t * otp_init )

Initialize SE one-time-programmable (OTP) configuration.

Configuration is performed by setting the desired options in the SE_OTPInit_t structure.

This function can be used to enable secure boot, to configure flash page locking, and to enable anti-rollback protection when using the SE to perform an application upgrade, typically a Gecko bootloader upgrade.

Before secure boot can be enabled, the public key used for secure boot verification must be uploaded using SE_initPubkey() .

Warning: This command can only be executed once per device! When the configuration has been programmed it is not possible to update any of the fields.

Parameters

[in] otp_init SE_OTPInit_t structure containing the SE configuration.

Returns: One of the SE_RESPONSE return codes.

Return values

SE_RESPONSE_OK when the command was executed successfully

Definition at line 900 of file em_se.c .

References SE_OTPInit_t::enableAntiRollback , SE_OTPInit_t::enableSecureBoot , SE_addDataInput() , SE_COMMAND_DEFAULT , SE_DATATRANSFER_DEFAULT , SE_executeCommand() , SE_KEY_TYPE_BOOT , SE_readCommandResponse() , SE_readPubkey() , SE_RESPONSE_OK , SE_OTPInit_t::secureBootPageLockFull , SE_OTPInit_t::secureBootPageLockNarrow , and SE_OTPInit_t::verifySecureBootCertificate .

SE_Response_t SE_initPubkey	(	uint32_t	`key_type,`
		void *	`pubkey,`
		uint32_t	`numBytes,`
		bool	`signature`
	)

Init pubkey or pubkey signature.

Initialize public key stored in the SE, or its corresponding signature. The command can be used to write:

SE_KEY_TYPE_BOOT – public key used to perform secure boot
SE_KEY_TYPE_AUTH – public key used to perform secure debug

Note: These keys can not be overwritten, so this command can only be issued once per key per part.

Parameters

[in]	`key_type`	ID of key type to initialize.
[in]	`pubkey`	Pointer to a buffer that contains the public key or signature. Must be word aligned and have a length of 64 bytes.
[in]	`numBytes`	Length of pubkey buffer (64 bytes).
[in]	`signature`	If true, initialize signature for the specified key type instead of the public key itself.

Returns: One of the SE_RESPONSE return codes.

Return values

`SE_RESPONSE_OK`	when the command was executed successfully
`SE_RESPONSE_TEST_FAILED`	when the pubkey is not set
`SE_RESPONSE_INVALID_PARAMETER`	when an invalid type is passed

Definition at line 844 of file em_se.c .

References SE_addDataInput() , SE_COMMAND_DEFAULT , SE_DATATRANSFER_DEFAULT , SE_executeCommand() , SE_KEY_TYPE_BOOT , and SE_readCommandResponse() .

__STATIC_INLINE 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 469 of file em_se.h .

Referenced by SE_waitCommandCompletion() .

__STATIC_INLINE SE_Response_t SE_readCommandResponse ( void )

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

Definition at line 514 of file em_se.h .

References SE_waitCommandCompletion() .

Referenced by SE_debugLockApply() , SE_debugLockStatus() , SE_debugSecureDisable() , SE_debugSecureEnable() , SE_deviceErase() , SE_deviceEraseDisable() , SE_eraseUserData() , SE_getStatus() , SE_initOTP() , SE_initPubkey() , SE_readPubkey() , SE_serialNumber() , SE_writeUserData() , and sl_efp_emu_ldo_enable() .

SE_Response_t SE_readPubkey	(	uint32_t	`key_type,`
		void *	`pubkey,`
		uint32_t	`numBytes,`
		bool	`signature`
	)

Read pubkey or pubkey signature.

Read out a public key stored in the SE, or its signature. The command can be used to read:

SE_KEY_TYPE_BOOT
SE_KEY_TYPE_AUTH

Parameters

[in]	`key_type`	ID of key type to read.
[out]	`pubkey`	Pointer to a buffer to contain the returned public key. Must be word aligned and have a length of 64 bytes.
[in]	`numBytes`	Length of pubkey buffer (64 bytes).
[in]	`signature`	If true, the function will return the signature programmed for the specified public key instead of the public key itself.

Returns: One of the SE_RESPONSE return codes.

Return values

`SE_RESPONSE_OK`	when the command was executed successfully
`SE_RESPONSE_TEST_FAILED`	when the pubkey is not set
`SE_RESPONSE_INVALID_PARAMETER`	when an invalid type is passed

Definition at line 789 of file em_se.c .

References SE_addDataOutput() , SE_COMMAND_DEFAULT , SE_DATATRANSFER_DEFAULT , SE_executeCommand() , SE_KEY_TYPE_BOOT , and SE_readCommandResponse() .

Referenced by SE_initOTP() .

SE_Response_t SE_serialNumber ( void * serial )

Read the serial number of the SE module.

Parameters

[out] serial Pointer to array of size 16 bytes.

Returns: One of the SE_Response_t return codes.

Return values

`SE_RESPONSE_OK`	when serial number is returned successfully,
`SE_RESPONSE_INTERNAL_ERROR`	if not.

Definition at line 745 of file em_se.c .

References SE_addDataOutput() , SE_COMMAND_DEFAULT , SE_DATATRANSFER_DEFAULT , SE_executeCommand() , and SE_readCommandResponse() .

__STATIC_INLINE void SE_waitCommandCompletion ( void )

Wait for completion of the current command.

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

Definition at line 483 of file em_se.h .

References SE_isCommandCompleted() .

Referenced by SE_readCommandResponse() .

SE_Response_t SE_writeUserData	(	uint32_t	`offset,`
		void *	`data,`
		uint32_t	`numBytes`
	)

Writes data to User Data section in MTP. Write data must be aligned to word size and contain a number of bytes that is divisable by four.

Note: It is recommended to erase the flash page before performing a write.

Parameters

[in]	`offset`	Offset to the flash word to write to. Must be aligned to words.
[in]	`data`	Data to write to flash.
[in]	`numBytes`	Number of bytes to write to flash. NB: Must be divisable by four.

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

Definition at line 646 of file em_se.c .

References SE_addDataInput() , SE_addParameter() , SE_COMMAND_DEFAULT , SE_DATATRANSFER_DEFAULT , SE_executeCommand() , and SE_readCommandResponse() .

SE EMLIB

Detailed Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation

SE
EMLIB