linaro/freertos-pkcs11-psa

FreeRTOS PSA PKCS11

What is this project

The Amazon FreeRTOS PKCS#11 to PSA shim layer provides a reference implementation of PKCS#11 API based on PSA API.

PSA is Platform Security Architecture which is initiated by Arm. Please get the details from this link.

Amazon FreeRTOS uses TLS (Transport Layer Security) to secure the connection between the devices and AWS IoT Cloud. PKCS#11 (Public Key Cryptography Standards) provides some security functions to TLS in Amazon FreeRTOS. For example, objective storage and signing.

The original PKCS#11 API implementation in Amazon FreeRTOS is based on mbedTLS. This project is the PSA based PKCS#11 API implementation. This is done by adding the shim layer between these two API sets.

In general, this shim layer maps the PKCS#11 APIs to PSA Cryptography and Storage APIs V1.0. It follows the same PSA Cryptography API version supported in mbedtls-3.6.0. Certificate objects and key objects are protected by PSA secure service. By default, the device private/public keys are persistent while the code verify key is volatile.

License

Please check the License.md file in this project root folder for the detailed license information.

Unless stated otherwise, the software is provided under the MIT License.

This project contains code derived from mbedTLS local copy in Amazon FreeRTOS project. This code, including modifications, is provided under the Apache-2.0 license.

For details:

• iot_pkcs11_psa_input_format.h and iot_pkcs11_psa_input_format.c are derivatives of amazon-freertos\libraries\3rdparty\mbedtls\library\pkparse.c (amazon-freertos commit 74875b1d2)

Integration guide

Integrate PSA shim layer with the FreeRTOS project

In Amazon FreeRTOS, this shim layer is cloned into libraries/abstractions/pkcs11/psa folder by Git Submodule. To replace the default mbedTLS shim layer with PSA shim layer:

• Add all source files under libraries/abstractions/pkcs11/psa to the project (CMakeLists or IDE). Remove the files of other shim layers (for exmaple, the files of mbedTLS shim layer are under libraries/abstractions/pkcs11/mbedtls) from the project.
• Build the PSA implementation as the secure side image (check the Trusted Firmware-M example in the following section).
• Integrate the FreeRTOS project with the interface files of the PSA implementation (check the TF-M example below).
• Build the FreeRTOS project.
• Follow the platform specific instructions to sign/combine the FreeRTOS image and secure side image.

Integrate FreeRTOS project with Trusted Firmware-M (TF-M)

TF-M is a PSA implementation. It implements the PSA Firmware Framework API and developer API such as Secure Storage, Cryptography, Initial Attestation, etc. Refer to PSA website for more details.

This version of PKCS#11 shim layer is supported by TF-M v2.1.0.

Please follow the Build instructions of TF-M to build the secure side image for your platform.

Please check Integration guide for integrating FreeRTOS project with TF-M.

freertos-pkcs11-psa's Issues

RFC: Elaborating Github project description

Current Github description for this project is "FreeRTOS PSA PKCS11". That's too terse and clearly misses descriptive words to convey what it is. Colloquially it is referred as "shim" (e.g. in the current README), but that word is pretty much a developer slang, and in all fairness, with 100K+ source code, it's not really a shim. More formal word for what it does is "adapter" (as in "API adapter"), but for security-related things, there's even better established term - "security provider". That's as an alternative to something like "security driver", because term "driver" has strong connotation of being related to hardware.

With the above in mind, I propose to change the Github description "FreeRTOS PKCS11 security provider for PSA/TrustedFirmware-M". If the change goes thru, then apparently also update other references too.

One thing I'm not sure is how "security provider" term is established in FreeRTOS landscape (for example, maybe it's used for slightly different meaning).

Let me know if you agree/disagee. Thanks.