Migrating from Mbed TLS 2.x to Mbed TLS 3.0 =========================================== This guide details the steps required to migrate from Mbed TLS version 2.x to Mbed TLS version 3.0 or greater. Unlike normal releases, Mbed TLS 3.0 breaks compatibility with previous versions, so users (and alt implementors) might need to change their own code in order to make it work with Mbed TLS 3.0. Here's the list of breaking changes; each entry should help you answer these two questions: (1) am I affected? (2) if yes, what's my migration path? Some function parameters were made const ---------------------------------------- Various functions in the PK and ASN.1 modules had a `const` qualifier added to some of their parameters. This normally doesn't affect your code, unless you use pointers to reference those functions. In this case, you'll need to update the type of your pointers in order to match the new signature. Deprecated functions were removed from hashing modules ------------------------------------------------------ Modules: MD2, MD4, MD5, SHA1, SHA256, SHA512, MD. - The functions `mbedtls_xxx_starts()`, `mbedtls_xxx_update()`, `mbedtls_xxx_finish()` and `mbedtls_xxx()` were removed. Please use the function with the same name with `_ret` appended and check the return value. - The function `mbedtls_md_init_ctx()` was removed; please use `mbedtls_md_setup()` instead. - The functions `mbedtls_xxx_process()` were removed. You normally don't need to call that from application code. However if you do (or if you want to provide your own version of that function), please use `mbedtls_internal_xxx_process()` instead, and check the return value. Deprecated error codes for hardware failures were removed --------------------------------------------------------- - The macros `MBEDTLS_ERR_xxx_FEATURE_UNSUPPORTED` from various crypto modules were removed; `MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED` is now used instead. - The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead. Deprecated names for PSA constants and types were removed --------------------------------------------------------- Some constants and types that were present in beta versions of the PSA Crypto API were removed from version 1.0 of specification. Please switch to the new names provided by the 1.0 specification instead. Internal / alt-focused headers were moved to a private location ---------------------------------------------------------------- This shouldn't affect users who took care not to include headers that were documented as internal, despite being in the public include directory. If you're providing alt implementations of ECP or RSA, you'll need to add our `library` directory to your include path when building your alt implementations, and note that `ecp_internal.h` and `rsa_internal.h` have been renamed to `ecp_internal_alt.h` and `rsa_alt_helpers.h` respectively. If you're a library user and used to rely on having access to a structure or function that's now in a private header, please reach out on the mailing list and explain your need; we'll consider adding a new API in a future version. Remove the option to allow SHA-1 by default in certificates ----------------------------------------------------------- This does not affect users who use the default `config.h`, as this option was already off by default. If you used to enable `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` in your `config.h`, first please take a moment to consider whether you really still want to accept certificates signed with SHA-1 as those are considered insecure and no CA has issued them for a while. If you really need to allow SHA-1 in certificates, please set up a custom profile as follows: ``` const mbedtls_x509_crt_profile mbedtls_x509_crt_custom = { MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA1 ) | MBEDTLS_X509_ID_FLAG( /* other hash */ ) /* | etc */, 0xFFFFFFF, /* Or specific PK algs */ 0xFFFFFFF, /* Or specific curves */ 2048 /* Or another RSA min bitlen */ }; ``` Then pass it to `mbedtls_x509_crt_verify_with_profile()` if you're verifying a certificate chain directly, or to `mbedtls_ssl_conf_cert_profile()` if the verification happens during a TLS handshake. Remove the certs module from the library ---------------------------------------- This should not affect production use of the library, as the certificates and keys included there were never suitable for production use. However it might affect you if you relied on them for testing purposes. In that case, please embed your own test certificates in your test code; now that `certs.c` is out of the library there is no longer any stability guaranteed and it may change in incompatible ways at any time. Remove the HAVEGE module ------------------------ This doesn't affect people using the default configuration as it was already disabled by default. This only affects users who called the HAVEGE modules directly (not recommended), or users who used it through the entropy module but had it as the only source of entropy. If you're in that case, please declare OS or hardware RNG interfaces with `mbedtls_entropy_add_source()` and/or use an entropy seed file created securely during device provisioning. See for more information. Remove support for parsing SSLv2 ClientHello -------------------------------------------- This doesn't affect people using the default configuration as it was already disabled by default. This only affects TLS servers that have clients who send an SSLv2 ClientHello. These days clients are very unlikely to do that. If you have a client that does, please try contacting them and encouraging them to upgrade their software. Remove support for SSL 3.0 -------------------------- This doesn't affect people using the default configuration as it was already disabled by default. This only affects TLS users who explicitly enabled `MBEDTLS_SSL_PROTO_SSL3` and relied on that version in order to communicate with peers that are not up to date. If one of your peers is in that case, please try contacting them and encouraging them to upgrade their software. Remove support for compatibility with old Mbed TLS's truncated HMAC ------------------------------------------------------------------- This doesn't affect people using the default configuration as it was already disabled by default. This only affects TLS users who enabled `MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT` and used the Truncated HMAC extension to communicate with peers using old version of Mbed TLS. Please consider using a CCM-8 ciphersuite instead of the Truncated HMAC extension, or convincing your peer to upgrade their version of Mbed TLS. Remove support for TLS record-level compression ----------------------------------------------- This doesn't affect people using the default configuration as it was already disabled by default. This only affects TLS users who enabled `MBEDTLS_ZLIB_SUPPORT`. This will not cause any failures however if you used to enable TLS record-level compression you may find that your bandwidth usage increases without compression. There's no general solution to this problem; application protocols might have their own compression mechanisms and are in a better position than the TLS stack to avoid variants of the CRIME and BREACH attacks. Remove support for TLS RC4-based ciphersuites --------------------------------------------- This does not affect people who used the default `config.h` and the default list of ciphersuites, as RC4-based ciphersuites were already not negotiated in that case. Please switch to any of the modern, recommended ciphersuites (based on AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support any, encourage them to upgrade their software. Remove support for TLS single-DES ciphersuites ---------------------------------------------- This doesn't affect people using the default configuration as it was already disabled by default. Please switch to any of the modern, recommended ciphersuites (based on AES-GCM, AES-CCM or ChachaPoly for example) and if your peer doesn't support any, encourage them to upgrade their software. Remove support for TLS record-level hardware acceleration --------------------------------------------------------- This doesn't affect people using the default configuration as it was already disabled by default. This feature had been broken for a while so we doubt anyone still used it. However if you did, please reach out on the mailing list and let us know about your use case. Remove wrapper for libpkcs11-helper ----------------------------------- This doesn't affect people using the default configuration as it was already disabled by default. If you used to rely on this module in order to store your private keys securely, please have a look at the key management facilities provided by the PSA crypto API. If you have a use case that's not covered yet by this API, please reach out on the mailing list. Remove config option `MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME` ---------------------------------------------------------- This doesn't affect people using the default configuration. This option has not had any effect for a long time. Please use the `lifetime` parameter of `mbedtls_ssl_ticket_setup()` instead. Remove helpers for the transition from Mbed TLS 1.3 to Mbed TLS 2.0 ------------------------------------------------------------------- This only affects people who've been using Mbed TLS since before version 2.0 and still relied on `compat-1.3.h` in their code. Please use the new names directly in your code; `scripts/rename.pl` (from any of the 2.x releases - no longer included in 3.0) might help you do that.