Utilities#

Device initialisation, debug lock, upgrade functionality, user data...

API for managing the Secure Engine or Root code on a device. Upload and read device configuration.

Modules#

sl_se_cert_size_type_t

sl_se_otp_init_t

sl_se_debug_options_t

sl_se_debug_status_t

sl_se_status_t

Tamper options

Enumerations#

enum
SL_SE_KEY_TYPE_IMMUTABLE_BOOT = 0
SL_SE_KEY_TYPE_IMMUTABLE_AUTH
SL_SE_KEY_TYPE_IMMUTABLE_AES_128
SL_SE_KEY_TYPE_IMMUTABLE_ATTESTATION
SL_SE_KEY_TYPE_IMMUTABLE_SE_ATTESTATION
}

OTP key types.

Typedefs#

typedef uint8_t

SE tamper signal levels.

typedef uint32_t

SE tamper signals.

typedef uint8_t

SE tamper filter timeout period.

typedef uint8_t

Number of tamper counts to trigger the filter signal.

typedef uint8_t

SE certificate types.

typedef uint32_t

SE Debug lock flags.

typedef uint8_t
sl_se_challenge_t[SL_SE_CHALLENGE_SIZE]

SE challenge storage.

Functions#

sl_status_t
sl_se_check_se_image(sl_se_command_context_t *cmd_ctx, void *image_addr)

Validate SE firmware image.

sl_status_t
sl_se_apply_se_image(sl_se_command_context_t *cmd_ctx, void *image_addr)

Apply SE firmware 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.

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.

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.

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.

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.

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.

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.

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.

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.

sl_status_t
sl_se_get_se_version(sl_se_command_context_t *cmd_ctx, uint32_t *version)

Read the SE firmware version.

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.

sl_status_t
sl_se_apply_debug_lock(sl_se_command_context_t *cmd_ctx)

Enables the debug lock for the part.

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.

sl_status_t
sl_se_erase_user_data(sl_se_command_context_t *cmd_ctx)

Erases User Data section in MTP.

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.

sl_status_t
sl_se_get_serialnumber(sl_se_command_context_t *cmd_ctx, void *serial)

Read the serial number of the SE module.

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.

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.

sl_status_t
sl_se_enable_secure_debug(sl_se_command_context_t *cmd_ctx)

Enables the secure debug functionality.

sl_status_t
sl_se_disable_secure_debug(sl_se_command_context_t *cmd_ctx)

Disables the secure debug functionality.

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.

sl_status_t
sl_se_erase_device(sl_se_command_context_t *cmd_ctx)

Performs a device mass erase and debug unlock.

sl_status_t
sl_se_disable_device_erase(sl_se_command_context_t *cmd_ctx)

Disabled device erase functionality.

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.

sl_status_t
sl_se_roll_challenge(sl_se_command_context_t *cmd_ctx)

Invalidate current challenge and make a new challenge.

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.

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.

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.

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.

sl_status_t
sl_se_enter_active_mode(sl_se_command_context_t *cmd_ctx)

Enter SE active mode.

sl_status_t
sl_se_exit_active_mode(sl_se_command_context_t *cmd_ctx)

Exit SE active mode.

Macros#

#define

Default configuration for OTP initialisation structure.

#define

SE Challenge size.

#define

Certificate key size.

#define

Certificate signature size.

#define

Batch ID certificate.

#define

SE ID certificate.

#define

Host ID certificate.

Enumeration Documentation#

sl_se_device_key_type_t#

sl_se_device_key_type_t

OTP key types.

Enumerator
SL_SE_KEY_TYPE_IMMUTABLE_BOOT
SL_SE_KEY_TYPE_IMMUTABLE_AUTH
SL_SE_KEY_TYPE_IMMUTABLE_AES_128
SL_SE_KEY_TYPE_IMMUTABLE_ATTESTATION
SL_SE_KEY_TYPE_IMMUTABLE_SE_ATTESTATION

Definition at line 57 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

Typedef Documentation#

sl_se_tamper_level_t#

typedef uint8_t sl_se_tamper_level_t

SE tamper signal levels.


Definition at line 71 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

sl_se_tamper_signals_t#

typedef uint32_t sl_se_tamper_signals_t

SE tamper signals.


Definition at line 74 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

sl_se_tamper_filter_period_t#

typedef uint8_t sl_se_tamper_filter_period_t

SE tamper filter timeout period.


Definition at line 77 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

sl_se_tamper_filter_threshold_t#

typedef uint8_t sl_se_tamper_filter_threshold_t

Number of tamper counts to trigger the filter signal.


Definition at line 80 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

sl_se_cert_type_t#

typedef uint8_t sl_se_cert_type_t

SE certificate types.


Definition at line 91 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

sl_se_debug_flags_t#

typedef uint32_t sl_se_debug_flags_t

SE Debug lock flags.


Definition at line 157 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

sl_se_challenge_t#

typedef uint8_t sl_se_challenge_t[SL_SE_CHALLENGE_SIZE] [SL_SE_CHALLENGE_SIZE]

SE challenge storage.


Definition at line 301 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

Function Documentation#

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]image_addr

Pointer to SE image to validate.

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


Definition at line 89 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]image_addr

Pointer to SE image to apply.

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


Definition at line 110 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]status

Pointer to 32-bit word where to return upgrade status.

[in]prev_version

Pointer to 32-bit word where to return previous version.

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


Definition at line 131 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]image_addr

Pointer to Host image to validate.

[in]size

Size of Host image to validate.

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


Definition at line 157 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]image_addr

Pointer to Host image to apply.

[in]size

Size of Host image to apply.

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


Definition at line 182 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]status

Pointer to 32-bit word where to return upgrade status.

[in]prev_version

Pointer to 32-bit word where to return previous version.

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


Definition at line 205 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key_type

ID of key type to initialize.

[in]key

Pointer to a buffer that contains the key. Public keys must be word aligned and have a length of 64 bytes. AES-128 keys must be word aligned and have length of 16 bytes.

[in]num_bytes

Length of key buffer in bytes (16 or 64 bytes).

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


Definition at line 242 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key_type

ID of key type to read.

[out]key

Pointer to a buffer to contain the returned public key. Must be word aligned and have a length of 64 bytes.

[in]num_bytes

Length of pubkey buffer (64 bytes).

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


Definition at line 274 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]otp_init

Pointer to OTP initialization structure.

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.


Definition at line 295 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]version

Pointer to uint32_t word where version shall be returned.

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


Definition at line 315 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]otp_settings

Pointer to OTP initialization structure.

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.


Definition at line 334 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]version

Pointer to uint32_t word where version shall be returned.

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


Definition at line 355 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]status

Pointer to sl_se_debug_status_t structure to be filled out with the current status of the debug 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


Definition at line 374 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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


Definition at line 392 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]offset

Offset to the flash word to write to. Must be aligned to words.

[in]data

Data to write to flash.

[in]num_bytes

Number of bytes to write to flash. NB: Must be divisable by four.

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


Definition at line 417 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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


Definition at line 436 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]status

SE_Status_t containing current SE status.

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


Definition at line 456 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]serial

Pointer to array of size 16 bytes.

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


Definition at line 476 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]reset_cause

Pointer to uint32_t word where reset cause shall be returned.

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


Definition at line 496 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]was_tamper_reset

Pointer to bool that indicates if a tamper event occurred. If the cached value is 0 this will be false, true otherwise.

[out]reset_cause

Pointer to a uint32_t where the cached reset cause value should be returned.

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


Definition at line 524 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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


Definition at line 546 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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


Definition at line 563 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]debug_options

Pointer to debug options structure.

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


Definition at line 584 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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.


Definition at line 609 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

sl_se_disable_device_erase#

sl_status_t sl_se_disable_device_erase (sl_se_command_context_t * cmd_ctx)

Disabled device erase functionality.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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


Definition at line 632 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[out]challenge

SE challenge storage.

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


Definition at line 653 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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


Definition at line 671 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]cert

Certificate for debug unlock and signed challenge.

[in]len

Length of certificate in number of bytes.

[in]debug_options

Debug options to open/unlock.

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


Definition at line 696 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]cert

Certificate for disabling tamper and signed challenge.

[in]len

Length of certificate in number of bytes.

[in]tamper_signals

Tamper signals to disable. Each signal represented by a bit.

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


Definition at line 726 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[inout]cert_size

Size of the certificates stored in SE.

Returns

  • Status code, sl_status.h.


Definition at line 746 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]cert_type

Type of the certificate stored in SE.

[inout]cert

Buffer to read certificate.

[in]num_bytes

Length of certificate in number of bytes.

Returns

  • Status code, sl_status.h.


Definition at line 768 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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


Definition at line 794 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

sl_se_exit_active_mode#

sl_status_t sl_se_exit_active_mode (sl_se_command_context_t * cmd_ctx)

Exit SE active mode.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

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


Definition at line 812 of file platform/security/sl_component/se_manager/inc/sl_se_manager_util.h

Macro Definition Documentation#

SL_SE_OTP_INIT_DEFAULT#

#define SL_SE_OTP_INIT_DEFAULT
Value:
{ \
.enable_secure_boot = false, \
.verify_secure_boot_certificate = false, \
.enable_anti_rollback = false, \
.secure_boot_page_lock_narrow = false, \
.secure_boot_page_lock_full = false, \
.tamper_levels = { 0 }, \
.tamper_filter_period = SL_SE_TAMPER_FILTER_PERIOD_2MIN, \
.tamper_filter_threshold = SL_SE_TAMPER_FILTER_THRESHOLD_4, \
.tamper_flags = 0, \
.tamper_reset_threshold = 5 \
}

Default configuration for OTP initialisation structure.


Definition at line 68 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_CHALLENGE_SIZE#

#define SL_SE_CHALLENGE_SIZE
Value:
16

SE Challenge size.


Definition at line 254 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_CERT_KEY_SIZE#

#define SL_SE_CERT_KEY_SIZE
Value:
64

Certificate key size.


Definition at line 257 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_CERT_SIGN_SIZE#

#define SL_SE_CERT_SIGN_SIZE
Value:
64

Certificate signature size.


Definition at line 260 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_CERT_BATCH#

#define SL_SE_CERT_BATCH
Value:
0x01

Batch ID certificate.


Definition at line 263 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_CERT_DEVICE_SE#

#define SL_SE_CERT_DEVICE_SE
Value:
0x02

SE ID certificate.


Definition at line 265 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_CERT_DEVICE_HOST#

#define SL_SE_CERT_DEVICE_HOST
Value:
0x03

Host ID certificate.


Definition at line 267 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h