Platform Security API Documentation#

Platform Security includes a fork of Mbed TLS. It is intended to be used by all SDK and application code which needs to handle or use cryptographic keys or secrets. This includes Mbed TLS PSA Crypto APIs.

For more information on Mbed TLS and PSA Crypto from a hardware acceleration perspective, see PSA Crypto versus mbed TLS plugins.

PSA Crypto Initialization#

PSA Crypto must be initialized before usage. If the application calls any function that returns a psa_status_t result code before calling psa_crypto_init(), the function should return an error. In order to simplify things for users, Silicon Labs' implementation will automatically call psa_crypto_init() as a part of sl_system_init() before the user application is started. There is, however, one exception to this rule: applications that rely on RAIL for entropy. This should mainly be the case for EFR32xG14 and EFR32xG13 devices. In those cases, the application is responsible for calling psa_crypto_init().

Dynamic Memory#

The Runtime initialisation of dynamic memory allocation functions for Mbed TLS component, supports user configuration of application specific functions for dynamic memory allocation. When this component is selected the application can call mbedtls_platform_set_calloc_free to set application specific calloc and free function pointers which will be used by the Mbed TLS modules, plugins, PSA Crypto library and drivers.

The Default dynamic memory allocation macros for mbedtls component is applied by default, and uses dynamic memory allocation functions provided by the silabs_core_sl_malloc component.

Key Identifiers#

Cryptographic function in the PSA API requires a key taken in as a key by reference through psa_key_id_t. A key's ID is either:

• User-defined, for persistent keys (stored in non-volatile storage). The key ID should be set to the key's attributes before importing/creating the key. It needs to be in the user range and cannot be 0.

• Auto-generated, for transient/volatile keys (stored in RAM). The key ID in the key's attributes should be set to 0 before importing/creating the key, and upon success the auto-assigned ID (valid for this session or until the key is destroyed) will be output by the key import/generation function.

• System-defined, for keys accessed through either the builtin key mechanism (e.g. attestation keys preprovisioned on Vault parts).

PSA Crypto key ID namespacing in the Silicon Labs SDK#

As PSA Crypto is the common place for cryptographic key storage and usage, all components in an application are sharing the PSA key ID namespace. In order to avoid collisions, especially in case the application stores keys with an identifier which is later attempted to be stored by another SDK component, agreement needs to happen on which part of the namespace belongs to which component.

So far, the following allocations have been made within the Silicon Labs SDK:

Note

• For more details on the builtin keys, refer to built-in keys.

Applications are highly encouraged to adhere to the allocations made for application usage, as the SDK usage of ranges allocated to the SDK may change at any time.

Note

• Irrespective of the size of the allocated ranges, there is a limitation on how many keys the non-volatile storage mechanism can store. This is a function of the total size of the storage area, as well as the file ID range allocated to PSA Crypto in the storage backend, and the sizing of the PSA ITS driver. See SL_PSA_ITS_USER_MAX_FILES in the PSA Crypto configuration file.

PSA Crypto Key Locations on Silicon Labs Devices#

When creating or importing a key in PSA Crypto, a lifetime value (which consists of a persistence and location value) dictates where and how the key gets stored. This value gets constructed by PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION

The PSA Crypto implementation on Silicon Labs devices currently supports persistence values of PSA_KEY_PERSISTENCE_VOLATILE (where the key is stored in volatile RAM and thus disappears on reset) and PSA_KEY_PERSISTENCE_DEFAULT (where the key will be stored in non-volatile memory). For storing keys in non-volatile memory, the component 'PSA Persistent Storage Support (ITS)' needs to be included to the project, and users should take note of the key ID ranges as described in PSA Crypto key ID namespacing in the Silicon Labs SDK.

All Silicon Labs devices support the location value of PSA_KEY_LOCATION_LOCAL_STORAGE which stores keys in plaintext. Silicon Labs devices with Secure Engine and Vault High capabilities additionally support the location value of #PSA_KEY_LOCATION_SL_SE_OPAQUE, which will store the key to the requested persistence, cryptographically secured with the device-unique secret. This gives heightened protection against key leakage, since the key can only be used by the device which stored it.

Using Pre-Provisioned Keys on SE Devices#

Silicon Labs devices with Secure Engine can contain keys which are pre-provisioned in the factory. To access these keys, the 'Built-In Keys' PSA Crypto component needs to be added to the project. This will make the keys available for use through their predefined builtin IDs.

Refer to built-in keys.

Thread Safety in PSA Crypto#

Silicon Labs include threading support in PSA Crypto library for GSDK version 4.3 and onwards. See Thread Safety of the PSA Subsystem for further details.

Internal Trusted Storage (ITS)#

Mbed TLS includes a PSA Crypto Library which interacts with a user configurable PSA ITS driver implementation. There is a default implementation of PSA ITS in Mbed TLS which is based on standard C file I/O interface. Silicon Labs has implemented it's own PSA ITS driver based on NVM3 which is documented in the section below.

PSA ITS (Internal Trusted Storage) is a set of storage abstraction APIs for use in conjunction with the rest of the PSA APIs.

It defines a way to interact with a trusted storage backend, by storing data in internal flash. Files are accessed with a unique value through psa_storage_uid_t. The PSA storage subsystem in Mbed TLS maps the psa_storage_uid_t parameter in the PSA API directly to the key_id (of type mbedtls_svc_key_id_t ). this is returned by psa_import_key and subsequently used when referencing most PSA Crypto APIs.

Use of ITS for Key Storage#

The Mbed TLS PSA Crypto implementation interacts with ITS to store its key database, key metadata and (if applicable) key material. It is based on a set of different files:

• One file for the key database (the list of psa_key_id's present on a system)

• One file per psa_key_id present on the system, containing key metadata (for all keys across all lifetimes except volatile) with potentially plain-text key material (for keys generated with the default persistent lifetime)

• One transaction file that logs ongoing key creation/modification/deletion operations in case an unexpected system restart happens and the transaction needs to be fulfilled across reset.

PSA ITS on Silicon Labs Parts#

PSA ITS is implemented as a wrapper around NVM3. See NVM3 NVM Data Manager for further details. In NVM3, there is a range of NVM3 IDs allocated to PSA ITS, and each file stored through ITS requires such an ID. Files are stored sequentially, and created in the first free NVM3 ID which can be found in its range. Retrieval of a PSA ITS file by its PSA ID requires finding the NVM3 ID which contains the file for the requested PSA ID.

PSA ITS Constraints#

Looking up a key by PSA ITS ID requires that all keys need to be partially read (through retrieval of the file header) to look for a match, since the PSA ITS ID range is 64 bits and the NVM3 range allocated for PSA ITS is set to 16 bits.

The PSA ITS file maximum size is dictated by the default NVM3 instance's maximum object size. The maximum amount of PSA ITS files in a system becomes a function of: The maximum NVM3 object size The available free space in the NVM3 default instance The amount of keys available in the NVM3_PSA_ITS_RANGE Currently, the NVM3 range available to PSA is set to 1024 files.

Note

• With the ITS driver upgrade to version 3, ITS uses simple PRNG with UID as a seed to create a hash-map-like structure. The NVM3 ID range was changed from region starting at 0x83100 to region ending with 0x870ff. We provide an upgrade path for the devices that already use the ITS driver. Note that after upgrading to ITS driver V3, SL_PSA_ITS_USER_MAX_FILES cannot be changed. Two new config options has been added: SL_PSA_ITS_SUPPORT_V2_DRIVER - This can be set to 0 if the device has never used ITS driver before in GSDK 4.1.x and earlier, or the keys have been already migrated to v3, and remove the unused code. SL_PSA_ITS_SUPPORT_V3_DRIVER - This can be set to 1 if the device has never used ITS driver before in GSDK 4.1.x and earlier. This configuration option will add support for V3 driver, and provide an upgrade path from V1/V2. For devices that are not able to upgrade to ITS driver V3, we recommend to disable it, and use the previous version of ITS driver.

Silicon Labs Plugins#

Cryptography Hardware Acceleration Plugins#

Silicon Labs plugins utilizing cryptography hardware acceleration are provided in this Mbed TLS package. These plugins and their configurations are documented in Silicon Labs Cryptography Hardware Acceleration Plugins. The plugins support sharing of cryptography hardware in multi-threaded applications, as well as a reduced overhead configuration for optimal performance in single-threaded applications.

Random Number Plugins#

True Random Number Generator (TRNG), ADC and Radio (RAIL) hardware entropy source plugins are available for Silicon Labs devices. Entropy plugins are documented in the Random number generator (RNG) module.

TrustZone#

TrustZone is an ARM security technology adopted by Silicon Labs and integrated in our protocol stacks. TrustZone provides a secure way of storing wireless cryptographic keys and other firmware used by the device from application vulnerabilities. Providing system security through a logical separation of memory into dedicated environments, secure processing environment (SPE) and non-secure processing environment (NSPE). More information on TrustZone is available in the official application note

Platform Security API Modules#