Silicon Labs Secure Engine Manager API definitions.
License#
Copyright 2020 Silicon Laboratories Inc. www.silabs.com
SPDX-License-Identifier: Zlib
The licensor of this software is Silicon Laboratories Inc.
This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:
The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
This notice may not be removed or altered from any source distribution.
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:
Setting | Description |
|---|---|
Tamper response levels | A response level for each tamper signal. |
Filter settings | The tamper filter counter has two settings:
These options can be set to the values given in the tables in the Response Filter section. Please see the examples section for a suggested use of the tamper filter signal. |
Flags | The tamper flags is used to configure two options:
|
Reset threshold | The number of consecutive tamper resets before the the part enters debug mode. |
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.
sl_se_otp_init_t otp_settings_init = SL_SE_OTP_INIT_DEFAULT;
// Configure tamper levels
otp_settings_init.tamper_levels[SL_SE_TAMPER_SIGNAL_FILTER] = SL_SE_TAMPER_LEVEL_PERMANENTLY_ERASE_OTP;
otp_settings_init.tamper_levels[SL_SE_TAMPER_SIGNAL_VGLITCHFALLING] = SL_SE_TAMPER_LEVEL_FILTER;
otp_settings_init.tamper_levels[SL_SE_TAMPER_SIGNAL_VGLITCHRISING] = SL_SE_TAMPER_LEVEL_FILTER;
otp_settings_init.tamper_levels[SL_SE_TAMPER_SIGNAL_DGLITCH] = SL_SE_TAMPER_LEVEL_FILTER;
// Configure tamper filter options
otp_settings_init.tamper_filter_period = SL_SE_TAMPER_FILTER_PERIOD_1MIN;
otp_settings_init.tamper_filter_threshold = SL_SE_TAMPER_FILTER_THRESHOLD_4;
// Commit OTP settings. This command is only available once!
sl_se_init_otp(&otp_settings_init);
RTOS Mode and Multi-Thread Safety#
Note
The SE Manager API is multi-thread safe, but does not support preemption. This means the API cannot be called from ISR or critical/atomic sections when running in an RTOS thread. When using the SE Manager API in a bare-metal application, it is the application developer's responsibility to not call the SE Manager APIs when another operation is in progress.
The SE Manager supports multi-thread safe APIs for MicriumOS and FreeRTOS interfacing with CMSIS RTOS2 APIs.
In the cases where Micrium OS or FreeRTOS are included in the project (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 Engine to complete a mailbox command.
For threading support the SE Manager applies an SE lock mechanism to protect the Secure Engine 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.
Macros#
Context initialization values.
Default configuration for OTP initialisation structure.
Flags that can be used with asymmetric keys Asymmetric key can only be used for signing (not key exchange)
Described key belongs to a custom ECC domain.
Storage buffer contains public part of an asymmetric key.
Storage buffer contains private part of an asymmetric key.
Allow usage of this key by other bus masters or TrustZone levels than the one which created/imported the key.
Old definition. Retained for backwards compatibility.
Flags that can be used with symmetric keys Usage of key requires DPA countermeasures.
Usage of key requires DFA countermeasures.
Do not allow exporting the key to plaintext.
Indicate that the key has been generated by this device.
Indicate that the key can only be used to sign SE generated content.
Mask for algorithm field in key type.
Offset of algorithm field in key type.
Mask for attributes field in key type.
Offset of attributes field in key type.
Symmetric key type.
Symmetric key type for AES-128 (16 byte key)
Symmetric key type for AES-192 (24 byte key)
Symmetric key type for AES-256 (32 byte key)
ECC Weierstrass Prime key type.
ECC Montgomery key type.
EDDSA key type.
ECC NIST P-192.
ECC NIST P-224.
ECC NIST P-256.
ECC Ed25519 key for EdDSA.
ECC X25519 key for ECDH.
Symmetric key type for ChaCha20.
ECC NIST P-384.
ECC NIST P-521.
ECC X448 key for ECDH.
ECC Ed448 key for EdDSA.
Key storage methods.
Key is stored encrypted in application memory.
Key is stored inside the SE, and will persist until system reset or explicitly deleted.
Key is one of the pre-defined keys (pre-loaded or write-once) available in the SE.
Key is stored in the KSURAM, an internal Key Slot RAM.
Available KSU Key slots.
List of available internal SE key slots.
Internal volatile slot 1.
Internal volatile slot 2.
Internal volatile slot 3.
Minimum key slot value for internal keys.
Internal TrustZone root key.
Internal immutable application secure debug key.
Internal immutable application AES-128 key (bootloader key)
Internal immutable application secure boot key.
Internal immutable application attestation key.
Internal immutable SE attestation key.
Size overhead for wrapped keys.
Defines mapping the PBKDF2 PRFs to corresponding sl_se_hash_type_t values.
HMAC-SHA-1.
HMAC-SHA-224.
HMAC-SHA-256.
HMAC-SHA-384.
HMAC-SHA-512.
SE Challenge size.
Certificate key size.
Certificate signature size.
Batch ID certificate.
SE ID certificate.
Host ID certificate.
No action taken.
Generate interrupt.
Increment filter counter.
System reset.
Erase OTP - THIS WILL MAKE THE DEVICE INOPERATIONAL!
Reserved tamper signal.
Filter counter exceeds threshold.
SE watchdog timeout.
Crypto error detected.
SE RAM 2-bit ECC error.
Reserved tamper signal.
SE major fault detected.
L2 instruction cache error.
Reserved tamper signal.
Secure boot of user code failed.
Unauthorised command received over the Mailbox interface.
Unauthorised command received over the DCI interface.
SE software triggers an assert.
Reserved tamper signal.
Integrity error of internal storage is detected.
TRNG monitor detected lack of entropy.
Debug lock internal logic check failed.
Any tamper detection.
OTP alarm triggered.
SE ICache RAM error.
SE RAM 1-bit ECC error.
Brown-out-detector threshold alert.
On-device temperature sensor.
DPLL lock failure.
SoC PLL failure.
External tamper detect.
KSU ECC 1-bit error.
KSU ECC 2-bit error.
QSPI reseed error.
PRS channel 0 asserted.
PRS channel 1 asserted.
PRS channel 2 asserted.
Number of tamper signals.
Timeout ~32ms.
Timeout ~64ms.
Timeout ~128ms.
Timeout ~256ms.
Timeout ~512ms.
Timeout ~1s.
Timeout ~2s.
Timeout ~4.1s.
Timeout ~8.2s.
Timeout ~16.4s.
Timeout ~32.8s.
Timeout ~1.1min.
Timeout ~2.2min.
Timeout ~4.4min.
Timeout ~8.7min.
Timeout ~17.5min.
Timeout ~35min.
Timeout ~1.2h.
Timeout ~2.3h.
Timeout ~4.7h.
Timeout ~9.3h.
Timeout ~18.6h.
Timeout ~1.6days.
Timeout ~3.1days.
Timeout ~6.2days.
Timeout ~12.4days.
Timeout ~24.9days.
Timeout ~49.7days.
Timeout ~99.4days.
Timeout ~198.8days.
Timeout ~397.7days.
Timeout ~795.4days.
Counter threshold 2.
Counter threshold 4.
Counter threshold 8.
Counter threshold 16.
Counter threshold 32.
Counter threshold 64.
Counter threshold 128.
Counter threshold 256.
Tamper flags.
Tamper is kept alive during sleep (down to EM3)
Block size for the AES.
Default streaming hash context.
SHA1 streaming hash context.
SHA224 streaming hash context.
SHA256 streaming hash context.
SHA384 streaming hash context.
SHA512 streaming hash context.
The maximum number of code regions available on the device.