diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md new file mode 100644 index 000000000..ca4f57ed3 --- /dev/null +++ b/docs/3.0-migration-guide.md @@ -0,0 +1,210 @@ +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 version 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 explained in the ChangeLog. + +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 though 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 a 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 in 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 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 convicing 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 ciehrsuites were already not negociated 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 been inactive 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. +