Hi all,

In the next few months we'll be preparing version 3.0 of Mbed TLS (with a goal of releasing in the 3rd quarter of calendar year 2020, see our roadmap [1]).

[1]: https://developer.trustedfirmware.org/w/mbed-tls/roadmap/

We've been maintaining full API compatibility since Mbed TLS 2.0.0 was released in July of 2015, so this will be our first chance in 5 years to clean up any API that we've found not to be entirely satisfactory, or no longer needed.

This is the first in a series of threads discussing what we would like to do in Mbed TLS 3.0 and how (or what we should rather postpone or not do at all). It will present the high-level goals and list some items as examples. Specific items that deserve further discussion (either to decide whether to include them in 3.0, or refine their scope or meaning) will be discussed each in their own thread.

Clean up the code by removing old things ----------------------------------------

This facilitates maintenance and testing.

Examples: - Remove support for SSL 3.0 and other deprecated protocol options. (But keep support for old crypto that could be useful for data at rest.) - Remove API functions that have been superseded.

Improve existing APIs, behaviours, and defaults -----------------------------------------------

This is mainly small things we just couldn't do in the 2.x line due to our compatibility rules.

Examples: - Upgrade the default TLS config to only offer (D)TLS 1.2 with forward-secure key exchanges and AEAD ciphers. - Add the 'const' qualifier to various arguments of existing APIs. - Add size arguments to existing APIs that lack such arguments.

Reduce the surface of the public API ------------------------------------

This makes it easier to evolve the library while maintaining API compatibility, and also makes testing easier.

Examples: - Forbid direct access to members of most (all?) structures. - Define more clearly which APIs are internal and forbid access to them. - Move some non-core modules that are only useful for examples out of the library (for example, certs.s).

Prepare the migration to PSA Crypto -----------------------------------

Currently Mbed TLS consists of three libraries: SSL/(D)TLS, X.509, and Crypto. Furthermore, currently Crypto provides both the long-standing `mbedtls_` APIs and the new PSA Crypto APIs, and the TLS and X.509 libraries still largely rely on the `mbedtls_` APIs, as does probably a large amount of external code.

Ultimately, we want to move to place where TLS and X.509 only rely on the PSA Crypto API (whose reference implementation will be independent and longer part of Mbed TLS), and where nobody uses the legacy `mbedtls_` APIs any more. But that's a goal for Mbed TLS 4.0. In the meantime, Mbed TLS 3.0 should pave the way for this.

The most important thing we want to do in 3.0 is to make most of the low-level crypto modules internal, and only keep the high-level crypto modules to ease the migration for existing users of the `mbedtls_` crypto APIs. Concretely, this would mean for example that the `mbedtls_aes_` functions and types would no longer be part of the API, but using AES via the `mbedtls_cipher_` APIs would still be supported for existing users until Mbed TLS 4.0 - and of course using AES via the PSA Crypto API is the way forward.

As this is a vast and complex topic, there will be a specific thread on where exactly we can and would like to draw the line of which crypto APIs are becoming private in Mbed TLS 3.0 and which are maintained until Mbed TLS 4.0 to ease migration.

Note: this strongly overlaps with the previous section (reduce the surface of the public API), but the two are still distinct as they're guided by different incentives: general maintainability vs supporting a specific migration.

I hope this email starts to clarify what Mbed TLS 3.0 should look like. Feel free to ask questions if anything's not clear, and again, there will be follow-up threads in the coming days and week to discuss specific aspects in more details.

Best regards, Manuel (Mbed TLS developer)