SEEMLIB

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_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_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   0x43070001UL
 
#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_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 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 334 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(), and SE_writeUserData().

#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 243 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:
{ \
(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 315 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 293 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 289 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 258 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 265 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 269 of file em_se.h.

#define SE_RESPONSE_INTERNAL_ERROR   0x00050000UL

Internal error

Definition at line 267 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 253 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 271 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 263 of file em_se.h.

#define SE_RESPONSE_OK   0x00000000UL

Command executed successfully or signature was successfully validated.

Definition at line 248 of file em_se.h.

Referenced by SE_initOTP().

Typedef Documentation

typedef uint32_t SE_Response_t

Possible responses to a command

Definition at line 344 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 132 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 165 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 194 of file em_se.c.

References SE_MAX_PARAMETERS.

Referenced by SE_eraseUserData(), and SE_writeUserData().

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 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 922 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 890 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 965 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 that can be used to open a locked debug port through the Get challenge and Open debug commands. 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.

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 946 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 DEVICE_ERASE_DISABLE 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 993 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 1020 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 509 of file em_se.h.

References SEMAILBOX_HOST.

__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 527 of file em_se.h.

References SEMAILBOX_HOST.

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 616 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 218 of file em_se.c.

References SE_MAX_PARAMETERS, SEMAILBOX_HOST, SEMAILBOX_TX_STATUS_TXINT, and SYSCFG.

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

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 639 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 OTP configuration.

Returns
One of the SE_RESPONSE return codes.
Return values
SE_RESPONSE_OKwhen the command was executed successfully

Definition at line 817 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, 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 signature. The command can be used to write:

  • SE_KEY_TYPE_BOOT
  • SE_KEY_TYPE_AUTH
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 requested key type instead of the public key.
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 780 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 448 of file em_se.h.

References SEMAILBOX_HOST, and SEMAILBOX_RX_STATUS_RXINT.

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

References SE_waitCommandCompletion(), and SEMAILBOX_HOST.

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

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_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, read signature for the requested key type instead of the public key.
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 725 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 681 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 462 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 582 of file em_se.c.

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