Mbed TLS is now part of TrustedFirmware.org.

Working towards Mbed TLS 3.0

Ongoing work

You may have heard about Arm's PSA initiative to bring security to every IoT device, no matter how performant, small, or constrained. PSA stands for Platform Security Architecture and it gathers specifications and recommendations around IoT security. PSA aims at providing the blueprints for building secure devices, making sure that:

  • They protect their data at rest or on the fly.
  • You can manage them over the air.
  • You can update their firmware as required.

One of the main tenants of PSA is to make security accessible to all firmware developers in an easy way: you don't have to be a crypto specialist to establish a secure connection or locally protect data. Security must be the path of least resistance.

The Mbed TLS team has has a task to make this a reality for crypto libraries, with a double aim:

  • Make Crypto easy to learn and use by providing a clear, concise, agile, and documented developer API.
  • Systematically provide drivers for crypto hardware: accelerators, secure elements, random number generators must be supported out of the box.

The team designed a new Crypto API from scratch to support these goals, generating a new project dedicated to support crypto operations. You can find the API and all relevant documentation on the PSA web site. In parallel, a new project was founded to support and implement the PSA Crypto API. Mbed Crypto is born from all crypto primitives from Mbed TLS and packaged under the new API.

Impacts on Mbed TLS

Mbed TLS will be split into two projects:

  • The Mbed TLS library itself, dedicated to provide the network security layer, including X.509 support
  • The Mbed Crypto library project, dedicated to support the PSA Crypto API and provide support for pluggable device drivers for crypto hardware and architecture-specific implementations.

The split will be effective with the Mbed TLS 3.0 release, expected in June 2019.

If you are currently using Mbed TLS to establish TLS sessions, you should see very few changes. The networking API is maintained.

If you are making direct use of Mbed TLS crypto primitives, expect very heavy changes impacting all code directly using crypto primitives.

Mbed Crypto is built around the notion of a crypto key store: keys remain stored securely inside a secure enclave and are never directly revealed to library callers. Keys are referred to by handles, for example Please use key #1 to sign this bag of bytes and send me the results back, or Please decrypt this message using key #2 and send me the clear text results. How keys are actually stored and operations performed is implementation-dependent. A pure software implementation may choose to store keys in the same memory space as the main application, but calls may be re-directed into a secure element running on the same device, or passed to a secure enclave running inside TrustZone, or even run on a separate device altogether.

This abstraction layer comes with a cost in terms of RAM and flash usage. There are tangible benefits to have portable code that supports any kind of (possibly) hardware-based security. The benefits outweigh the costs for the new abstraction layer, as we are expecting savings in terms of RAM and flash usage by replacing pure software implementations by calls into hardware drivers. It is also more difficult to leak crypto keys from errors in the main firmware.

Work is currently ongoing to move all crypto primitives from one project into another. There are still temporary overlaps with duplicated code between the two projects at the moment, but this should be solved by the Mbed TLS 3.0 release.

The next major changes in Mbed TLS

The networking layer itself has proved to become hard to maintain, with most code contained in very few functions that have organically grown beyond an acceptable size. We have worked on prototyping support for TLS 1.3 over Mbed TLS 2. The result was compatible with the specs but turned out to be brittle. When we were asked to offer better support for fragmented connections, we found out that some re-engineering is needed to consolidate and extend the networking layer.

The work is currently ongoing, with a new re-design of the TLS layer. Seen from the top, the APIs do not change and still perform as expected. Underneath, the new design sets the foundation for supporting all features needed for TLS 1.3 and lossy networks. All of this is happening in a public branch, but will not be part of the Mbed TLS 3.0 release.

Support for TLS 1.3 has been delayed for nearly a year due to the profound re-engineering changes in the library. Mbed TLS 3.0 will not be the version that finally brings the support, but we are getting closer now.

The next major change with Mbed TLS 3.0 will be the switch to a single open-source license. Mbed TLS 2 was distributed under a dual GPL/Apache-2.0 license, which only brought confusion to partners and contributors. Switching to Apache-2.0-only allows us to accept contributions from the community on an inbound-outbound basis without need for anyone to sign a Contributor's License Agreement (CLA), facilitating the process for everyone.

Until Mbed TLS 3.0 is released, only Long-Term Support (LTS) versions of Mbed TLS 2.x will be released. Feature releases will be targeting Mbed OS only.

Mbed TLS 2 LTS releases will be maintained for at least the next three years (until mid-2022) and they maintain their dual GPL/Apache-2.0 license, but no new features will be introduced. Support for new crypto primitives will be introduced through modifications in Mbed Crypto, which will only be supported with Mbed TLS 3.0 onwards.

Contributions related to bug fixes in LTS releases will still have to deal with the dual-license and CLA mechanism. Contributions related to Mbed TLS 3.0 and later will benefit from the simplified licensing scheme.

What about the Mbed TLS project itself?

The above decisions were not purely based on engineering considerations. We have been seeking extensive feedback from partners and contributors and found several roadblocks that needed to be addressed. Namely:

  • Currently, there are hundreds of forks of Mbed TLS, with dedicated teams maintaining their own version against our reference. The main reason for forking seems to be hardware support: ALT implementations were good enough for some cases, but cannot adequately support secure elements, for example. We are changing that by switching to a re-designed API and project that should make it a lot easier to support any kind of crypto hardware.

  • Many contributors have complained about the need to sign legal papers to contribute to an open-source project. We are changing that by switching to an inbound-outbound model based on Apache-2.0 only.

  • Contributions from the community were often parked for months or even years without anyone taking time to look into them. We do not want to fail the community any more by ignoring the excellent work provided to the project. We will change that by opening the governance of this project more and more over the coming months, allowing partners and customers to have a say in shaping the library to fit their needs.

We are all excited to see the new structure take place. The latest changes are fairly extensive and will certainly have an impact on our users. Our hope is to gather forces around a single code base for all to enjoy. This required some re-engineering, including breaking changes. We are all impatient to sign the release notes for Mbed TLS 3.0. Check this site again in June.

Like this?




Last updated:
May 2, 2019


Want to stay up to date?

To sign up for Mbed TLS news, log in to or create an Mbed account and update your marketing preferences.