Merge branch 'development' into Remove__CHECK_PARAMS_option

docs/3.0-migration-guide.d/Remove_3DES_ciphersuites.md

@@ -0,0 +1,10 @@
+Remove 3DES ciphersuites
+--
+
+This change does not affect users using default settings for 3DES in `config.h`
+because the 3DES ciphersuites were disabled by that.
+
+3DES has weaknesses/limitations and there are better alternatives, and more and
+more standard bodies are recommending against its use in TLS.
+
+The migration path here is to chose from the recomended in literature alternatives.

docs/3.0-migration-guide.d/ccm-alt.md

@@ -0,0 +1,9 @@
+CCM interface changes: impact for alternative implementations
+-------------------------------------------------------------
+
+The CCM interface has changed with the addition of support for
+multi-part operations. Five new API functions have been defined:
+mbedtls_ccm_starts(), mbedtls_ccm_set_lengths(),
+mbedtls_ccm_update_ad(), mbedtls_ccm_update() and mbedtls_ccm_finish().
+Alternative implementations of CCM (`MBEDTLS_CCM_ALT`) have now to
+implement those additional five API functions.

docs/3.0-migration-guide.d/cipher-delayed-output.md

@@ -0,0 +1,15 @@
+Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations
+----------------------------------------------------------------------------
+
+This only affects people who use the cipher module to perform AEAD operations
+using the multi-part API.
+
+Previously, the documentation didn't state explicitly if it was OK to call
+`mbedtls_cipher_check_tag()` or `mbedtls_cipher_write_tag()` directly after
+the last call to `mbedtls_cipher_update()` - that is, without calling
+`mbedtls_cipher_finish()` in-between. If you code was missing that call,
+please add it and be prepared to get as much as 15 bytes of output.
+
+Currently the output is always 0 bytes, but it may be more when alternative
+implementations of the underlying primitives are in use, or with future
+versions of the library.

docs/3.0-migration-guide.d/combine_SSL_CID-TLS1_3_PADDING_GRANULARITY_options.md

@@ -0,0 +1,14 @@
+Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options
+--
+
+This change affects users who modified the default `config.h` padding granularity
+settings, i.e. enabled at least one of the options.
+
+The `config.h` options `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and
+`MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` were combined into one option because
+they used exactly the same padding mechanism and hence their respective padding
+granularities can be used in exactly the same way. This change simplifies the
+code maintenance.
+
+The new single option `MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY` can be used
+for both DTLS-CID and TLS 1.3.

docs/3.0-migration-guide.d/csr-add-critical-extension.md

@@ -0,0 +1,9 @@
+Change the API to allow adding critical extensions to CSRs
+------------------------------------------------------------------
+
+This affects applications that call the `mbedtls_x509write_csr_set_extension`
+function.
+
+The API is changed to include the parameter `critical` which allow to mark an
+extension included in a CSR as critical. To get the previous behaviour pass
+`0`.

docs/3.0-migration-guide.d/modify_MBEDTLS_ECP_FIXED_POINT_OPTIM_behaviour.md

@@ -0,0 +1,11 @@
+Change MBEDTLS_ECP_FIXED_POINT_OPTIM behaviour
+------------------------------------------------------
+
+The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increase code size and it does
+not increase peak RAM usage anymore.
+
+If you are limited by code size, you can define `MBEDTLS_ECP_FIXED_POINT_OPTIM`
+to `0` in your config file. The impact depends on the number and size of
+enabled curves. For example, for P-256 the difference is 1KB; see the documentation
+of this option for details.
+

docs/3.0-migration-guide.d/relaxed-psk-semantics.md

@@ -0,0 +1,18 @@
+Relaxed semantics for PSK configuration
+-----------------------------------------------------------------
+
+This affects users which call the PSK configuration APIs
+`mbedtlsl_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()`
+multiple times on the same SSL configuration.
+
+In Mbed TLS 2.x, users would observe later calls overwriting
+the effect of earlier calls, with the prevailing PSK being
+the one that has been configured last. In Mbed TLS 3.0,
+calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times
+will return an error, leaving the first PSK intact.
+
+To achieve equivalent functionality when migrating to Mbed TLS 3.0,
+users calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times should
+remove all but the last call, so that only one call to _either_
+`mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()`
+remains.

docs/3.0-migration-guide.d/remove_supp_for_extensions_in_pre-v3_X_509_certs.md

@@ -0,0 +1,14 @@
+Remove the `MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3` option
+--
+
+This change does not affect users who were using the default configuration, as
+this option was already disabled by default. Also, it does not affect users who
+are working with current V3 X.509 certificates.
+
+Extensions were added in V3 of the X.509 specification, so pre-V3 certificates
+containing extensions were never compliant. Mbed TLS now rejects them with a
+parsing error in all configurations, as it did previously in the default
+configuration.
+
+If you are working with the pre-V3 certificates you need to switch to the
+current ones.

docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md

@@ -3,9 +3,25 @@ Remove suport for TLS 1.0, 1.1 and DTLS 1.0
 
 This change affects users of the TLS 1.0, 1.1 and DTLS 1.0 protocols.
 
-The versions of (D)TLS that are being removed are not as secure as the latest
-versions. Keeping them in the library creates opportunities for misconfiguration
+These versions have been deprecated by RFC 8996.
+Keeping them in the library creates opportunities for misconfiguration
 and possibly downgrade attacks. More generally, more code means a larger attack
 surface, even if the code is supposedly not used.
 
 The migration path is to adopt the latest versions of the protocol.
+
+As a consequence of removing TLS 1.0, support for CBC record splitting was
+also removed, as it was a work-around for a weakness in this particular
+version. There is no migration path since the feature is no longer relevant.
+
+As a consequence of currently supporting only one version of (D)TLS (and in the
+future 1.3 which will have a different version negociation mechanism), support
+for fallback SCSV (RFC 7507) was also removed. There is no migration path as
+it's no longer useful with TLS 1.2 and later.
+
+As a consequence of currently supporting only one version of (D)TLS (and in the
+future 1.3 which will have a different concept of ciphersuites), support for
+configuring ciphersuites separately for each version via
+`mbedtls_ssl_conf_ciphersuites_for_version()` was removed. Use
+`mbedtls_ssl_conf_ciphersuites()` to configure ciphersuites to use with (D)TLS
+1.2; in the future a different API will be added for (D)TLS 1.3.