diff --git a/ChangeLog b/ChangeLog index 3571910b6..dc6e4515d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -49,16 +49,9 @@ Removals * Remove the MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES compile-time option, which was off by default. Users should not trust certificates signed with SHA-1 due to the known attacks against SHA-1. - If needed, SHA-1 cerificate can still be used by providing custom - verification profile to mbedtls_x509_crt_verify_with_profile function - in x509_crt.h, or mbedtls_ssl_conf_cert_profile function in ssl.h. - Example of custom verification profile, supporting SHA-1: - const mbedtls_x509_crt_profile mbedtls_x509_crt_custom = { - MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA1 ), - 0xFFFFFFF, /* Any PK alg */ - 0xFFFFFFF, /* Any curve */ - 2048 - }; + If needed, SHA-1 certificates can still be verified by using a custom + verification profile. + * Removed deprecated things in psa/crypto_compat.h. Fixes #4284 * Removed deprecated functions from hashing modules. Fixes #4280. * Remove PKCS#11 library wrapper. PKCS#11 has limited functionality, diff --git a/ChangeLog.d/rm-ticket-lifetime-option b/ChangeLog.d/rm-ticket-lifetime-option new file mode 100644 index 000000000..4851512f8 --- /dev/null +++ b/ChangeLog.d/rm-ticket-lifetime-option @@ -0,0 +1,5 @@ +Removals + * Remove the MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES + compile-time option. This option has been inactive for a long time. + Please use the `lifetime` parameter of `mbedtls_ssl_ticket_setup()` + instead. diff --git a/docs/3.0-migration-guide.d/00README b/docs/3.0-migration-guide.d/00README new file mode 100644 index 000000000..a41733e47 --- /dev/null +++ b/docs/3.0-migration-guide.d/00README @@ -0,0 +1,27 @@ +Please add your migration guide entries here. Until 3.0 is released, each PR +that makes backwards-incompatible changes should add a file here, with the +extension .md, a descriptive name and the following format: + +---%<------%<------%<------%<------%<------%<------%<------%<--- + +The change that was made +------------------------ + +Who exactly is affected: does this affect users of the default config, of a +particular feature? Remember to contextualise. + +If I'm affected, what's my migration path? How should I change my code if this +is an API change; if a feature was removed what are my alternatives? + +---%<------%<------%<------%<------%<------%<------%<------%<--- + +PRs that make multiple independent changes should include one entry for each +changes or logical groups of changes. You can either add multiple files or put +multiple entries in the same file. + +For examples, have a look a docs/3.0-migration-guide.md (which includes the +top-level header and an intro before the list of entries). + +As part of release preparation, the entries in this directory will be appended +to docs/3.0-migration-guide.md and then re-ordered and reviewed one last time. +The file is then going to be moved to the version-independent docs repo. diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md new file mode 100644 index 000000000..2d031c6a4 --- /dev/null +++ b/docs/3.0-migration-guide.md @@ -0,0 +1,222 @@ +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_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.