Utilities#

sl_se_device_key_type_t#

sl_se_device_key_type_t

OTP key types.

sl_se_tamper_level_t#

typedef uint8_t sl_se_tamper_level_t

SE tamper signal levels.

sl_se_tamper_signals_t#

typedef uint32_t sl_se_tamper_signals_t

SE tamper signals.

sl_se_tamper_filter_period_t#

typedef uint8_t sl_se_tamper_filter_period_t

SE tamper filter timeout period.

sl_se_tamper_filter_threshold_t#

typedef uint8_t sl_se_tamper_filter_threshold_t

Number of tamper counts to trigger the filter signal.

sl_se_cert_type_t#

typedef uint8_t sl_se_cert_type_t

SE certificate types.

sl_se_debug_flags_t#

typedef uint32_t sl_se_debug_flags_t

SE Debug lock flags.

sl_se_challenge_t#

typedef uint8_t sl_se_challenge_t[SL_SE_CHALLENGE_SIZE] [SL_SE_CHALLENGE_SIZE]

SE challenge storage.

sl_se_check_se_image#

sl_status_t sl_se_check_se_image (sl_se_command_context_t * cmd_ctx, void * image_addr)

Validate SE firmware image.

Validate SE firmware image located at given address. This function is typically used before calling sl_se_apply_se_image.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_apply_se_image#

sl_status_t sl_se_apply_se_image (sl_se_command_context_t * cmd_ctx, void * image_addr)

Apply SE firmware image.

Apply SE firmware image located at given address.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_get_upgrade_status_se_image#

sl_status_t sl_se_get_upgrade_status_se_image (sl_se_command_context_t * cmd_ctx, uint32_t * status, uint32_t * prev_version)

Get upgrade status of SE firmware image.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_check_host_image#

sl_status_t sl_se_check_host_image (sl_se_command_context_t * cmd_ctx, void * image_addr, uint32_t size)

Validate Host firmware image.

Validate Host firmware image located at given address. This function is typically used before calling sl_se_apply_host_image.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_apply_host_image#

sl_status_t sl_se_apply_host_image (sl_se_command_context_t * cmd_ctx, void * image_addr, uint32_t size)

Apply Host firmware image.

Apply Host firmware image located at given address.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_get_upgrade_status_host_image#

sl_status_t sl_se_get_upgrade_status_host_image (sl_se_command_context_t * cmd_ctx, uint32_t * status, uint32_t * prev_version)

Get upgrade status of Host firmware image.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_init_otp_key#

sl_status_t sl_se_init_otp_key (sl_se_command_context_t * cmd_ctx, sl_se_device_key_type_t key_type, void * key, uint32_t num_bytes)

Initialize key to be stored in the SE OTP flash.

Initialize key stored in the SE. The command can be used to write (sl_se_device_key_type_t):

• SL_SE_KEY_TYPE_IMMUTABLE_BOOT

• SL_SE_KEY_TYPE_IMMUTABLE_AUTH

• SL_SE_KEY_TYPE_IMMUTABLE_AES_128

Note

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

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_read_pubkey#

sl_status_t sl_se_read_pubkey (sl_se_command_context_t * cmd_ctx, sl_se_device_key_type_t key_type, void * key, uint32_t num_bytes)

Read a public key stored in the SE.

Read out a public key stored in the SE. The command can be used to read (sl_se_device_key_type_t):

• SL_SE_KEY_TYPE_IMMUTABLE_BOOT

• SL_SE_KEY_TYPE_IMMUTABLE_AUTH

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_init_otp#

sl_status_t sl_se_init_otp (sl_se_command_context_t * cmd_ctx, sl_se_otp_init_t * otp_init)

Initialize SE OTP configuration.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

• SL_STATUS_ABORT: when the operation is not attempted.

sl_se_get_otp_version#

sl_status_t sl_se_get_otp_version (sl_se_command_context_t * cmd_ctx, uint32_t * version)

Read the OTP firmware version of the SE module.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_CREDENTIALS: when the command is not authorized

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_read_otp#

sl_status_t sl_se_read_otp (sl_se_command_context_t * cmd_ctx, sl_se_otp_init_t * otp_settings)

Read SE OTP configuration.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_COMMAND: if OTP configuration isn't initialized

• SL_STATUS_ABORT: when the operation is not attempted.

sl_se_get_se_version#

sl_status_t sl_se_get_se_version (sl_se_command_context_t * cmd_ctx, uint32_t * version)

Read the SE firmware version.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_OWNERSHIP: when the ownership is already taken

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_CREDENTIALS: when the command is not authorized

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_get_debug_lock_status#

sl_status_t sl_se_get_debug_lock_status (sl_se_command_context_t * cmd_ctx, sl_se_debug_status_t * status)

Returns the current debug lock configuration.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_apply_debug_lock#

sl_status_t sl_se_apply_debug_lock (sl_se_command_context_t * cmd_ctx)

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 following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

sl_se_write_user_data#

sl_status_t sl_se_write_user_data (sl_se_command_context_t * cmd_ctx, uint32_t offset, void * data, uint32_t num_bytes)

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.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_CREDENTIALS: when the command is not authorized

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_erase_user_data#

sl_status_t sl_se_erase_user_data (sl_se_command_context_t * cmd_ctx)

Erases User Data section in MTP.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_CREDENTIALS: when the command is not authorized

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_get_status#

sl_status_t sl_se_get_status (sl_se_command_context_t * cmd_ctx, sl_se_status_t * status)

Returns the current boot status, versions and system configuration.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: upon command completion. Errors are encoded in the different parts of the returned status object.

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_CREDENTIALS: when the command is not authorized

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_get_serialnumber#

sl_status_t sl_se_get_serialnumber (sl_se_command_context_t * cmd_ctx, void * serial)

Read the serial number of the SE module.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_CREDENTIALS: when the command is not authorized

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_get_reset_cause#

sl_status_t sl_se_get_reset_cause (sl_se_command_context_t * cmd_ctx, uint32_t * reset_cause)

Read the EMU->RSTCAUSE after a tamper reset.

This function should be called if EMU->RSTCAUSE has been cleared upon boot.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

sl_se_get_tamper_reset_cause#

sl_status_t sl_se_get_tamper_reset_cause (sl_se_command_context_t * cmd_ctx, bool * was_tamper_reset, uint32_t * reset_cause)

Read the latest cached tamper reset cause.

The returned value is the index of the tamper source that caused a reset. Requires SE version 2.2.1 or above.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_PARAMETER: when cmd_ctx or reset_cause is NULL

sl_se_enable_secure_debug#

sl_status_t sl_se_enable_secure_debug (sl_se_command_context_t * cmd_ctx)

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 following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

sl_se_disable_secure_debug#

sl_status_t sl_se_disable_secure_debug (sl_se_command_context_t * cmd_ctx)

Disables the secure debug functionality.

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

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

sl_se_set_debug_options#

sl_status_t sl_se_set_debug_options (sl_se_command_context_t * cmd_ctx, const sl_se_debug_options_t * debug_options)

Set debug options.

This function makes it possible to configure the Trust-Zone access permissions of the debug interface. For details please refer to sl_se_debug_options_t.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

sl_se_erase_device#

sl_status_t sl_se_erase_device (sl_se_command_context_t * cmd_ctx)

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

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_COMMAND: if device erase is disabled.

sl_se_disable_device_erase#

sl_status_t sl_se_disable_device_erase (sl_se_command_context_t * cmd_ctx)

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.

Warnings

• This command permanently disables the device erase functionality!

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

sl_se_get_challenge#

sl_status_t sl_se_get_challenge (sl_se_command_context_t * cmd_ctx, sl_se_challenge_t challenge)

Request challenge from SE which can be used to open debug access.

This command requests a challenge (16 bytes) which can be used to generate a certificate in order to open debug access, sl_se_open_debug.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_roll_challenge#

sl_status_t sl_se_roll_challenge (sl_se_command_context_t * cmd_ctx)

Invalidate current challenge and make a new challenge.

This command requests the SE to invalidate it's current challenge (16bytes) and generate a new challenge.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

sl_se_open_debug#

sl_status_t sl_se_open_debug (sl_se_command_context_t * cmd_ctx, void * cert, uint32_t len, const sl_se_debug_options_t * debug_options)

Unlock debug access using certificate and signed challenge.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_CREDENTIALS: when the command is not authorized

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_disable_tamper#

sl_status_t sl_se_disable_tamper (sl_se_command_context_t * cmd_ctx, void * cert, uint32_t len, sl_se_tamper_signals_t tamper_signals)

Temporarily disable tamper configuration using certificate and signed challenge.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_OPERATION: when the SE command ID is not recognized

• SL_STATUS_INVALID_CREDENTIALS: when the command is not authorized

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

sl_se_read_cert_size#

sl_status_t sl_se_read_cert_size (sl_se_command_context_t * cmd_ctx, sl_se_cert_size_type_t * cert_size)

Read size of stored certificates in SE.

Returns

• Status code, sl_status.h.

sl_se_read_cert#

sl_status_t sl_se_read_cert (sl_se_command_context_t * cmd_ctx, sl_se_cert_type_t cert_type, void * cert, uint32_t num_bytes)

Read stored certificates in SE.

Returns

• Status code, sl_status.h.

sl_se_enter_active_mode#

sl_status_t sl_se_enter_active_mode (sl_se_command_context_t * cmd_ctx)

Enter SE active mode.

SE will enter active mode. This will ensure SE is not powered down between operations, at the expense of increased power consumption.

Warnings

• Active mode will prevent entry to EM2/3/4. To allow energy mode entry, exit active mode through sl_se_exit_active_mode().

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

• SL_STATUS_COMMAND_IS_INVALID: when already in active mode

sl_se_exit_active_mode#

sl_status_t sl_se_exit_active_mode (sl_se_command_context_t * cmd_ctx)

Exit SE active mode.

SE will exit active mode.

Returns

• One of the following sl_status_t codes:

Return values

• SL_STATUS_OK: when the command was executed successfully

• SL_STATUS_INVALID_PARAMETER: when an invalid parameter was passed

• SL_STATUS_COMMAND_IS_INVALID: when already not in active mode

SL_SE_OTP_INIT_DEFAULT#

#define SL_SE_OTP_INIT_DEFAULT

Default configuration for OTP initialisation structure.

SL_SE_CHALLENGE_SIZE#

#define SL_SE_CHALLENGE_SIZE

16

SE Challenge size.

SL_SE_CERT_KEY_SIZE#

#define SL_SE_CERT_KEY_SIZE

64

Certificate key size.

SL_SE_CERT_SIGN_SIZE#

#define SL_SE_CERT_SIGN_SIZE

64

Certificate signature size.

SL_SE_CERT_BATCH#

#define SL_SE_CERT_BATCH

0x01

Batch ID certificate.

SL_SE_CERT_DEVICE_SE#

#define SL_SE_CERT_DEVICE_SE

0x02

SE ID certificate.

SL_SE_CERT_DEVICE_HOST#

#define SL_SE_CERT_DEVICE_HOST

0x03

Host ID certificate.