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]commandPointer to an SE command structure.
[in]dataPointer 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]commandPointer to an SE command structure.
[in]dataPointer 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]commandPointer to a filled-out SE command structure.
[in]parameterParameter 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_OKwhen the command was executed successfully.
SE_RESPONSE_INTERNAL_ERRORthere 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]statusThe 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_OKwhen the command was executed successfully.
SE_RESPONSE_INTERNAL_ERRORif 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_OKwhen the command was executed successfully.
SE_RESPONSE_INTERNAL_ERRORif 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_OKwhen the command was executed successfully.
SE_RESPONSE_INVALID_COMMANDif debug port is locked.
SE_RESPONSE_INVALID_PARAMETERif secure debug certificates are missing.
SE_RESPONSE_INTERNAL_ERRORif 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_OKwhen the command was executed successfully.
SE_RESPONSE_INVALID_COMMANDif device erase is disabled.
SE_RESPONSE_INTERNAL_ERRORif 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_OKwhen the command was executed successfully.
SE_RESPONSE_INTERNAL_ERRORif 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]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).

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

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_OKwhen the command was executed successfully or a signature was successfully verified,
SE_RESPONSE_INVALID_COMMANDwhen the command ID was not recognized,
SE_RESPONSE_AUTHORIZATION_ERRORwhen the command is not authorized,
SE_RESPONSE_INVALID_SIGNATUREwhen signature verification failed,
SE_RESPONSE_BUS_ERRORwhen a bus error was thrown during the command, e.g. because of conflicting Secure/Non-Secure memory accesses,
SE_RESPONSE_CRYPTO_ERRORon an internal SE failure, or
SE_RESPONSE_INVALID_PARAMETERwhen 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]commandPointer 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]statusSE_Status_t containing current SE status.
Returns
One of the SE_RESPONSE return codes.
Return values
SE_RESPONSE_OKupon 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_initSE_OTPInit_t structure containing the SE configuration.
Returns
One of the SE_RESPONSE return codes.
Return values
SE_RESPONSE_OKwhen 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_typeID of key type to initialize.
[in]pubkeyPointer to a buffer that contains the public key or signature. Must be word aligned and have a length of 64 bytes.
[in]numBytesLength of pubkey buffer (64 bytes).
[in]signatureIf 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_OKwhen the command was executed successfully
SE_RESPONSE_TEST_FAILEDwhen the pubkey is not set
SE_RESPONSE_INVALID_PARAMETERwhen 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:

Parameters
[in]key_typeID of key type to read.
[out]pubkeyPointer to a buffer to contain the returned public key. Must be word aligned and have a length of 64 bytes.
[in]numBytesLength of pubkey buffer (64 bytes).
[in]signatureIf 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_OKwhen the command was executed successfully
SE_RESPONSE_TEST_FAILEDwhen the pubkey is not set
SE_RESPONSE_INVALID_PARAMETERwhen 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]serialPointer to array of size 16 bytes.
Returns
One of the SE_Response_t return codes.
Return values
SE_RESPONSE_OKwhen serial number is returned successfully,
SE_RESPONSE_INTERNAL_ERRORif 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]offsetOffset to the flash word to write to. Must be aligned to words.
[in]dataData to write to flash.
[in]numBytesNumber of bytes to write to flash. NB: Must be divisable by four.
Returns
One of the SE_RESPONSE return codes.
Return values
SE_RESPONSE_OKwhen the command was executed successfully or a signature was successfully verified,
SE_RESPONSE_INVALID_COMMANDwhen the command ID was not recognized,
SE_RESPONSE_AUTHORIZATION_ERRORwhen the command is not authorized,
SE_RESPONSE_INVALID_SIGNATUREwhen signature verification failed,
SE_RESPONSE_BUS_ERRORwhen a bus error was thrown during the command, e.g. because of conflicting Secure/Non-Secure memory accesses,
SE_RESPONSE_CRYPTO_ERRORon an internal SE failure, or
SE_RESPONSE_INVALID_PARAMETERwhen 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().