Manuel Pégourié-Gonnard e756306dd6 Move some details from ChangeLog to migration guide

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>

2021-05-04 11:36:33 +02:00

9.6 KiB

Raw Blame History

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 it you do (or it 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 in 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_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.