Mbed TLS is now part of TrustedFirmware.org.

Preparing for the 2.0 upgrade

In the coming weeks we should be releasing a new major version: mbed TLS 2.0, which will be the first official branch with DTLS support.

While we take great care not to break API compatibility within a stable branch, upgrading to a new stable branch usually requires some manual intervention. The 2.0 release will have a larger number of such changes than usual, and we hope to make the transition at bit easier by sharing our plans in advance. A more detailed article will follow when 2.0 will be closer to publication.

Wait, 2.0, not 1.5?

Before we dive into the details of the changes that will require work, let's start with a simple news: we're moving to semantic versioning starting with the 2.0 branch. This means 2.0.1 will be the first bugfix release (if needed); the first round of new features will be in 2.1.0 and the next major branch (breaking API compatibility) will be 3.0.0.

The Great Renaming

We're going to rename all publicly visible symbols (function names, types, enum constants, macros, global objects) so that all the names start with MBEDTLS_ (macros, enum constants) or mbedtls_ in order to avoid possible name collision that users have been reporting in the past.

We realise this change has a huge impact on users, so we are going to provide help for the migration in two forms:

  • A renaming script that you can apply to your codebase to automatically replace old names with the new ones. It is the script we used internally for the change, so it has been tested at least on our example programs and test suites, and it will undergo further internal testing before prime time.
  • A compatibility header that provides #defines for the old names.

SSL configuration interface

The other most visible change will be that some of the information that is currently held in each ssl_context structure will be moved to a new structure called mbedtls_ssl_config that can be shared between multiple mbedtls_ssl_contexts to allow memory savings. Also, mbedtls_ssl_configs could be written to ROM in order to save RAM if only a small number of them are used.

The impact will be that this new structure will need to be declared/allocated, initialised, configured and freed explicitly by the user. Also, most ssl_set_xxx() functions now operate on mbedtls_ssl_config and have been renamed to mbedtls_ssl_conf_xxx() in order to reflect that.

Other changes in the SSL interface

The current interface for server-side handling of session tickets is very simple but has a number of issues: sharing ticket keys between SSL contexts is hard, which is a problem for concurrent servers, and ticket keys are not rotated, which impairs forward secrecy. The new interface will be based on callbacks, with a default set of callbacks provided in ssl_ticket.c that will solve these issues. It will also allow people to implement more sophisticated behaviour such as sharing ticket keys between a set of servers.

The implementations of the PSK and SNI callbacks will need to be changed to replace ssl_set_xxx() functions with a new mbedtls_ssl_set_hs_xxx() function to reflect the fact that the settings done by these callbacks are specific to a single handshake, hence set_hs.

Moving of HMAC functions to the MD layer

There are currently two interface for, eg HMAC-SHA256: a specific one in the sha256 module, and a generic one in the MD layer. The specific interface is going to be removed, which will significantly reduce code size. Specific mdX_file() and shaXXX_file() functions are also going to be removed.

Please note that you can already prepare for this change in your 1.3-based code by making sure you're only using the generic interface.

Removal of deprecated things

All the functions, compatibility headers and configuration options that are deprecated in 1.3.11 will be removed in 2.0.0. The full list can be found in the API reference. The 1.3.11 release introduces two new options in config.h that can help you track usage of deprecated functions: POLARSSL_DEPRECATED_WARNING (only with GCC and Clang) and POLARSSL_DEPRECATED_REMOVED.

We highly encourage you to make sure your code does not use anything deprecated in 1.3.11 before starting your migration to the 2.x branch, as this will be assumed in all the help tools and documentation we will provide.

Incompatible changes in default behaviour

The default settings of the SSL module are going to be improved in order to match the current best practices (no RC4 suites , no SSLv3, no SSLv2 ClientHello, mandatory server authentication). Unfortunately, such improvements may result in interoperability issues for some of our users, so support can still be reactivated if necessary (at runtime for RC4 suites and SSLv3, at compile time for SSLv2 ClientHello).

Miscellaneous prototype changes

As usual, a few functions will change prototypes in order to provide cleaner usage patterns. The full list will be included in the ChangeLog and release notes.

That's all for now

We realise this is already a long list with some big items. Occasional disruptive changes are sometimes necessary in order to maintain and continuously improve the quality of our code and API. We hope communicating in advance and providing helper tools such as the renaming script and compatibility header will help make the transition less painful.

Obviously, the 1.3 branch will continue to receive bug fixes and security fixes well after 2.0 is published, giving you ample time to make the transition if you don't need the new features from the 2.0 branch.

As always, your feedback is most welcome.

Like this?




Last updated:
Jun 12, 2015


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.