Merge pull request #4402 from mpg/migration-guide-3.0

Migration guide for 3.0

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
+     If needed, SHA-1 certificates can still be verified by using a custom
-     verification profile to mbedtls_x509_crt_verify_with_profile function
+     verification profile.
-     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
-     };
    * 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,

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.

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.

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
+<https://tls.mbed.org/kb/how-to/add-entropy-sources-to-entropy-pool> 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.