Description

Silicon Labs Secure Element Manager.

Note

The APIs are thread-safe.

Introduction

The Secure Element (SE) Manager provides thread-safe APIs for the Secure Element's mailbox interface. The SE Manager will use the SE hardware peripherals to accelerate cryptographic operations.

Functionality

The functionality of the SE Manager includes

• Secure key storage ( Key handling )
  • Key wrapping
  • Storing keys in the SE volatile storage
  • Using key by reference
• Configuration of tamper responses ( Utilities )
  • The available signals include core hard-fault, glitch detectors, PRS, and failed authenticated commands, while the responses vary from triggering an interrupt to the hardware autonomously erasing the one-time-programmable (OTP) memory
• Block ciphers ( Cipher )
  • Supports AES-ECB, AES-CBC, AES-CFB128, AES-CFB8, AES-CTR, AES-CCM, AES-GCM, CMAC, HMAC and ChaCha20/Poly1305
  • The cipher operations can be performed using plaintext keys, wrapped keys or referencing a key in the SE
  • Streaming operations are supported for AES-GCM and CMAC
• Block and streaming hash operations ( Hashing )
  • Supports SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512
• True Random Number Generator ( Entropy )
  • Hardware block inside the SE used for generating random numbers. Can be used as a source of entropy, or to securely generate keys inside the SE
• Elliptic Curve Signature operation ( Signature )
  • ECDSA and EDDSA
• Key agreement ( Key derivation )
  • Perform Elliptic Curve Diffie-Hellman and J-PAKE key agreement operations inside the SE
• Key derivation functions ( Key derivation )
  • Perform HKDF and PBKDF2 key derivation functions inside the SE
• Device configuration and utilities ( Utilities )
  • Write to user data stored inside the SE
  • Configuration of debug locks
  • Configuration of secure boot
  • Configuration of flash lock
  • Read SE OTP contents
  • Read SE firmware version
  • Read provisioned certificates
• Multi-thread safe APIs for MicriumOS and FreeRTOS

For a full overview of the available APIs, see Secure Element Manager .

Key Storage and Use of SE Wrapped Keys

The way keys are stored and operated on depends on the options set in the key descriptor used ( sl_se_key_descriptor_t ). Each key descriptor is initialized with a storage location, a key type, and length of the key (some key types have a known length, and it is not required to be set). The storage location can either be application memory or inside the SE, for more details, see sl_se_storage_method_t . Depending on the use-case, the key descriptors will also store the pointer to a key and an SE key slot, see sl_se_key_slot_t for the list of available internal SE key slots.

For more information on the key handling APIs see Key handling .

Supported Key Types

Symmetric keys

• AES-128 (16 bytes)
• AES-192 (24 bytes)
• AES-256 (32 bytes)
• ChaCha20 (32 bytes)

Asymmetric keys for ECC

• NIST P-192
• NIST P-256
• NIST P-384
• NIST P-521
• Curve25519
• Curve448

Custom Weierstrass Prime curves are also supported ( sl_se_custom_weierstrass_prime_domain_t ).

Example Usage of Keys

Tamper

The Secure Element (SE) tamper module connects a number of hardware and software-driven tamper signals to a set of configurable hardware and software responses. This can be used to program the device to automatically respond to external events that could signal that someone is trying to tamper with the device, and very rapidly remove secrets stored in the SE. The available tamper signals range from signals based on failed authentication and secure boot to specialized glitch detectors. When any of these signals fire, the tamper block can be configured to trigger several different responses, ranging from triggering an interrupt to erasing the one-time-programmable (OTP) memory, removing all SE secrets and resulting in a permanently destroyed device.

A tamper signal can lead to a series of different autonomous responses from the tamper module. These responses are listed in the table below.

These responses are cumulative, meaning that if a filter response is triggered, an interrupt will also be triggered. For a full overview of the tamper signals, see sl_se_manager_defines.h.

The tamper configuration is one-time-programmable, and is done using the initialise OTP command to the SE (see sl_se_init_otp ). This means that tamper settings must be written together with secure boot settings, and are immutable after they are written. After tamper has been initialized, it is possible to temporarily disable one or several tamper signals using an authenticated command, similar to secure debug unlock. This is only possible if the debug public key has been installed on the device. It is only possible to disable the customer enabled response. The default response to a signal cannot be disabled.

Tamper is configured by providing the following:

Example Usage

The glitch detectors can see spurious activations, and should typically not be used to directly drive a serious tamper response. Instead they should feed their signals into a tamper interrupt (to handle the response logic on the M33), or into the tamper filter counter, which can be used to activate a high level response if a number of incidents occur in a short time window. The time period and counter threshold must be tuned to the use case. In the following example the device will erase OTP and become inoperable if 4 glitch signals is seen in a 1 minute time period.

Since you can only configure tamper once for each device, please make sure that this is the configuration you actually want before you execute this example on actual device.

RTOS Mode and Multi-Thread Safety

The SE Manager supports multi-thread safe APIs for MicriumOS and FreeRTOS.

For MicriumOS support the user application must define the compile time option SL_CATALOG_MICRIUMOS_KERNEL_PRESENT. For FreeRTOS support the user application must define the compile time option SL_CATALOG_FREERTOS_KERNEL_PRESENT. For bare metal mode (non-RTOS) the user must not define SL_CATALOG_MICRIUMOS_KERNEL_PRESENT or SL_CATALOG_FREERTOS_KERNEL_PRESENT.

UC-based applications should include the header file called sl_component_catalog.h which should include a macro define for one of the abovementioned RTOSes if present.

In the cases with SL_CATALOG_MICRIUMOS_KERNEL_PRESENT or SL_CATALOG_FREERTOS_KERNEL_PRESENT defined (RTOS-mode), the SE Manager will be configured with threading and yield support. Configure sl_se_command_context_t with sl_se_set_yield to yield the CPU core when the SE Manager is waiting for the Secure Element to complete a mailbox command.

For threading support the SE Manager applies an SE lock mechanism ( mutex in MicriumOS and semaphore in FreeRTOS) to protect the Secure Element Mailbox interface from being accessed by more than one thread, ensuring multi-thread safety. For yielding the CPU core while waiting for the SE, the SE Manager APIs that invoke SE mailbox commands will wait on a semaphore which is signaled in the ISR that handles the SE mailbox completion interrupt. Hence other threads may run on the CPU core while the SE is processing the mailbox command.