PSA Crypto API adoption in Zephyr

[ceolin]

Introduction

Zephyr has currently, at least, three different cryptography available and been used. They are:

• https://github.com/zephyrproject-rtos/tinycrypt
• https://github.com/zephyrproject-rtos/mbedtls
• https://github.com/zephyrproject-rtos/zephyr/blob/main/include/crypto/crypto.h

The lack of an unified API to cryptography leads to a situation where we have different components using the one that best attend there needs and when an application needs those components we end up having multiple cryptography implementations in a single target. This means resources being waste.

To make things worse, one of these implementations (TinyCrypt) is no longer supported, which put us in a position of maintain it by ourselves or replace it with something else.

PSA Crypto implementation provides a portable interface to cryptographic operations on a wide range of hardware and software. Which means we may have Zephyr's using a single API that can have different implementations depending in build options.
More information about it can be found in https://armmbed.github.io/mbed-crypto/html/overview/intro.html

Problem description

The lack of ONE API may cause waste of resources (multiple implementations needed at same time), make products more vulnerable (multiple implementations increases the code surface and consequently the chance of bugs), and it does help us take full advantage of HW accelerators.

Proposed change

The proposal is to adopt psa crypto API on Zephyr to replace the direct usage of other cryptography implementations.

Detailed RFC

The initial idea is:

• Select an implementation of the PSA crypto API (recent versions of mbedTLS implement it)
• Change the code base to use PSA crypto API
• Enable HW accelerators in the new API.

Concerns and Unresolved Questions

• The major reason to use TinyCrypt is due constraint resources, will PSA crypto be able to achieve similar requirements.
• What happens if we end up having two implementations of PSA crypto API in a same target ? e.g TF-M uses mbedTLS implementation and Zephyr's code base uses another one.

Alternatives

• One alternative is to implement Zephy's own API. That is idea behind the crypto drivers implementation (https://github.com/zephyrproject-rtos/zephyr/blob/main/include/crypto/crypto.h)

[d3zd3z]

Given https://www.wolfssl.com/platform-security-architecture-psa-crypto-api-support-wolfssl/, I think we are past the point of really deciding if PSA is the correct API to implement, and just planning on how we are going to get there.

[carlescufi]

Note: In the context of Bluetooth, there have been attempts to:

• Replace TinyCrypt with mbedTLS: Rejected because of higher ROM footprint: Bluetooth: Deprecate TinyCrypt and use mbedTLS #8081
• Use zephyr-specific crypto APIs instead of TC directly: was close but never merged: Use crypto drivers for Bluetooth - v2 #9227

[joerchan]

Snapshot of the current features of TinyCrypt that we would required replacements for:

zephyr/drivers/crypto/Kconfig:
  28: 	select TINYCRYPT_AES
  29: 	select TINYCRYPT_AES_CBC
  30: 	select TINYCRYPT_AES_CTR
  31: 	select TINYCRYPT_AES_CCM
  32: 	select TINYCRYPT_AES_CMAC

zephyr/subsys/bluetooth/common/Kconfig:
  239: 	select TINYCRYPT_AES

zephyr/subsys/bluetooth/host/Kconfig:
  118: 	select TINYCRYPT_AES
  119: 	select TINYCRYPT_SHA256
  120: 	select TINYCRYPT_SHA256_HMAC
  121: 	select TINYCRYPT_SHA256_HMAC_PRNG
  256: 	select TINYCRYPT_AES
  257: 	select TINYCRYPT_AES_CMAC
  633: 	select TINYCRYPT_ECC_DH

zephyr/subsys/bluetooth/host/Kconfig.gatt:
  94: 	select TINYCRYPT_AES
  95: 	select TINYCRYPT_AES_CMAC

zephyr/subsys/bluetooth/mesh/Kconfig:
  10: 	select TINYCRYPT_AES
  11: 	select TINYCRYPT_AES_CMAC
  34: 	select TINYCRYPT_ECC_DH

zephyr/subsys/jwt/Kconfig:
  25: 	select TINYCRYPT_SHA256
  26: 	select TINYCRYPT_ECC_DSA
  27: 	select TINYCRYPT_CTR_PRNG
  28: 	select TINYCRYPT_AES

zephyr/subsys/mgmt/updatehub/Kconfig:
  21: 	select TINYCRYPT_SHA256

zephyr/subsys/random/Kconfig:
  94: 	select TINYCRYPT_CTR_PRNG if TINYCRYPT
  95: 	select TINYCRYPT_AES if TINYCRYPT

zephyr/subsys/storage/flash_map/Kconfig:
  45: 	select TINYCRYPT_SHA256

[Vge0rge]

In my opinion moving towards the PSA crypto APIs as a universal solution does make a lot of sense. There are two notes that I would like to mention here.

1. The PSA APIs do not seem to provide flexible (enough) configuration option support for crypto accelerators yet. To reduce the code size it will be important to enable/disable specific functionalities in the PSA driver level. For example it should be possible for crypto accelerators to enable SHA256 and nothing else. Even though in the current state there are configuration options for this (PSA_WANT_ALG_SHA_256), I could not find any finalized configuration option for accelerators. There are some accelerator configurations (MBEDTLS_PSA_ACCEL_ALG_SHA_256) which does not seem to be used much in the code and they don't have a finalized structure.
2. The CSRNG support from PSA APIs is lacking at the moment. There is a psa_generate_random function available but the entropy interface as specified in the driver proposal here is not fully implemented. And additionally, configuration options for enabling CTR_DRBG or HMAC_DRBG using purely PSA APIs are lacking.

I still believe that moving to the PSA APIs is the way to go. I am just noting some possible challenges that will need to be handled.

[microbuilder]

@Vge0rge There is an effort to enable support for crypto accelerators in the PSA APIs, which I think is worth highlighting and solves a real problem: https://github.com/ARMmbed/mbedtls/blob/development/docs/proposed/psa-driver-interface.md

EDIT: You link to that proposal in point two, sorry. 🥸

[microbuilder]

I'd second that moving towards the PSA Crypto API make a lot of sense to me, even if there are clearly some issues to resolve around their use, and valid considerations of code size with the MbedTLS implementation. But resolving those issues will be less work than designing something else from scratch.

[frkv]

We are very happy with an intention to gravitate to PSA Crypto APIs!

The latest (released) version of nRF Connect SDK has an additional file describing Kconfig options for all PSA_WANT_ALG_XXX configurations found in Mbed TLS

https://github.com/nrfconnect/sdk-zephyr/blob/main/modules/mbedtls/Kconfig.psa

We have plans to upstream this, but we were waiting for the final decision on standardization

We have added two new configurations for the (for now) missing feature of configuring CTR_DRBG or HMAC_DRBG PRNG support:

CTR_DRBG and HMAC_DRBG

We have internal logic in our SDK to handle configuring NSPE and SPE in case TF-M is used to make sure that the configurations correctly transition into the TF-M build and is exposed in the secure services.

The logic includes:

• Converting CONFIG_PSA_WANT_ALG_XXXX into PSA_WANT_ALG_XXXX in generated configuration files (for NSPE and SPE)
• Passing SPE configurations to TF-M build
• Adding Nordic specific PSA driver configurations for NSPE or SPE builds (for building and linking)
• Adding necessary C-files in NSPE or SPE for building PSA Crypto APIs
• Enabling TF-M secure services based on enabled crypto features

Our intention is to support both with and without TF-M and to make sure that there is only "one unit implementing PSA crypto" in the system.

With regards to out-of-box experience, it wouldn't take much to get the Zephyr-module of Mbed TLS to make use of our proposed Kconfig logic. It is also possible to consider making µECC into a PSA driver to decrease the flash-size (if need be).

HMAC DRBG is not a big item to fix in a downstream adaptation if we make use of our proposed PSA configuration PSA_WANT_ALG_HMAC_DRBG

[ceolin]

We are very happy with an intention to gravitate to PSA Crypto APIs!

The latest (released) version of nRF Connect SDK has an additional file describing Kconfig options for all PSA_WANT_ALG_XXX configurations found in Mbed TLS

https://github.com/nrfconnect/sdk-zephyr/blob/main/modules/mbedtls/Kconfig.psa

We have plans to upstream this, but we were waiting for the final decision on standardization

We have added two new configurations for the (for now) missing feature of configuring CTR_DRBG or HMAC_DRBG PRNG support:

CTR_DRBG and HMAC_DRBG

We have internal logic in our SDK to handle configuring NSPE and SPE in case TF-M is used to make sure that the configurations correctly transition into the TF-M build and is exposed in the secure services.

The logic includes:

• Converting CONFIG_PSA_WANT_ALG_XXXX into PSA_WANT_ALG_XXXX in generated configuration files (for NSPE and SPE)
• Passing SPE configurations to TF-M build
• Adding Nordic specific PSA driver configurations for NSPE or SPE builds (for building and linking)
• Adding necessary C-files in NSPE or SPE for building PSA Crypto APIs
• Enabling TF-M secure services based on enabled crypto features

Our intention is to support both with and without TF-M and to make sure that there is only "one unit implementing PSA crypto" in the system.

Glad to hear it, that is one of my main concerns, we should not make Zephyr dependent of TF-M in order to have cryptography support.

With regards to out-of-box experience, it wouldn't take much to get the Zephyr-module of Mbed TLS to make use of our proposed Kconfig logic. It is also possible to consider making µECC into a PSA driver to decrease the flash-size (if need be).

Nice, we have to find a solution for the TinyCrypt EOL, uECC sounds like the direct alternative for it, but we have to have only one API to not have the same problem in future. We need to understand exactly what is the minimum requirements regarding rom/ram usage.

HMAC DRBG is not a big item to fix in a downstream adaptation if we make use of our proposed PSA configuration PSA_WANT_ALG_HMAC_DRBG

[gregshue]

From a cursory look it seems PSA Crypto API and Zephyr system interface have a common omission: calls that support a controlled de-initialization of the system. This matters when handing off the hardware from the boot image to the application image. And it affects not only the state of crypto hardware, but also the state of persistent storage, external chips, and even native UI.

To check my assumptions and foster discussion, here are the needs and requirements I have come up with so far:

Stakeholder needs:

1. As a developer of secure connected devices, I need the device boot image to use cryptographic algorithms to authenticate an image prior to running it, so that I do not run corrupted code.
2. As a developer of secure connected devices, I need the device boot image to use cryptographic algorithms to attest the source of an image prior to running it, so that I only run authorized code.
3. As a developer of secure, intermitently connected devices, I need the device boot image to use data in a device-local cryptographic vault (e.g., permanently attached secure element chip) to attest the source of an image prior to running it, so that I only run authorized code.
4. As a developer of devices, I need the device boot image to indicate boot progress and authentication/attestation status on the device native user interface, so that I can triage an unsucessful boot and/or firmware update.
5. As a developer of devices, I need the device boot image to use cryptographic algorithms to decode and encode data in off-MCU persistent storage (e.g., external flash, EEPROM).
6. As a developer of secure devices, I need the device boot image to only expose well-controlled and specified metadata about the boot image and related storage, so that I minimize the device vulnerabilities.
7. As a developer of devices, I need the device boot image to be extensible (extended without code modification), so that I can reuse the tools, tests, and processes to generate my own security review artifacts for the maximum amount of code.

System Requirements:
A. When the device transitions from the boot image to the application image, the device shall have cleanly completed all updates to persistent storage.
B. When the device transitions from the boot image to the application image, the device shall leave communications with external chips in a quiescent state.
C. When the device transitions from the boot image to the applicaiton image, the device shall have DMAs disabled.
D. When the device transitions from the boot image to the application image, the device shall have interrupts disabled.
E. When the device transitions from the boot image to the application image, the device shall have the caches disabled.

Analysis:
⦁ Algorithmically cleaning up hardware agents activated in the boot image requires a de-initialization of the system (reverse dependency order). The proposed API does not provide a de-initialization call, and so does not support an extensible boot architecture implied by the Zephyr ecosystem. This precludes boot code using MCU-external cryptographic hardware agents.

I expect I am pretty naïve here. What have I missed?

[gregshue]

Here are several more generally related to APIs:

Stakeholder needs:
8. As a developer of composable resource-constrained embedded software, I need to set the preemption priority of each unit of work so that I get consistent soft-real-time behavior. (In other words, a separate work queue for each preemption priority; cooperative scheduling available at every preemption level or avoidance of cooperative scheduling)
9. As a developer of resource constrained embedded systems that need to support controlled disablement and cancel functionality, I need to use asynchronous API operations so that I can minimize RAM usage (fewer threads/stacks)
10. As a developer of software models of hardware, I need to have a single executable support both hardware and software implementations of a specific functionality so that I can run predictive maintenance models.
11. As a user of the Zephyr ecosystem, I need a single executable to support multiple instances (e.g., simultaneous sessions/contexts) of an internal service, so that I can support asynchronous processing (e.g., receiving and acting on a cancel request)
12. As a potential (re)user of the Zephyr ecosystem with a proprietary 3rd party toolchain, I need the Zephyr ecosystem to be limited to a published, maximum number of significant characters in linker symbols, so that I can determine if Zephyr can be supported by my toolchain for the foreseable future. In the absence of a published maximum number, I need the maximum number of significant characters in the Zephyr ecosystem linker symbols to fit within the limits guaranteed by the C99 standard.
13. As a user of the Zephyr ecosystem and other 3rd party libraries that is not allowed to change either codebase, I need the Zephyr ecosystem to minimize potential conflicts with any other library or external component source tree so that I don't have to replace Zephyr when my feature set grows.
14. As a developer of a family of resource-constrained products that may need the MCU replaced at any time, I need to configure the system to execute interrupt service routines at any configurable thread preemption or interrupt preemption level so that I can minimize the costs of supporting code running on alternative MCUs and/or CPU architectures.
15. As a developer of mechatronic devices built on Zephyr, I need to cancel arbitrary operations so that I can support user-initiated Cancel functionality.

[d3zd3z]

Let me try to distill this down a bit, since most of these requirements are a bit higher level than what would be affected by the crypto API.

The first point I want to make is that asking this as a question "Should Zephyr Adopt the PSA Crypto API" is kind of a moot point. Mbed TLS has been a component of Zephyr for some time, and the Mbed TLS project is in transition to the PSA crypto API. The question here isn't about a general crypto API, which is already the PSA Crypto API within Zephyr, but about a small number of cryptographic primitives that are used by other functionality built into Zephyr. Right now, these use some other ad-hoc libraries (e.g. tinycrypt) that have to be replaced due to lack of upstream support. We're proposing moving these to use the PSA crypto API, and in some sense, the requirements we need here are in regards to what these subsystems need.

But, back to the above lists from @gregshue:

1. There is a need for deinitialization of crypto operations. Given that the current implementation is entirely software, there really isn't anything to deinitialize, and as Mbed TLS begins to implement hardware accelerated crypto support, the need to deinitialize can be brought up. This isn't necessarily even part of the crypto API, although it would make sense to definitely include it there.
2. Related, as far as priority of work, currently for a software solution, work is done in the caller's thread, for basic cryptographic operations. For features such as TLS, this is generally done by networking worker threads. There are likely issues to be addressed here, but not really related to the crypto API itself. As far as work done when hardware acceleration is used, there may indeed need to be prioritization and scheduling done here.
3. As far as the 31-character identifier limitation: this is pretty hard to enforce within Zephyr, as none of our current toolchains have any way of enforcing this kind of limit. Ideas are welcome, but there really isn't any way to specify this as a requirement that Zephyr meets without a way of checking it. This is worth raising an issue to track, as it has nothing to do with the crypto API (unless you're aware of symbols longer than 31 characters in the PSA API).
4. As far as symbol conflicts go, this is a general issue, and should be raised as such. As far as I know, the PSA Crypto API does a good job of prefixing its namespace.
5. Likewise with the remainder of issues. The only issue I see possibly affecting the crypto api would be the ability to cancel an operation. For a software implementation, this would be no different than canceling a running thread. For something with hardware crypto, this is challenging to address in a device-independent way, and until we have a better idea of how hardware addresses these issues, across diverse devices, it is difficult to know what could even be done that is general.

Again, to summarize. There are numerous points raised here. Many of them aren't really related to the use of a crypto API, and should be raised as their own issues.

As far as using the PSA Crypto API within Zephyr, that's already the case. By officially adopting it, we're discussing migrating existing users of other crypto libraries (notably tinycrypt) to use the PSA API, and what requirements there are behind that.