From 8cccbe11dffe54e4708a6b2b2adfcbee229694f5 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 13:15:50 +0100 Subject: [PATCH 01/51] Update the migration guide Signed-off-by: Dave Rodgman --- .../Remove_3DES_ciphersuites.md | 10 - docs/3.0-migration-guide.d/ccm-alt.md | 9 - .../cipher-delayed-output.md | 15 - ..._CID-TLS1_3_PADDING_GRANULARITY_options.md | 14 - .../csr-add-critical-extension.md | 9 - docs/3.0-migration-guide.d/default-curves.md | 25 - docs/3.0-migration-guide.d/gcm-alt.md | 10 - docs/3.0-migration-guide.d/gcm-multipart.md | 12 - docs/3.0-migration-guide.d/key-export.md | 36 - .../mandatory-rng-param.md | 40 - .../max-record-payload-api.md | 11 - ...MBEDTLS_ECP_FIXED_POINT_OPTIM_behaviour.md | 11 - .../modify_SHA384_option_behaviour.md | 12 - ...art_of_timing_module_out_of_the_library.md | 9 - docs/3.0-migration-guide.d/out_size.md | 9 - .../relaxed-psk-semantics.md | 18 - .../remove-enable-weak-ciphersuites.md | 12 - .../remove-max-content-len.md | 10 - .../remove-null-entropy.md | 11 - .../remove-rsa-mode-parameter.md | 21 - .../remove-ssl-get-session_pointer.md | 23 - ...09_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION.md | 17 - ..._MBEDTLS_X509_CHECK_x_KEY_USAGE_options.md | 18 - .../remove_MD2_MD4_RC4_Blowfish_XTEA.md | 8 - .../remove_SSL_DTLS_BADMAC_LIMIT_option.md | 11 - ...move_deprecated_functions_and_constants.md | 74 -- .../remove_mbedtls_check_params_option.md | 33 - .../remove_ssl_record_checking.md | 13 - ...pp_for_extensions_in_pre-v3_X_509_certs.md | 14 - ...ve_support_for_tls_1.0_1.1_and_dtls_1.0.md | 27 - .../rename_the__ret_functions.md | 43 - .../require-matching-hashlen-rsa.md | 24 - docs/3.0-migration-guide.d/rsa-padding.md | 29 - .../separate_SHA224_from_SHA256.md | 11 - .../session-cache-api.md | 28 - .../sha512-output-type.md | 8 - docs/3.0-migration-guide.d/split_config.md | 20 - .../ssl-error-code-cleanup.md | 39 - docs/3.0-migration-guide.d/ssl-ticket-api.md | 30 - ...NT_PREFERENCE_config_opt_to_runtime_opt.md | 14 - docs/3.0-migration-guide.md | 789 +++++++++++++++++- 41 files changed, 783 insertions(+), 794 deletions(-) delete mode 100644 docs/3.0-migration-guide.d/Remove_3DES_ciphersuites.md delete mode 100644 docs/3.0-migration-guide.d/ccm-alt.md delete mode 100644 docs/3.0-migration-guide.d/cipher-delayed-output.md delete mode 100644 docs/3.0-migration-guide.d/combine_SSL_CID-TLS1_3_PADDING_GRANULARITY_options.md delete mode 100644 docs/3.0-migration-guide.d/csr-add-critical-extension.md delete mode 100644 docs/3.0-migration-guide.d/default-curves.md delete mode 100644 docs/3.0-migration-guide.d/gcm-alt.md delete mode 100644 docs/3.0-migration-guide.d/gcm-multipart.md delete mode 100644 docs/3.0-migration-guide.d/key-export.md delete mode 100644 docs/3.0-migration-guide.d/mandatory-rng-param.md delete mode 100644 docs/3.0-migration-guide.d/max-record-payload-api.md delete mode 100644 docs/3.0-migration-guide.d/modify_MBEDTLS_ECP_FIXED_POINT_OPTIM_behaviour.md delete mode 100644 docs/3.0-migration-guide.d/modify_SHA384_option_behaviour.md delete mode 100644 docs/3.0-migration-guide.d/move_part_of_timing_module_out_of_the_library.md delete mode 100644 docs/3.0-migration-guide.d/out_size.md delete mode 100644 docs/3.0-migration-guide.d/relaxed-psk-semantics.md delete mode 100644 docs/3.0-migration-guide.d/remove-enable-weak-ciphersuites.md delete mode 100644 docs/3.0-migration-guide.d/remove-max-content-len.md delete mode 100644 docs/3.0-migration-guide.d/remove-null-entropy.md delete mode 100644 docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md delete mode 100644 docs/3.0-migration-guide.d/remove-ssl-get-session_pointer.md delete mode 100644 docs/3.0-migration-guide.d/remove_MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION.md delete mode 100644 docs/3.0-migration-guide.d/remove_MBEDTLS_X509_CHECK_x_KEY_USAGE_options.md delete mode 100644 docs/3.0-migration-guide.d/remove_MD2_MD4_RC4_Blowfish_XTEA.md delete mode 100644 docs/3.0-migration-guide.d/remove_SSL_DTLS_BADMAC_LIMIT_option.md delete mode 100644 docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md delete mode 100644 docs/3.0-migration-guide.d/remove_mbedtls_check_params_option.md delete mode 100644 docs/3.0-migration-guide.d/remove_ssl_record_checking.md delete mode 100644 docs/3.0-migration-guide.d/remove_supp_for_extensions_in_pre-v3_X_509_certs.md delete mode 100644 docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md delete mode 100644 docs/3.0-migration-guide.d/rename_the__ret_functions.md delete mode 100644 docs/3.0-migration-guide.d/require-matching-hashlen-rsa.md delete mode 100644 docs/3.0-migration-guide.d/rsa-padding.md delete mode 100644 docs/3.0-migration-guide.d/separate_SHA224_from_SHA256.md delete mode 100644 docs/3.0-migration-guide.d/session-cache-api.md delete mode 100644 docs/3.0-migration-guide.d/sha512-output-type.md delete mode 100644 docs/3.0-migration-guide.d/split_config.md delete mode 100644 docs/3.0-migration-guide.d/ssl-error-code-cleanup.md delete mode 100644 docs/3.0-migration-guide.d/ssl-ticket-api.md delete mode 100644 docs/3.0-migration-guide.d/turn_SSL_SRV_RESPECT_CLIENT_PREFERENCE_config_opt_to_runtime_opt.md diff --git a/docs/3.0-migration-guide.d/Remove_3DES_ciphersuites.md b/docs/3.0-migration-guide.d/Remove_3DES_ciphersuites.md deleted file mode 100644 index 086336368..000000000 --- a/docs/3.0-migration-guide.d/Remove_3DES_ciphersuites.md +++ /dev/null @@ -1,10 +0,0 @@ -Remove 3DES ciphersuites --- - -This change does not affect users using default settings for 3DES in `mbedtls_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. diff --git a/docs/3.0-migration-guide.d/ccm-alt.md b/docs/3.0-migration-guide.d/ccm-alt.md deleted file mode 100644 index 1abac7acd..000000000 --- a/docs/3.0-migration-guide.d/ccm-alt.md +++ /dev/null @@ -1,9 +0,0 @@ -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. diff --git a/docs/3.0-migration-guide.d/cipher-delayed-output.md b/docs/3.0-migration-guide.d/cipher-delayed-output.md deleted file mode 100644 index 18d327152..000000000 --- a/docs/3.0-migration-guide.d/cipher-delayed-output.md +++ /dev/null @@ -1,15 +0,0 @@ -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. diff --git a/docs/3.0-migration-guide.d/combine_SSL_CID-TLS1_3_PADDING_GRANULARITY_options.md b/docs/3.0-migration-guide.d/combine_SSL_CID-TLS1_3_PADDING_GRANULARITY_options.md deleted file mode 100644 index c4005cffc..000000000 --- a/docs/3.0-migration-guide.d/combine_SSL_CID-TLS1_3_PADDING_GRANULARITY_options.md +++ /dev/null @@ -1,14 +0,0 @@ -Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options --- - -This change affects users who modified the default `mbedtls_config.h` padding granularity -settings, i.e. enabled at least one of the options. - -The `mbedtls_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. diff --git a/docs/3.0-migration-guide.d/csr-add-critical-extension.md b/docs/3.0-migration-guide.d/csr-add-critical-extension.md deleted file mode 100644 index ebcb343ca..000000000 --- a/docs/3.0-migration-guide.d/csr-add-critical-extension.md +++ /dev/null @@ -1,9 +0,0 @@ -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`. diff --git a/docs/3.0-migration-guide.d/default-curves.md b/docs/3.0-migration-guide.d/default-curves.md deleted file mode 100644 index 928130d24..000000000 --- a/docs/3.0-migration-guide.d/default-curves.md +++ /dev/null @@ -1,25 +0,0 @@ -Strengthen default algorithm selection for X.509 and TLS --------------------------------------------------------- - -The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. - -Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. - -The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. - -The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. - -If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: -``` -mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; -my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); -``` - -If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. - -TLS now favors faster curves over larger curves ------------------------------------------------ - -The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves. - -If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection. diff --git a/docs/3.0-migration-guide.d/gcm-alt.md b/docs/3.0-migration-guide.d/gcm-alt.md deleted file mode 100644 index 388e2bedd..000000000 --- a/docs/3.0-migration-guide.d/gcm-alt.md +++ /dev/null @@ -1,10 +0,0 @@ -GCM interface changes: impact for alternative implementations -------------------------------------------------------------- - -The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: - -* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. -* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: - * Always return the partial output immediately, even if it does not consist of a whole number of blocks. - * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. -* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. diff --git a/docs/3.0-migration-guide.d/gcm-multipart.md b/docs/3.0-migration-guide.d/gcm-multipart.md deleted file mode 100644 index ebc6397fa..000000000 --- a/docs/3.0-migration-guide.d/gcm-multipart.md +++ /dev/null @@ -1,12 +0,0 @@ -GCM multipart interface: application changes --------------------------------------------- - -The GCM module now supports arbitrary chunked input in the multipart interface. -This changes the interface for applications using the GCM module directly for multipart operations. -Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. - -* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data. -* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case: - * As long as the input remains block-aligned, the output length is exactly the input length, as before. - * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. -* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. diff --git a/docs/3.0-migration-guide.d/key-export.md b/docs/3.0-migration-guide.d/key-export.md deleted file mode 100644 index f8b3505b5..000000000 --- a/docs/3.0-migration-guide.d/key-export.md +++ /dev/null @@ -1,36 +0,0 @@ -SSL key export interface change -------------------------------- - -This affects users of the SSL key export APIs: -``` - mbedtls_ssl_conf_export_keys_cb() - mbedtls_ssl_conf_export_keys_ext_cb() -``` - -Those APIs have been removed and replaced by the new API -`mbedtls_ssl_set_export_keys_cb()`. This API differs from -the previous key export API in the following ways: - -- It is no longer bound to an SSL configuration, but to an - SSL context. This allows users to more easily identify the - connection an exported key belongs to. -- It no longer exports raw keys and IV. -- A secret type parameter has been added to identify which key - is being exported. For TLS 1.2, only the master secret is - exported, but upcoming TLS 1.3 support will add other kinds of keys. -- The callback now specifies a void return type, rather than - returning an error code. It is the responsibility of the application - to handle failures in the key export callback, for example by - shutting down the TLS connection. - -For users which do not rely on raw keys and IV, adjusting to the new -callback type should be straightforward - see the example programs -programs/ssl/ssl_client2 and programs/ssl/ssl_server2 for callbacks -for NSSKeylog, EAP-TLS and DTLS-SRTP. - -Users which require access to the raw keys used to secure application -traffic may derive those by hand based on the master secret and the -handshake transcript hashes which can be obtained from the raw data -on the wire. Such users are also encouraged to reach out to the -Mbed TLS team on the mailing list, to let the team know about their -use case. diff --git a/docs/3.0-migration-guide.d/mandatory-rng-param.md b/docs/3.0-migration-guide.d/mandatory-rng-param.md deleted file mode 100644 index f6aba08b1..000000000 --- a/docs/3.0-migration-guide.d/mandatory-rng-param.md +++ /dev/null @@ -1,40 +0,0 @@ -The RNG parameter is now mandatory for all functions that accept one --------------------------------------------------------------------- - -This change affects all users who called a function accepting a `f_rng` -parameter with `NULL` as the value of this argument; this is no longer -supported. - -The changed functions are: the X.509 CRT and CSR writing functions; the PK and -RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM -and ECDH that compute the shared secret; the scalar multiplication functions in -ECP. - -You now need to pass a properly seeded, cryptographically secure RNG to all -functions that accept a `f_rng` parameter. It is of course still possible to -pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a -context. - -Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` -configuration options) may have their own internal and are free to ignore the -`f_rng` argument but must allow users to pass one anyway. - -Some functions gained an RNG parameter --------------------------------------- - -This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, -`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and -`mbedtls_pk_parse_keyfile()`. - -You now need to pass a properly seeded, cryptographically secure RNG when -calling these functions. It is used for blinding, a counter-measure against -side-channel attacks. - -The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed ------------------------------------------------------------------- - -This doesn't affect users of the default configuration; it only affects people -who were explicitly setting this option. - -This was a trade-off between code size and counter-measures; it is no longer -relevant as the counter-measure is now always on at no cost in code size. diff --git a/docs/3.0-migration-guide.d/max-record-payload-api.md b/docs/3.0-migration-guide.d/max-record-payload-api.md deleted file mode 100644 index 0b34915f4..000000000 --- a/docs/3.0-migration-guide.d/max-record-payload-api.md +++ /dev/null @@ -1,11 +0,0 @@ -Remove MaximumFragmentLength (MFL) query API ------------------------------------------------------------------ - -This affects users which use the MFL query APIs -`mbedtls_ssl_get_{input,output}_max_frag_len()` to -infer upper bounds on the plaintext size of incoming and -outgoing record. - -Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` -instead, which also provides such upper bounds but takes more factors -than just the MFL configuration into account. diff --git a/docs/3.0-migration-guide.d/modify_MBEDTLS_ECP_FIXED_POINT_OPTIM_behaviour.md b/docs/3.0-migration-guide.d/modify_MBEDTLS_ECP_FIXED_POINT_OPTIM_behaviour.md deleted file mode 100644 index 91bec7269..000000000 --- a/docs/3.0-migration-guide.d/modify_MBEDTLS_ECP_FIXED_POINT_OPTIM_behaviour.md +++ /dev/null @@ -1,11 +0,0 @@ -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. - diff --git a/docs/3.0-migration-guide.d/modify_SHA384_option_behaviour.md b/docs/3.0-migration-guide.d/modify_SHA384_option_behaviour.md deleted file mode 100644 index 68eacfc16..000000000 --- a/docs/3.0-migration-guide.d/modify_SHA384_option_behaviour.md +++ /dev/null @@ -1,12 +0,0 @@ -Replaced MBEDTLS_SHA512_NO_SHA384 with MBEDTLS_SHA384_C ------------------------------------------------------- - -This does not affect users who use the default `mbedtls_config.h`. -MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is -enabled by default. - -If you were using a config file with both MBEDTLS_SHA512_C and -MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384. -If you were using a config file with MBEDTLS_SHA512_C and without -MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add -`#define MBEDTLS_SHA384_C` to your config file. diff --git a/docs/3.0-migration-guide.d/move_part_of_timing_module_out_of_the_library.md b/docs/3.0-migration-guide.d/move_part_of_timing_module_out_of_the_library.md deleted file mode 100644 index fa61e274b..000000000 --- a/docs/3.0-migration-guide.d/move_part_of_timing_module_out_of_the_library.md +++ /dev/null @@ -1,9 +0,0 @@ -Move part of timing module out of the library --- - -The change affects users who use any of the following functions: -`mbedtls_timing_self_test()`, `mbedtls_hardclock_poll()`, -`mbedtls_timing_hardclock()` and `mbedtls_set_alarm()`. - -If you were relying on these functions, you'll now need to change to using your -platform's corresponding functions directly. diff --git a/docs/3.0-migration-guide.d/out_size.md b/docs/3.0-migration-guide.d/out_size.md deleted file mode 100644 index 49d3246a7..000000000 --- a/docs/3.0-migration-guide.d/out_size.md +++ /dev/null @@ -1,9 +0,0 @@ -Extra parameter for the output buffer size ------------------------------------------- - -The following functions now take an extra parameter indicating the size of the output buffer: - -* `mbedtls_ecdsa_write_signature()`, `mbedtls_ecdsa_write_signature_restartable()` -* `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()` - -The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. diff --git a/docs/3.0-migration-guide.d/relaxed-psk-semantics.md b/docs/3.0-migration-guide.d/relaxed-psk-semantics.md deleted file mode 100644 index 6b0e79475..000000000 --- a/docs/3.0-migration-guide.d/relaxed-psk-semantics.md +++ /dev/null @@ -1,18 +0,0 @@ -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. diff --git a/docs/3.0-migration-guide.d/remove-enable-weak-ciphersuites.md b/docs/3.0-migration-guide.d/remove-enable-weak-ciphersuites.md deleted file mode 100644 index 917d1ac8a..000000000 --- a/docs/3.0-migration-guide.d/remove-enable-weak-ciphersuites.md +++ /dev/null @@ -1,12 +0,0 @@ -Remove the configuration to enable weak ciphersuites in SSL / TLS ------------------------------------------------------------------ - -This does not affect users who use the default `mbedtls_config.h`, as this option was -already off by default. - -If you were using a weak cipher, 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. - -If you were using a ciphersuite without encryption, you just have to -enable MBEDTLS_CIPHER_NULL_CIPHER now. diff --git a/docs/3.0-migration-guide.d/remove-max-content-len.md b/docs/3.0-migration-guide.d/remove-max-content-len.md deleted file mode 100644 index 40c7d539f..000000000 --- a/docs/3.0-migration-guide.d/remove-max-content-len.md +++ /dev/null @@ -1,10 +0,0 @@ -Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option -------------------------------------------------------------- - -This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to -set the maximum length of incoming and outgoing plaintext fragments, -which can save memory by reducing the size of the TLS I/O buffers. - -This option is replaced by the more fine-grained options -`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set -the maximum incoming and outgoing plaintext fragment lengths, respectively. diff --git a/docs/3.0-migration-guide.d/remove-null-entropy.md b/docs/3.0-migration-guide.d/remove-null-entropy.md deleted file mode 100644 index c38c93056..000000000 --- a/docs/3.0-migration-guide.d/remove-null-entropy.md +++ /dev/null @@ -1,11 +0,0 @@ -Remove the option to build the library without any entropy sources ------------------------------------------------------------------- - -This does not affect users who use the default `mbedtls_config.h`, as this option was -already off by default. - -If you were using the `MBEDTLS_TEST_NULL_ENTROPY` option and your platform -doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED` -and make sure your device is provisioned with a strong random seed. -Alternatively, for testing purposes only, you can create and register a fake -entropy function. diff --git a/docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md b/docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md deleted file mode 100644 index d21d5ed85..000000000 --- a/docs/3.0-migration-guide.d/remove-rsa-mode-parameter.md +++ /dev/null @@ -1,21 +0,0 @@ -Remove the mode parameter from RSA functions --------------------------------------------- - -This affects all users who use the RSA encryption, decryption, sign and -verify APIs. - -The RSA module no longer supports private-key operations with the public key or -vice versa. As a consequence, RSA operation functions no longer have a mode -parameter. If you were calling RSA operations with the normal mode (public key -for verification or encryption, private key for signature or decryption), remove -the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling -RSA operations with the wrong mode, which rarely makes sense from a security -perspective, this is no longer supported. - -Remove the RNG parameter from RSA verify functions --------------------------------------------------- - -RSA verification functions also no longer take random generator arguments (this -was only needed when using a private key). This affects all applications using -the RSA verify functions. - diff --git a/docs/3.0-migration-guide.d/remove-ssl-get-session_pointer.md b/docs/3.0-migration-guide.d/remove-ssl-get-session_pointer.md deleted file mode 100644 index a4a4895a8..000000000 --- a/docs/3.0-migration-guide.d/remove-ssl-get-session_pointer.md +++ /dev/null @@ -1,23 +0,0 @@ -Remove the SSL API mbedtls_ssl_get_session_pointer() ------------------------------------------------------------------ - -This affects two classes of users: - -1. Users who manually inspect parts of the current session through - direct structure field access. - -2. Users of session resumption who query the current session - via `mbedtls_ssl_get_session_pointer()` prior to saving or exporting - it via `mbedtls_ssl_session_copy()` or `mbedtls_ssl_session_save()`, - respectively. - -Migration paths: - -1. Mbed TLS 3.0 does not offer a migration path for the usecase 1: Like many - other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no - longer part of the public API in Mbed TLS 3.0, and direct structure field - access is no longer supported. Please see the corresponding migration guide. - -2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by - calls to `mbedtls_ssl_get_session()` as demonstrated in the example - program `programs/ssl/ssl_client2.c`. diff --git a/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION.md b/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION.md deleted file mode 100644 index 738fa81fd..000000000 --- a/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION.md +++ /dev/null @@ -1,17 +0,0 @@ -Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION --------------------------------------------------------------------------- - -This change does not affect users of the default configuration; it only affect -users who enable this option. - -The X.509 standard says that implementations must reject critical extensions that -they don't recognize, and this is what Mbed TLS does by default. This option -allowed to continue parsing those certificates but didn't provide a convenient -way to handle those extensions. - -The migration path from that option is to use the -`mbedtls_x509_crt_parse_der_with_ext_cb()` function which is functionally -equivalent to `mbedtls_x509_crt_parse_der()`, and/or -`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every -unsupported certificate extension and additionally the "certificate policies" -extension if it contains any unsupported certificate policies. diff --git a/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_CHECK_x_KEY_USAGE_options.md b/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_CHECK_x_KEY_USAGE_options.md deleted file mode 100644 index ebb4be946..000000000 --- a/docs/3.0-migration-guide.d/remove_MBEDTLS_X509_CHECK_x_KEY_USAGE_options.md +++ /dev/null @@ -1,18 +0,0 @@ -Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` -------------------------------------------------------------------- - -This change affects users who have chosen the configuration options to disable the -library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509 -certificates. - -The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE` -configuration options are removed and the X509 code now behaves as if they were -always enabled. It is consequently not possible anymore to disable at compile -time the verification of the `keyUsage` and `extendedKeyUsage` fields of X509 -certificates. - -The verification of the `keyUsage` and `extendedKeyUsage` fields is important, -disabling it can cause security issues and it is thus not recommended. If the -verification is for some reason undesirable, it can still be disabled by means -of the verification callback function passed to `mbedtls_x509_crt_verify()` (see -the documentation of this function for more information). diff --git a/docs/3.0-migration-guide.d/remove_MD2_MD4_RC4_Blowfish_XTEA.md b/docs/3.0-migration-guide.d/remove_MD2_MD4_RC4_Blowfish_XTEA.md deleted file mode 100644 index d199f2f13..000000000 --- a/docs/3.0-migration-guide.d/remove_MD2_MD4_RC4_Blowfish_XTEA.md +++ /dev/null @@ -1,8 +0,0 @@ -Remove MD2, MD4, RC4, Blowfish and XTEA algorithms --- - -This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. - -They are already niche or obsolete and most of them are weak or broken. For -those reasons possible users should consider switching to modern and safe -alternatives to be found in literature. diff --git a/docs/3.0-migration-guide.d/remove_SSL_DTLS_BADMAC_LIMIT_option.md b/docs/3.0-migration-guide.d/remove_SSL_DTLS_BADMAC_LIMIT_option.md deleted file mode 100644 index 3c0cbe944..000000000 --- a/docs/3.0-migration-guide.d/remove_SSL_DTLS_BADMAC_LIMIT_option.md +++ /dev/null @@ -1,11 +0,0 @@ -Remove MBEDTLS_SSL_DTLS_BADMAC_LIMIT option -------------------------------------------- - -This change does not affect users who used the default `mbedtls_config.h`, as the option -MBEDTLS_SSL_DTLS_BADMAC_LIMIT was already on by default. - -This option was a trade-off between functionality and code size: it allowed -users who didn't need that feature to avoid paying the cost in code size, by -disabling it. - -This option is no longer present, but its functionality is now always enabled. diff --git a/docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md b/docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md deleted file mode 100644 index 31c2ce862..000000000 --- a/docs/3.0-migration-guide.d/remove_deprecated_functions_and_constants.md +++ /dev/null @@ -1,74 +0,0 @@ -Deprecated functions were removed from AES ------------------------------------------- - -The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were -removed. - -If you're simply using the AES module, you should be calling the higher-level -functions `mbedtls_aes_crypt_xxx()`. - -If you're providing an alternative implementation using -`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be -replacing the removed functions with `mbedtls_internal_aes_encrypt()` and -`mbedtls_internal_aes_decrypt()` respectively. - -Deprecated functions were removed from bignum ---------------------------------------------- - -The function `mbedtls_mpi_is_prime()` was removed. Please use -`mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the -number of Miller-Rabin rounds. - -Deprecated functions were removed from cipher ---------------------------------------------- - -The functions `mbedtls_cipher_auth_encrypt()` and -`mbedtls_cipher_auth_decrypt()` were removed. They were superseded by -`mbedtls_cipher_auth_encrypt_ext()` and `mbedtls_cipher_auth_decrypt_ext()` -respectively which additionally support key wrapping algorithms such as -NIST_KW. - -Deprecated functions were removed from DRBGs --------------------------------------------- - -The functions `mbedtls_ctr_drbg_update()` and `mbedtls_hmac_drbg_update()` -were removed. They were superseded by `mbedtls_ctr_drbg_update_ret()` and -`mbedtls_hmac_drbg_update_ret()` respectively. - -Deprecated functions were removed from ECDSA --------------------------------------------- - -The functions `mbedtls_ecdsa_write_signature_det()` and -`mbedtls_ecdsa_sign_det()` were removed. They were superseded by -`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` -respectively. - -Deprecated functions were removed from SSL ------------------------------------------- - -The function `mbedtls_ssl_conf_dh_param()` was removed. Please use -`mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead. - -The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use -`mbedtls_ssl_get_max_out_record_payload()` and -`mbedtls_ssl_get_max_in_record_payload()` -instead. - -Deprecated hex-encoded primes were removed from DHM ---------------------------------------------------- - -The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`, -`MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`, -`MBEDTLS_DHM_RFC3526_MODP_3072_P`, `MBEDTLS_DHM_RFC3526_MODP_3072_G`, -`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were -removed. The primes from RFC 5114 are deprecated because their derivation is not -documented and therefore their usage constitutes a security risk; they are fully -removed from the library. Please use parameters from RFC3526 (still in the -library, only in binary form) or RFC 7919 (also available in the library) or -other trusted sources instead. - -Deprecated net.h file was removed ---------------------------------- - -The file `include/mbedtls/net.h` was removed because its only function was to -include `mbedtls/net_sockets.h` which now should be included directly. diff --git a/docs/3.0-migration-guide.d/remove_mbedtls_check_params_option.md b/docs/3.0-migration-guide.d/remove_mbedtls_check_params_option.md deleted file mode 100644 index 6f43aa37a..000000000 --- a/docs/3.0-migration-guide.d/remove_mbedtls_check_params_option.md +++ /dev/null @@ -1,33 +0,0 @@ -Remove MBEDTLS_CHECK_PARAMS option ----------------------------------- - -This change does not affect users who use the default configuration; it only -affects users who enabled that option. - -The option `MBEDTLS_CHECK_PARAMS` (disabled by default) enabled certain kinds -of “parameter validation”. It covered two kinds of validations: - -- In some functions that require a valid pointer, “parameter validation” checks -that the pointer is non-null. With the feature disabled, a null pointer is not -treated differently from any other invalid pointer, and typically leads to a -runtime crash. 90% of the uses of the feature are of this kind. -- In some functions that take an enum-like argument, “parameter validation” -checks that the value is a valid one. With the feature disabled, an invalid -value causes a silent default to one of the valid values. - -The default reaction to a failed check was to call a function -`mbedtls_param_failed()` which the application had to provide. If this function -returned, its caller returned an error `MBEDTLS_ERR_xxx_BAD_INPUT_DATA`. - -This feature was only used in some classic (non-PSA) cryptography modules. It was -not used in X.509, TLS or in PSA crypto, and it was not implemented in all -classic crypto modules. - -This feature has been removed. The library no longer checks for NULL pointers; -checks for enum-like arguments will be kept or re-introduced on a case-by-case -basis, but their presence will no longer be dependent on a compile-time option. - -Validation of enum-like values is somewhat useful, but not extremely important, -because the parameters concerned are usually constants in applications. - -For more information see issue #4313. diff --git a/docs/3.0-migration-guide.d/remove_ssl_record_checking.md b/docs/3.0-migration-guide.d/remove_ssl_record_checking.md deleted file mode 100644 index 7bee4ae9d..000000000 --- a/docs/3.0-migration-guide.d/remove_ssl_record_checking.md +++ /dev/null @@ -1,13 +0,0 @@ -Remove MBEDTLS_SSL_RECORD_CHECKING option and enable its action by default --------------------------------------------------------------------------- - -This change does not affect users who use the default mbedtls_config.h, as the -option MBEDTLS_SSL_RECORD_CHECKING was already on by default. - -This option was added only to control compilation of one function, -mbedtls_ssl_check_record(), which is only useful in some specific cases, so it -was made optional to allow users who don't need it to save some code space. -However, the same effect can be achieve by using link-time garbage collection. - -Users who changed the default setting of the option need to change the config/ -build system to remove that change. diff --git a/docs/3.0-migration-guide.d/remove_supp_for_extensions_in_pre-v3_X_509_certs.md b/docs/3.0-migration-guide.d/remove_supp_for_extensions_in_pre-v3_X_509_certs.md deleted file mode 100644 index 4c87f038f..000000000 --- a/docs/3.0-migration-guide.d/remove_supp_for_extensions_in_pre-v3_X_509_certs.md +++ /dev/null @@ -1,14 +0,0 @@ -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. diff --git a/docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md b/docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md deleted file mode 100644 index 73d621f78..000000000 --- a/docs/3.0-migration-guide.d/remove_support_for_tls_1.0_1.1_and_dtls_1.0.md +++ /dev/null @@ -1,27 +0,0 @@ -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. - -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. diff --git a/docs/3.0-migration-guide.d/rename_the__ret_functions.md b/docs/3.0-migration-guide.d/rename_the__ret_functions.md deleted file mode 100644 index 875164b25..000000000 --- a/docs/3.0-migration-guide.d/rename_the__ret_functions.md +++ /dev/null @@ -1,43 +0,0 @@ -Rename mbedtls_*_ret() cryptography functions whose deprecated variants -have been removed ------------------ - -This change affects users who were using the `mbedtls_*_ret()` cryptography -functions. - -Those functions were created based on now-deprecated functions according to a -requirement that a function needs to return a value. This change brings back the -original names of those functions. The renamed functions are: - -| name before this change | after the change | -|------------------------------|--------------------------| -| mbedtls_ctr_drbg_update_ret | mbedtls_ctr_drbg_update | -| mbedtls_hmac_drbg_update_ret | mbedtls_hmac_drbg_update | -| mbedtls_md5_starts_ret | mbedtls_md5_starts | -| mbedtls_md5_update_ret | mbedtls_md5_update | -| mbedtls_md5_finish_ret | mbedtls_md5_finish | -| mbedtls_md5_ret | mbedtls_md5 | -| mbedtls_ripemd160_starts_ret | mbedtls_ripemd160_starts | -| mbedtls_ripemd160_update_ret | mbedtls_ripemd160_update | -| mbedtls_ripemd160_finish_ret | mbedtls_ripemd160_finish | -| mbedtls_ripemd160_ret | mbedtls_ripemd160 | -| mbedtls_sha1_starts_ret | mbedtls_sha1_starts | -| mbedtls_sha1_update_ret | mbedtls_sha1_update | -| mbedtls_sha1_finish_ret | mbedtls_sha1_finish | -| mbedtls_sha1_ret | mbedtls_sha1 | -| mbedtls_sha256_starts_ret | mbedtls_sha256_starts | -| mbedtls_sha256_update_ret | mbedtls_sha256_update | -| mbedtls_sha256_finish_ret | mbedtls_sha256_finish | -| mbedtls_sha256_ret | mbedtls_sha256 | -| mbedtls_sha512_starts_ret | mbedtls_sha512_starts | -| mbedtls_sha512_update_ret | mbedtls_sha512_update | -| mbedtls_sha512_finish_ret | mbedtls_sha512_finish | -| mbedtls_sha512_ret | mbedtls_sha512 | - -To migrate to the this change the user can keep the `*_ret` names in their code -and include the `compat_2.x.h` header file which holds macros with proper -renaming or to rename those function in their code according to the list from -mentioned header file. - - - diff --git a/docs/3.0-migration-guide.d/require-matching-hashlen-rsa.md b/docs/3.0-migration-guide.d/require-matching-hashlen-rsa.md deleted file mode 100644 index d59a8d397..000000000 --- a/docs/3.0-migration-guide.d/require-matching-hashlen-rsa.md +++ /dev/null @@ -1,24 +0,0 @@ -Signature functions now require the hash length to match the expected value ---------------------------------------------------------------------------- - -This affects users of the PK API as well as users of the low-level API in the RSA module. Users of the PSA API or of the ECDSA module are unaffected. - -All the functions in the RSA module that accept a `hashlen` parameter used to -ignore it unless the `md_alg` parameter was `MBEDTLS_MD_NONE`, indicating raw -data was signed. The `hashlen` parameter is now always the size that is read -from the `hash` input buffer. This length must be equal to the output size of -the hash algorithm used when signing a hash. (The requirements when signing -raw data are unchanged.) This affects the following functions: - -* `mbedtls_rsa_pkcs1_sign`, `mbedtls_rsa_pkcs1_verify` -* `mbedtls_rsa_rsassa_pkcs1_v15_sign`, `mbedtls_rsa_rsassa_pkcs1_v15_verify` -* `mbedtls_rsa_rsassa_pss_sign`, `mbedtls_rsa_rsassa_pss_verify` -* `mbedtls_rsa_rsassa_pss_sign_ext`, `mbedtls_rsa_rsassa_pss_verify_ext` - -The signature functions in the PK module no longer accept 0 as the `hash_len` parameter. The `hash_len` parameter is now always the size that is read from the `hash` input buffer. This affects the following functions: - -* `mbedtls_pk_sign`, `mbedtls_pk_verify` -* `mbedtls_pk_sign_restartable`, `mbedtls_pk_verify_restartable` -* `mbedtls_pk_verify_ext` - -The migration path is to pass the correct value to those functions. diff --git a/docs/3.0-migration-guide.d/rsa-padding.md b/docs/3.0-migration-guide.d/rsa-padding.md deleted file mode 100644 index f10ece6f8..000000000 --- a/docs/3.0-migration-guide.d/rsa-padding.md +++ /dev/null @@ -1,29 +0,0 @@ -Remove the padding parameters from mbedtls_rsa_init() ------------------------------------------------------ - -This affects all users who use the RSA encryption, decryption, sign and -verify APIs. - -The function mbedtls_rsa_init() no longer supports selecting the PKCS#1 v2.1 -encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If -you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call -to mbedtls_rsa_init(), to call mbedtls_rsa_set_padding() to set it. - -To choose the padding type when initializing a context, instead of -```C - mbedtls_rsa_init(ctx, padding, hash_id); -``` -, use -```C - mbedtls_rsa_init(ctx); - mbedtls_rsa_set_padding(ctx, padding, hash_id); -``` - -To use PKCS#1 v1.5 padding, instead of -```C - mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, ); -``` -, just use -```C - mbedtls_rsa_init(ctx); -``` diff --git a/docs/3.0-migration-guide.d/separate_SHA224_from_SHA256.md b/docs/3.0-migration-guide.d/separate_SHA224_from_SHA256.md deleted file mode 100644 index f5a8d9873..000000000 --- a/docs/3.0-migration-guide.d/separate_SHA224_from_SHA256.md +++ /dev/null @@ -1,11 +0,0 @@ -Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C ------------------------------------------------------------------ - -This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C -was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are -enabled. - -If you were using custom config file with MBEDTLS_SHA256_C enabled, then -you will need to add `#define MBEDTLS_SHA224_C` option your config. -Current version of the library does not support enabling MBEDTLS_SHA256_C -without MBEDTLS_SHA224_C. diff --git a/docs/3.0-migration-guide.d/session-cache-api.md b/docs/3.0-migration-guide.d/session-cache-api.md deleted file mode 100644 index b28ce1946..000000000 --- a/docs/3.0-migration-guide.d/session-cache-api.md +++ /dev/null @@ -1,28 +0,0 @@ -Session Cache API Change ------------------------------------------------------------------ - -This affects users who use `mbedtls_ssl_conf_session_cache()` -to configure a custom session cache implementation different -from the one Mbed TLS implements in `library/ssl_cache.c`. - -Those users will need to modify the API of their session cache -implementation to that of a key-value store with keys being -session IDs and values being instances of `mbedtls_ssl_session`: - -``` -typedef int mbedtls_ssl_cache_get_t( void *data, - unsigned char const *session_id, - size_t session_id_len, - mbedtls_ssl_session *session ); -typedef int mbedtls_ssl_cache_set_t( void *data, - unsigned char const *session_id, - size_t session_id_len, - const mbedtls_ssl_session *session ); -``` - -Since the structure of `mbedtls_ssl_session` is no longer public from 3.0 -onwards, portable session cache implementations must not access fields of -`mbedtls_ssl_session`. See the corresponding migration guide. Users that -find themselves unable to migrate their session cache functionality without -accessing fields of `mbedtls_ssl_session` should describe their usecase -on the Mbed TLS mailing list. diff --git a/docs/3.0-migration-guide.d/sha512-output-type.md b/docs/3.0-migration-guide.d/sha512-output-type.md deleted file mode 100644 index c62a88159..000000000 --- a/docs/3.0-migration-guide.d/sha512-output-type.md +++ /dev/null @@ -1,8 +0,0 @@ -SHA-512 and SHA-256 output type change --------------------------- - -The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. - -This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. - -Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. diff --git a/docs/3.0-migration-guide.d/split_config.md b/docs/3.0-migration-guide.d/split_config.md deleted file mode 100644 index 6f433c5f7..000000000 --- a/docs/3.0-migration-guide.d/split_config.md +++ /dev/null @@ -1,20 +0,0 @@ -Introduce a level of indirection and versioning in the config files -------------------------------------------------------------------- - -`config.h` was split into `build_info.h` and `mbedtls_config.h`. - -* In code, use `#include `. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`. -* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before. -* If you had a tool that parsed the library version from `include/mbedtls/version.h`, this has moved to `include/mbedtls/build_info.h`. From C code, both headers now define the `MBEDTLS_VERSION_xxx` macros. - -Also, if you have a custom configuration file: - -* Don't include `check_config.h` or `config_psa.h` anymore. -* Don't define `MBEDTLS_CONFIG_H` anymore. - -A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced. -Defining it to a particular value will ensure that Mbed TLS interprets -the config file in a way that's compatible with the config file format -used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same -value. -The only value supported by Mbed TLS 3.0.0 is `0x03000000`. diff --git a/docs/3.0-migration-guide.d/ssl-error-code-cleanup.md b/docs/3.0-migration-guide.d/ssl-error-code-cleanup.md deleted file mode 100644 index ce795e5d9..000000000 --- a/docs/3.0-migration-guide.d/ssl-error-code-cleanup.md +++ /dev/null @@ -1,39 +0,0 @@ -Changes in the SSL error code space ------------------------------------------------------------------ - -# Removals - -This affects users manually checking for the following error codes: -- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` -- `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` -- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` -- `MBEDTLS_ERR_SSL_BAD_HS_XXX` - -Migration paths: - -- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` - should never be returned from Mbed TLS, and there is no need to check for it. - - Users should simply remove manual checks for those codes, and let the Mbed TLS - team know if -- contrary to the team's understanding -- there is in fact a situation - where one of them was ever returned. - -- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and - `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate - is too large to fit into the output buffers. - - Users should check for - `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially compare the size of their - own certificate against the configured size of the output buffer to understand if - the error is due to an overly large certificate. - -- All `MBEDTLS_ERR_SSL_BAD_HS_XXX` error code have been removed. - - Users should check for the newly introduced generic error codes - * `MBEDTLS_ERR_SSL_DECODE_ERROR` - * `MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER`, - * `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` - * `MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION` - * `MBEDTLS_ERR_SSL_BAD_CERTIFICATE` - * `MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME` - instead. diff --git a/docs/3.0-migration-guide.d/ssl-ticket-api.md b/docs/3.0-migration-guide.d/ssl-ticket-api.md deleted file mode 100644 index 23c53d671..000000000 --- a/docs/3.0-migration-guide.d/ssl-ticket-api.md +++ /dev/null @@ -1,30 +0,0 @@ -Modified semantics of mbedtls_ssl_{get,set}_session() ------------------------------------------------------------------ - -This affects users who call `mbedtls_ssl_get_session()` or -`mbedtls_ssl_set_session()` multiple times on the same SSL context -representing an established TLS 1.2 connection. -Those users will now observe the second call to fail with -`MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`. - -Migration path: -- Exporting the same TLS 1.2 connection multiple times via - `mbedtls_ssl_get_session()` leads to multiple copies of - the same session. This use of `mbedtls_ssl_get_session()` - is discouraged, and the following should be considered: - * If the various session copies are later loaded into - fresh SSL contexts via `mbedtls_ssl_set_session()`, - export via `mbedtls_ssl_get_session()` only once and - load the same session into different contexts via - `mbedtls_ssl_set_session()`. Since `mbedtls_ssl_set_session()` - makes a copy of the session that's being loaded, this - is functionally equivalent. - * If the various session copies are later serialized - via `mbedtls_ssl_session_save()`, export and serialize - the session only once via `mbedtls_ssl_get_session()` and - `mbedtls_ssl_session_save()` and make copies of the raw - data instead. -- Calling `mbedtls_ssl_set_session()` multiple times in Mbed TLS 2.x - is not useful since subsequent calls overwrite the effect of previous - calls. Applications achieve equivalent functional behaviour by - issuing only the very last call to `mbedtls_ssl_set_session()`. diff --git a/docs/3.0-migration-guide.d/turn_SSL_SRV_RESPECT_CLIENT_PREFERENCE_config_opt_to_runtime_opt.md b/docs/3.0-migration-guide.d/turn_SSL_SRV_RESPECT_CLIENT_PREFERENCE_config_opt_to_runtime_opt.md deleted file mode 100644 index 6f5a13aca..000000000 --- a/docs/3.0-migration-guide.d/turn_SSL_SRV_RESPECT_CLIENT_PREFERENCE_config_opt_to_runtime_opt.md +++ /dev/null @@ -1,14 +0,0 @@ -Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option --- - -This change affects users who were enabling MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE -option in the `mbedtls_config.h` - -This option has been removed and a new function with similar functionality has -been introduced into the SSL API. - -This new function `mbedtls_ssl_conf_preference_order()` can be used to -change the preferred order of ciphersuites on the server to those used on the client, -e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)` -has the same effect as enabling the removed option. The default state is to use -the server order of suites. diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 5fe6ebd7a..402fc6462 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -24,22 +24,22 @@ Deprecated functions were removed from hashing modules Modules: 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 functions `mbedtls_xxx_starts_ret()`, `mbedtls_xxx_update_ret()`, + `mbedtls_xxx_finish_ret()` and `mbedtls_xxx_ret()` were renamed to replace + the corresponding functions without `_ret` appended. Please call the name without `_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. + 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. + 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. @@ -194,3 +194,780 @@ 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. + + +Remove 3DES ciphersuites +-- + +This change does not affect users using default settings for 3DES in `mbedtls_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. +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. +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. +Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options +-- + +This change affects users who modified the default `mbedtls_config.h` padding granularity +settings, i.e. enabled at least one of the options. + +The `mbedtls_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. +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`. +Strengthen default algorithm selection for X.509 and TLS +-------------------------------------------------------- + +The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. + +Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. + +The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. + +The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. + +If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: +``` +mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; +my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); +``` + +If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. + +TLS now favors faster curves over larger curves +----------------------------------------------- + +The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves. + +If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection. +GCM interface changes: impact for alternative implementations +------------------------------------------------------------- + +The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: + +* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. +* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: + * Always return the partial output immediately, even if it does not consist of a whole number of blocks. + * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. +* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. +GCM multipart interface: application changes +-------------------------------------------- + +The GCM module now supports arbitrary chunked input in the multipart interface. +This changes the interface for applications using the GCM module directly for multipart operations. +Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. + +* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data. +* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case: + * As long as the input remains block-aligned, the output length is exactly the input length, as before. + * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. +* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. +SSL key export interface change +------------------------------- + +This affects users of the SSL key export APIs: +``` + mbedtls_ssl_conf_export_keys_cb() + mbedtls_ssl_conf_export_keys_ext_cb() +``` + +Those APIs have been removed and replaced by the new API +`mbedtls_ssl_set_export_keys_cb()`. This API differs from +the previous key export API in the following ways: + +- It is no longer bound to an SSL configuration, but to an + SSL context. This allows users to more easily identify the + connection an exported key belongs to. +- It no longer exports raw keys and IV. +- A secret type parameter has been added to identify which key + is being exported. For TLS 1.2, only the master secret is + exported, but upcoming TLS 1.3 support will add other kinds of keys. +- The callback now specifies a void return type, rather than + returning an error code. It is the responsibility of the application + to handle failures in the key export callback, for example by + shutting down the TLS connection. + +For users which do not rely on raw keys and IV, adjusting to the new +callback type should be straightforward - see the example programs +programs/ssl/ssl_client2 and programs/ssl/ssl_server2 for callbacks +for NSSKeylog, EAP-TLS and DTLS-SRTP. + +Users which require access to the raw keys used to secure application +traffic may derive those by hand based on the master secret and the +handshake transcript hashes which can be obtained from the raw data +on the wire. Such users are also encouraged to reach out to the +Mbed TLS team on the mailing list, to let the team know about their +use case. +The RNG parameter is now mandatory for all functions that accept one +-------------------------------------------------------------------- + +This change affects all users who called a function accepting a `f_rng` +parameter with `NULL` as the value of this argument; this is no longer +supported. + +The changed functions are: the X.509 CRT and CSR writing functions; the PK and +RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM +and ECDH that compute the shared secret; the scalar multiplication functions in +ECP. + +You now need to pass a properly seeded, cryptographically secure RNG to all +functions that accept a `f_rng` parameter. It is of course still possible to +pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a +context. + +Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` +configuration options) may have their own internal and are free to ignore the +`f_rng` argument but must allow users to pass one anyway. + +Some functions gained an RNG parameter +-------------------------------------- + +This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, +`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and +`mbedtls_pk_parse_keyfile()`. + +You now need to pass a properly seeded, cryptographically secure RNG when +calling these functions. It is used for blinding, a counter-measure against +side-channel attacks. + +The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed +------------------------------------------------------------------ + +This doesn't affect users of the default configuration; it only affects people +who were explicitly setting this option. + +This was a trade-off between code size and counter-measures; it is no longer +relevant as the counter-measure is now always on at no cost in code size. +Remove MaximumFragmentLength (MFL) query API +----------------------------------------------------------------- + +This affects users which use the MFL query APIs +`mbedtls_ssl_get_{input,output}_max_frag_len()` to +infer upper bounds on the plaintext size of incoming and +outgoing record. + +Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` +instead, which also provides such upper bounds but takes more factors +than just the MFL configuration into account. +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. + +Replaced MBEDTLS_SHA512_NO_SHA384 with MBEDTLS_SHA384_C +------------------------------------------------------ + +This does not affect users who use the default `mbedtls_config.h`. +MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is +enabled by default. + +If you were using a config file with both MBEDTLS_SHA512_C and +MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384. +If you were using a config file with MBEDTLS_SHA512_C and without +MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add +`#define MBEDTLS_SHA384_C` to your config file. +Move part of timing module out of the library +-- + +The change affects users who use any of the following functions: +`mbedtls_timing_self_test()`, `mbedtls_hardclock_poll()`, +`mbedtls_timing_hardclock()` and `mbedtls_set_alarm()`. + +If you were relying on these functions, you'll now need to change to using your +platform's corresponding functions directly. +Extra parameter for the output buffer size +------------------------------------------ + +The following functions now take an extra parameter indicating the size of the output buffer: + +* `mbedtls_ecdsa_write_signature()`, `mbedtls_ecdsa_write_signature_restartable()` +* `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()` + +The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. +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. +Remove the configuration to enable weak ciphersuites in SSL / TLS +----------------------------------------------------------------- + +This does not affect users who use the default `mbedtls_config.h`, as this option was +already off by default. + +If you were using a weak cipher, 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. + +If you were using a ciphersuite without encryption, you just have to +enable MBEDTLS_CIPHER_NULL_CIPHER now. +Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option +------------------------------------------------------------- + +This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to +set the maximum length of incoming and outgoing plaintext fragments, +which can save memory by reducing the size of the TLS I/O buffers. + +This option is replaced by the more fine-grained options +`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set +the maximum incoming and outgoing plaintext fragment lengths, respectively. +Remove the option to build the library without any entropy sources +------------------------------------------------------------------ + +This does not affect users who use the default `mbedtls_config.h`, as this option was +already off by default. + +If you were using the `MBEDTLS_TEST_NULL_ENTROPY` option and your platform +doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED` +and make sure your device is provisioned with a strong random seed. +Alternatively, for testing purposes only, you can create and register a fake +entropy function. +Remove the mode parameter from RSA functions +-------------------------------------------- + +This affects all users who use the RSA encryption, decryption, sign and +verify APIs. + +The RSA module no longer supports private-key operations with the public key or +vice versa. As a consequence, RSA operation functions no longer have a mode +parameter. If you were calling RSA operations with the normal mode (public key +for verification or encryption, private key for signature or decryption), remove +the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling +RSA operations with the wrong mode, which rarely makes sense from a security +perspective, this is no longer supported. + +Remove the RNG parameter from RSA verify functions +-------------------------------------------------- + +RSA verification functions also no longer take random generator arguments (this +was only needed when using a private key). This affects all applications using +the RSA verify functions. + +Remove the SSL API mbedtls_ssl_get_session_pointer() +----------------------------------------------------------------- + +This affects two classes of users: + +1. Users who manually inspect parts of the current session through + direct structure field access. + +2. Users of session resumption who query the current session + via `mbedtls_ssl_get_session_pointer()` prior to saving or exporting + it via `mbedtls_ssl_session_copy()` or `mbedtls_ssl_session_save()`, + respectively. + +Migration paths: + +1. Mbed TLS 3.0 does not offer a migration path for the usecase 1: Like many + other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no + longer part of the public API in Mbed TLS 3.0, and direct structure field + access is no longer supported. Please see the corresponding migration guide. + +2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by + calls to `mbedtls_ssl_get_session()` as demonstrated in the example + program `programs/ssl/ssl_client2.c`. + Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION +-------------------------------------------------------------------------- + +This change does not affect users of the default configuration; it only affect +users who enable this option. + +The X.509 standard says that implementations must reject critical extensions that +they don't recognize, and this is what Mbed TLS does by default. This option +allowed to continue parsing those certificates but didn't provide a convenient +way to handle those extensions. + +The migration path from that option is to use the +`mbedtls_x509_crt_parse_der_with_ext_cb()` function which is functionally +equivalent to `mbedtls_x509_crt_parse_der()`, and/or +`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every +unsupported certificate extension and additionally the "certificate policies" +extension if it contains any unsupported certificate policies. +Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` +------------------------------------------------------------------- + +This change affects users who have chosen the configuration options to disable the +library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509 +certificates. + +The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE` +configuration options are removed and the X509 code now behaves as if they were +always enabled. It is consequently not possible anymore to disable at compile +time the verification of the `keyUsage` and `extendedKeyUsage` fields of X509 +certificates. + +The verification of the `keyUsage` and `extendedKeyUsage` fields is important, +disabling it can cause security issues and it is thus not recommended. If the +verification is for some reason undesirable, it can still be disabled by means +of the verification callback function passed to `mbedtls_x509_crt_verify()` (see +the documentation of this function for more information). +Remove MD2, MD4, RC4, Blowfish and XTEA algorithms +-- + +This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. + +They are already niche or obsolete and most of them are weak or broken. For +those reasons possible users should consider switching to modern and safe +alternatives to be found in literature. +Remove MBEDTLS_SSL_DTLS_BADMAC_LIMIT option +------------------------------------------- + +This change does not affect users who used the default `mbedtls_config.h`, as the option +MBEDTLS_SSL_DTLS_BADMAC_LIMIT was already on by default. + +This option was a trade-off between functionality and code size: it allowed +users who didn't need that feature to avoid paying the cost in code size, by +disabling it. + +This option is no longer present, but its functionality is now always enabled. +Deprecated functions were removed from AES +------------------------------------------ + +The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were +removed. + +If you're simply using the AES module, you should be calling the higher-level +functions `mbedtls_aes_crypt_xxx()`. + +If you're providing an alternative implementation using +`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be +replacing the removed functions with `mbedtls_internal_aes_encrypt()` and +`mbedtls_internal_aes_decrypt()` respectively. + +Deprecated functions were removed from bignum +--------------------------------------------- + +The function `mbedtls_mpi_is_prime()` was removed. Please use +`mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the +number of Miller-Rabin rounds. + +Deprecated functions were removed from cipher +--------------------------------------------- + +The functions `mbedtls_cipher_auth_encrypt()` and +`mbedtls_cipher_auth_decrypt()` were removed. They were superseded by +`mbedtls_cipher_auth_encrypt_ext()` and `mbedtls_cipher_auth_decrypt_ext()` +respectively which additionally support key wrapping algorithms such as +NIST_KW. + +Deprecated functions were removed from DRBGs +-------------------------------------------- + +The functions `mbedtls_ctr_drbg_update()` and `mbedtls_hmac_drbg_update()` +were removed. They were superseded by `mbedtls_ctr_drbg_update_ret()` and +`mbedtls_hmac_drbg_update_ret()` respectively. + +Deprecated functions were removed from ECDSA +-------------------------------------------- + +The functions `mbedtls_ecdsa_write_signature_det()` and +`mbedtls_ecdsa_sign_det()` were removed. They were superseded by +`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` +respectively. + +Deprecated functions were removed from SSL +------------------------------------------ + +The function `mbedtls_ssl_conf_dh_param()` was removed. Please use +`mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead. + +The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use +`mbedtls_ssl_get_max_out_record_payload()` and +`mbedtls_ssl_get_max_in_record_payload()` +instead. + +Deprecated hex-encoded primes were removed from DHM +--------------------------------------------------- + +The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`, +`MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`, +`MBEDTLS_DHM_RFC3526_MODP_3072_P`, `MBEDTLS_DHM_RFC3526_MODP_3072_G`, +`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were +removed. The primes from RFC 5114 are deprecated because their derivation is not +documented and therefore their usage constitutes a security risk; they are fully +removed from the library. Please use parameters from RFC3526 (still in the +library, only in binary form) or RFC 7919 (also available in the library) or +other trusted sources instead. + +Deprecated net.h file was removed +--------------------------------- + +The file `include/mbedtls/net.h` was removed because its only function was to +include `mbedtls/net_sockets.h` which now should be included directly. +Remove MBEDTLS_CHECK_PARAMS option +---------------------------------- + +This change does not affect users who use the default configuration; it only +affects users who enabled that option. + +The option `MBEDTLS_CHECK_PARAMS` (disabled by default) enabled certain kinds +of “parameter validation”. It covered two kinds of validations: + +- In some functions that require a valid pointer, “parameter validation” checks +that the pointer is non-null. With the feature disabled, a null pointer is not +treated differently from any other invalid pointer, and typically leads to a +runtime crash. 90% of the uses of the feature are of this kind. +- In some functions that take an enum-like argument, “parameter validation” +checks that the value is a valid one. With the feature disabled, an invalid +value causes a silent default to one of the valid values. + +The default reaction to a failed check was to call a function +`mbedtls_param_failed()` which the application had to provide. If this function +returned, its caller returned an error `MBEDTLS_ERR_xxx_BAD_INPUT_DATA`. + +This feature was only used in some classic (non-PSA) cryptography modules. It was +not used in X.509, TLS or in PSA crypto, and it was not implemented in all +classic crypto modules. + +This feature has been removed. The library no longer checks for NULL pointers; +checks for enum-like arguments will be kept or re-introduced on a case-by-case +basis, but their presence will no longer be dependent on a compile-time option. + +Validation of enum-like values is somewhat useful, but not extremely important, +because the parameters concerned are usually constants in applications. + +For more information see issue #4313. +Remove MBEDTLS_SSL_RECORD_CHECKING option and enable its action by default +-------------------------------------------------------------------------- + +This change does not affect users who use the default mbedtls_config.h, as the +option MBEDTLS_SSL_RECORD_CHECKING was already on by default. + +This option was added only to control compilation of one function, +mbedtls_ssl_check_record(), which is only useful in some specific cases, so it +was made optional to allow users who don't need it to save some code space. +However, the same effect can be achieve by using link-time garbage collection. + +Users who changed the default setting of the option need to change the config/ +build system to remove that change. +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. +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. + +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. + +Rename mbedtls_*_ret() cryptography functions whose deprecated variants have been removed +----------------- + +This change affects users who were using the `mbedtls_*_ret()` cryptography +functions. + +Those functions were created based on now-deprecated functions according to a +requirement that a function needs to return a value. This change brings back the +original names of those functions. The renamed functions are: + +| name before this change | after the change | +|------------------------------|--------------------------| +| mbedtls_ctr_drbg_update_ret | mbedtls_ctr_drbg_update | +| mbedtls_hmac_drbg_update_ret | mbedtls_hmac_drbg_update | +| mbedtls_md5_starts_ret | mbedtls_md5_starts | +| mbedtls_md5_update_ret | mbedtls_md5_update | +| mbedtls_md5_finish_ret | mbedtls_md5_finish | +| mbedtls_md5_ret | mbedtls_md5 | +| mbedtls_ripemd160_starts_ret | mbedtls_ripemd160_starts | +| mbedtls_ripemd160_update_ret | mbedtls_ripemd160_update | +| mbedtls_ripemd160_finish_ret | mbedtls_ripemd160_finish | +| mbedtls_ripemd160_ret | mbedtls_ripemd160 | +| mbedtls_sha1_starts_ret | mbedtls_sha1_starts | +| mbedtls_sha1_update_ret | mbedtls_sha1_update | +| mbedtls_sha1_finish_ret | mbedtls_sha1_finish | +| mbedtls_sha1_ret | mbedtls_sha1 | +| mbedtls_sha256_starts_ret | mbedtls_sha256_starts | +| mbedtls_sha256_update_ret | mbedtls_sha256_update | +| mbedtls_sha256_finish_ret | mbedtls_sha256_finish | +| mbedtls_sha256_ret | mbedtls_sha256 | +| mbedtls_sha512_starts_ret | mbedtls_sha512_starts | +| mbedtls_sha512_update_ret | mbedtls_sha512_update | +| mbedtls_sha512_finish_ret | mbedtls_sha512_finish | +| mbedtls_sha512_ret | mbedtls_sha512 | + +To migrate to the this change the user can keep the `*_ret` names in their code +and include the `compat_2.x.h` header file which holds macros with proper +renaming or to rename those function in their code according to the list from +mentioned header file. + + + +Signature functions now require the hash length to match the expected value +--------------------------------------------------------------------------- + +This affects users of the PK API as well as users of the low-level API in the RSA module. Users of the PSA API or of the ECDSA module are unaffected. + +All the functions in the RSA module that accept a `hashlen` parameter used to +ignore it unless the `md_alg` parameter was `MBEDTLS_MD_NONE`, indicating raw +data was signed. The `hashlen` parameter is now always the size that is read +from the `hash` input buffer. This length must be equal to the output size of +the hash algorithm used when signing a hash. (The requirements when signing +raw data are unchanged.) This affects the following functions: + +* `mbedtls_rsa_pkcs1_sign`, `mbedtls_rsa_pkcs1_verify` +* `mbedtls_rsa_rsassa_pkcs1_v15_sign`, `mbedtls_rsa_rsassa_pkcs1_v15_verify` +* `mbedtls_rsa_rsassa_pss_sign`, `mbedtls_rsa_rsassa_pss_verify` +* `mbedtls_rsa_rsassa_pss_sign_ext`, `mbedtls_rsa_rsassa_pss_verify_ext` + +The signature functions in the PK module no longer accept 0 as the `hash_len` parameter. The `hash_len` parameter is now always the size that is read from the `hash` input buffer. This affects the following functions: + +* `mbedtls_pk_sign`, `mbedtls_pk_verify` +* `mbedtls_pk_sign_restartable`, `mbedtls_pk_verify_restartable` +* `mbedtls_pk_verify_ext` + +The migration path is to pass the correct value to those functions. +Remove the padding parameters from mbedtls_rsa_init() +----------------------------------------------------- + +This affects all users who use the RSA encryption, decryption, sign and +verify APIs. + +The function mbedtls_rsa_init() no longer supports selecting the PKCS#1 v2.1 +encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If +you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call +to mbedtls_rsa_init(), to call mbedtls_rsa_set_padding() to set it. + +To choose the padding type when initializing a context, instead of +```C + mbedtls_rsa_init(ctx, padding, hash_id); +``` +, use +```C + mbedtls_rsa_init(ctx); + mbedtls_rsa_set_padding(ctx, padding, hash_id); +``` + +To use PKCS#1 v1.5 padding, instead of +```C + mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, ); +``` +, just use +```C + mbedtls_rsa_init(ctx); +``` +Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C +----------------------------------------------------------------- + +This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C +was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are +enabled. + +If you were using custom config file with MBEDTLS_SHA256_C enabled, then +you will need to add `#define MBEDTLS_SHA224_C` option your config. +Current version of the library does not support enabling MBEDTLS_SHA256_C +without MBEDTLS_SHA224_C. +Session Cache API Change +----------------------------------------------------------------- + +This affects users who use `mbedtls_ssl_conf_session_cache()` +to configure a custom session cache implementation different +from the one Mbed TLS implements in `library/ssl_cache.c`. + +Those users will need to modify the API of their session cache +implementation to that of a key-value store with keys being +session IDs and values being instances of `mbedtls_ssl_session`: + +``` +typedef int mbedtls_ssl_cache_get_t( void *data, + unsigned char const *session_id, + size_t session_id_len, + mbedtls_ssl_session *session ); +typedef int mbedtls_ssl_cache_set_t( void *data, + unsigned char const *session_id, + size_t session_id_len, + const mbedtls_ssl_session *session ); +``` + +Since the structure of `mbedtls_ssl_session` is no longer public from 3.0 +onwards, portable session cache implementations must not access fields of +`mbedtls_ssl_session`. See the corresponding migration guide. Users that +find themselves unable to migrate their session cache functionality without +accessing fields of `mbedtls_ssl_session` should describe their usecase +on the Mbed TLS mailing list. +SHA-512 and SHA-256 output type change +-------------------------- + +The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. + +This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. + +Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. +Introduce a level of indirection and versioning in the config files +------------------------------------------------------------------- + +`config.h` was split into `build_info.h` and `mbedtls_config.h`. + +* In code, use `#include `. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`. +* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before. +* If you had a tool that parsed the library version from `include/mbedtls/version.h`, this has moved to `include/mbedtls/build_info.h`. From C code, both headers now define the `MBEDTLS_VERSION_xxx` macros. + +Also, if you have a custom configuration file: + +* Don't include `check_config.h` or `config_psa.h` anymore. +* Don't define `MBEDTLS_CONFIG_H` anymore. + +A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced. +Defining it to a particular value will ensure that Mbed TLS interprets +the config file in a way that's compatible with the config file format +used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same +value. +The only value supported by Mbed TLS 3.0.0 is `0x03000000`. +Removal of some SSL error codes +----------------------------------------------------------------- + +This affects users manually checking for the following error codes: +- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` +- `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` +- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` +- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` +- `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` +- `MBEDTLS_ERR_SSL_BAD_HS_XXX` + +Migration paths: +- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` + should never be returned from Mbed TLS, and there is no need to check for it. + Users should simply remove manual checks for those codes, and let the Mbed TLS + team know if -- contrary to the team's understanding -- there is in fact a situation + where one of them was ever returned. +- `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and + `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate + is too large to fit into the output buffers. Users should check for + `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially compare the size of their + own certificate against the configured size of the output buffer to understand if + the error is due to an overly large certificate. +-`MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN`, `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` and all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`. + + Modified semantics of mbedtls_ssl_{get,set}_session() +----------------------------------------------------------------- + +This affects users who call `mbedtls_ssl_get_session()` or +`mbedtls_ssl_set_session()` multiple times on the same SSL context +representing an established TLS 1.2 connection. +Those users will now observe the second call to fail with +`MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`. + +Migration path: +- Exporting the same TLS 1.2 connection multiple times via + `mbedtls_ssl_get_session()` leads to multiple copies of + the same session. This use of `mbedtls_ssl_get_session()` + is discouraged, and the following should be considered: + * If the various session copies are later loaded into + fresh SSL contexts via `mbedtls_ssl_set_session()`, + export via `mbedtls_ssl_get_session()` only once and + load the same session into different contexts via + `mbedtls_ssl_set_session()`. Since `mbedtls_ssl_set_session()` + makes a copy of the session that's being loaded, this + is functionally equivalent. + * If the various session copies are later serialized + via `mbedtls_ssl_session_save()`, export and serialize + the session only once via `mbedtls_ssl_get_session()` and + `mbedtls_ssl_session_save()` and make copies of the raw + data instead. +- Calling `mbedtls_ssl_set_session()` multiple times in Mbed TLS 2.x + is not useful since subsequent calls overwrite the effect of previous + calls. Applications achieve equivalent functional behaviour by + issuing only the very last call to `mbedtls_ssl_set_session()`. + + Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option + -- + +This change affects users who were enabling MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE +option in the `mbedtls_config.h` + +This option has been removed and a new function with similar functionality has +been introduced into the SSL API. + +This new function `mbedtls_ssl_conf_preference_order()` can be used to +change the preferred order of ciphersuites on the server to those used on the client, +e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)` +has the same effect as enabling the removed option. The default state is to use +the server order of suites. From e45e6401afc8473e561b0800d0e00315f8b853b9 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 13:21:55 +0100 Subject: [PATCH 02/51] Re-order to put some more significant items at the top Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 170 ++++++++++++++++++------------------ 1 file changed, 87 insertions(+), 83 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 402fc6462..787490915 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -9,15 +9,85 @@ 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 ----------------------------------------- +Introduce a level of indirection and versioning in the config files +------------------------------------------------------------------- -Various functions in the PK and ASN.1 modules had a `const` qualifier added to -some of their parameters. +`config.h` was split into `build_info.h` and `mbedtls_config.h`. -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. +* In code, use `#include `. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`. +* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before. +* If you had a tool that parsed the library version from `include/mbedtls/version.h`, this has moved to `include/mbedtls/build_info.h`. From C code, both headers now define the `MBEDTLS_VERSION_xxx` macros. + +Also, if you have a custom configuration file: + +* Don't include `check_config.h` or `config_psa.h` anymore. +* Don't define `MBEDTLS_CONFIG_H` anymore. + +A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced. +Defining it to a particular value will ensure that Mbed TLS interprets +the config file in a way that's compatible with the config file format +used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same +value. +The only value supported by Mbed TLS 3.0.0 is `0x03000000`. + +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. + +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. + +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. +`0`. + +Strengthen default algorithm selection for X.509 and TLS +-------------------------------------------------------- + +The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. + +Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. + +The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. + +The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. + +If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: +``` +mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; +my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); +``` + +If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. Deprecated functions were removed from hashing modules ------------------------------------------------------ @@ -101,17 +171,6 @@ 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 truncated HMAC --------------------------------- @@ -252,25 +311,6 @@ 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`. -Strengthen default algorithm selection for X.509 and TLS --------------------------------------------------------- - -The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. - -Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. - -The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. - -The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. - -If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: -``` -mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; -my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); -``` - -If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. TLS now favors faster curves over larger curves ----------------------------------------------- @@ -711,33 +751,6 @@ configuration. If you are working with the pre-V3 certificates you need to switch to the current ones. -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. - -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. Rename mbedtls_*_ret() cryptography functions whose deprecated variants have been removed ----------------- @@ -881,26 +894,7 @@ The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, ` This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. -Introduce a level of indirection and versioning in the config files -------------------------------------------------------------------- -`config.h` was split into `build_info.h` and `mbedtls_config.h`. - -* In code, use `#include `. Don't include `mbedtls/config.h` and don't refer to `MBEDTLS_CONFIG_FILE`. -* In build tools, edit `mbedtls_config.h`, or edit `MBEDTLS_CONFIG_FILE` as before. -* If you had a tool that parsed the library version from `include/mbedtls/version.h`, this has moved to `include/mbedtls/build_info.h`. From C code, both headers now define the `MBEDTLS_VERSION_xxx` macros. - -Also, if you have a custom configuration file: - -* Don't include `check_config.h` or `config_psa.h` anymore. -* Don't define `MBEDTLS_CONFIG_H` anymore. - -A config file version symbol, `MBEDTLS_CONFIG_VERSION` was introduced. -Defining it to a particular value will ensure that Mbed TLS interprets -the config file in a way that's compatible with the config file format -used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same -value. -The only value supported by Mbed TLS 3.0.0 is `0x03000000`. Removal of some SSL error codes ----------------------------------------------------------------- @@ -971,3 +965,13 @@ change the preferred order of ciphersuites on the server to those used on the cl e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)` has the same effect as enabling the removed option. The default state is to use the server order of suites. + +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. From 1aea40427f519b26f7cb088e25b1e30b9a05b4de Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 13:27:15 +0100 Subject: [PATCH 03/51] Add a very short summary Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 787490915..f64b20954 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -9,6 +9,12 @@ 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? +The changes are detailed below, and include: +- Removal of many insecure / obsolete features +- Tidying up of configuration options (including removing some less useful options) +- Changing function signatures (e.g., adding return codes or extra parameters); introducing const to arguments. +- Removal of functions marked as deprecated in 2.x + Introduce a level of indirection and versioning in the config files ------------------------------------------------------------------- From 759c0109f236156119b2fe9878052a8fbdd480f8 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 15:55:08 +0100 Subject: [PATCH 04/51] Fix errors in migration guide Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 74 +++++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index f64b20954..ef6df7ae5 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -10,6 +10,7 @@ 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? The changes are detailed below, and include: + - Removal of many insecure / obsolete features - Tidying up of configuration options (including removing some less useful options) - Changing function signatures (e.g., adding return codes or extra parameters); introducing const to arguments. @@ -36,7 +37,7 @@ used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same value. The only value supported by Mbed TLS 3.0.0 is `0x03000000`. -Remove suport for TLS 1.0, 1.1 and DTLS 1.0 +Remove support 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. @@ -53,7 +54,7 @@ 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 +future 1.3 which will have a different version negotiation 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. @@ -260,7 +261,6 @@ 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. - Remove 3DES ciphersuites -- @@ -270,7 +270,8 @@ 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. +The migration path here is to chose from the recommended in literature alternatives. + CCM interface changes: impact for alternative implementations ------------------------------------------------------------- @@ -280,6 +281,7 @@ 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. + Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations ---------------------------------------------------------------------------- @@ -295,6 +297,7 @@ 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. + Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options -- @@ -309,6 +312,7 @@ code maintenance. The new single option `MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY` can be used for both DTLS-CID and TLS 1.3. + Change the API to allow adding critical extensions to CSRs ------------------------------------------------------------------ @@ -316,7 +320,7 @@ 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 +extension included in a CSR as critical. To get the previous behavior pass TODO TLS now favors faster curves over larger curves ----------------------------------------------- @@ -324,6 +328,7 @@ TLS now favors faster curves over larger curves The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves. If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection. + GCM interface changes: impact for alternative implementations ------------------------------------------------------------- @@ -334,6 +339,7 @@ The GCM multipart interface has changed as described in [“GCM multipart interf * Always return the partial output immediately, even if it does not consist of a whole number of blocks. * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. * `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. + GCM multipart interface: application changes -------------------------------------------- @@ -346,6 +352,7 @@ Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `ps * As long as the input remains block-aligned, the output length is exactly the input length, as before. * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. * `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. + SSL key export interface change ------------------------------- @@ -382,6 +389,7 @@ handshake transcript hashes which can be obtained from the raw data on the wire. Such users are also encouraged to reach out to the Mbed TLS team on the mailing list, to let the team know about their use case. + The RNG parameter is now mandatory for all functions that accept one -------------------------------------------------------------------- @@ -422,6 +430,7 @@ who were explicitly setting this option. This was a trade-off between code size and counter-measures; it is no longer relevant as the counter-measure is now always on at no cost in code size. + Remove MaximumFragmentLength (MFL) query API ----------------------------------------------------------------- @@ -433,7 +442,8 @@ outgoing record. Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` instead, which also provides such upper bounds but takes more factors than just the MFL configuration into account. -Change MBEDTLS_ECP_FIXED_POINT_OPTIM behaviour + +Change MBEDTLS_ECP_FIXED_POINT_OPTIM behavior ------------------------------------------------------ The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increase code size and it does @@ -456,6 +466,7 @@ MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384. If you were using a config file with MBEDTLS_SHA512_C and without MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add `#define MBEDTLS_SHA384_C` to your config file. + Move part of timing module out of the library -- @@ -465,6 +476,7 @@ The change affects users who use any of the following functions: If you were relying on these functions, you'll now need to change to using your platform's corresponding functions directly. + Extra parameter for the output buffer size ------------------------------------------ @@ -474,6 +486,7 @@ The following functions now take an extra parameter indicating the size of the o * `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()` The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. + Relaxed semantics for PSK configuration ----------------------------------------------------------------- @@ -492,6 +505,7 @@ 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. + Remove the configuration to enable weak ciphersuites in SSL / TLS ----------------------------------------------------------------- @@ -504,6 +518,7 @@ and if your peer doesn't support any, encourage them to upgrade their software. If you were using a ciphersuite without encryption, you just have to enable MBEDTLS_CIPHER_NULL_CIPHER now. + Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option ------------------------------------------------------------- @@ -514,6 +529,7 @@ which can save memory by reducing the size of the TLS I/O buffers. This option is replaced by the more fine-grained options `MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set the maximum incoming and outgoing plaintext fragment lengths, respectively. + Remove the option to build the library without any entropy sources ------------------------------------------------------------------ @@ -525,6 +541,7 @@ doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED` and make sure your device is provisioned with a strong random seed. Alternatively, for testing purposes only, you can create and register a fake entropy function. + Remove the mode parameter from RSA functions -------------------------------------------- @@ -561,7 +578,7 @@ This affects two classes of users: Migration paths: -1. Mbed TLS 3.0 does not offer a migration path for the usecase 1: Like many +1. Mbed TLS 3.0 does not offer a migration path for the use case 1: Like many other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no longer part of the public API in Mbed TLS 3.0, and direct structure field access is no longer supported. Please see the corresponding migration guide. @@ -569,10 +586,11 @@ Migration paths: 2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by calls to `mbedtls_ssl_get_session()` as demonstrated in the example program `programs/ssl/ssl_client2.c`. - Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION + +Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION -------------------------------------------------------------------------- -This change does not affect users of the default configuration; it only affect +This change does not affect users of the default configuration; it only affects users who enable this option. The X.509 standard says that implementations must reject critical extensions that @@ -586,6 +604,7 @@ equivalent to `mbedtls_x509_crt_parse_der()`, and/or `mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every unsupported certificate extension and additionally the "certificate policies" extension if it contains any unsupported certificate policies. + Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` ------------------------------------------------------------------- @@ -604,6 +623,7 @@ disabling it can cause security issues and it is thus not recommended. If the verification is for some reason undesirable, it can still be disabled by means of the verification callback function passed to `mbedtls_x509_crt_verify()` (see the documentation of this function for more information). + Remove MD2, MD4, RC4, Blowfish and XTEA algorithms -- @@ -612,6 +632,7 @@ This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. They are already niche or obsolete and most of them are weak or broken. For those reasons possible users should consider switching to modern and safe alternatives to be found in literature. + Remove MBEDTLS_SSL_DTLS_BADMAC_LIMIT option ------------------------------------------- @@ -623,6 +644,7 @@ users who didn't need that feature to avoid paying the cost in code size, by disabling it. This option is no longer present, but its functionality is now always enabled. + Deprecated functions were removed from AES ------------------------------------------ @@ -697,6 +719,7 @@ Deprecated net.h file was removed The file `include/mbedtls/net.h` was removed because its only function was to include `mbedtls/net_sockets.h` which now should be included directly. + Remove MBEDTLS_CHECK_PARAMS option ---------------------------------- @@ -730,6 +753,7 @@ Validation of enum-like values is somewhat useful, but not extremely important, because the parameters concerned are usually constants in applications. For more information see issue #4313. + Remove MBEDTLS_SSL_RECORD_CHECKING option and enable its action by default -------------------------------------------------------------------------- @@ -743,6 +767,7 @@ However, the same effect can be achieve by using link-time garbage collection. Users who changed the default setting of the option need to change the config/ build system to remove that change. + Remove the `MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3` option -- @@ -798,8 +823,6 @@ and include the `compat_2.x.h` header file which holds macros with proper renaming or to rename those function in their code according to the list from mentioned header file. - - Signature functions now require the hash length to match the expected value --------------------------------------------------------------------------- @@ -824,6 +847,7 @@ The signature functions in the PK module no longer accept 0 as the `hash_len` pa * `mbedtls_pk_verify_ext` The migration path is to pass the correct value to those functions. + Remove the padding parameters from mbedtls_rsa_init() ----------------------------------------------------- @@ -853,6 +877,7 @@ To use PKCS#1 v1.5 padding, instead of ```C mbedtls_rsa_init(ctx); ``` + Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C ----------------------------------------------------------------- @@ -864,6 +889,7 @@ If you were using custom config file with MBEDTLS_SHA256_C enabled, then you will need to add `#define MBEDTLS_SHA224_C` option your config. Current version of the library does not support enabling MBEDTLS_SHA256_C without MBEDTLS_SHA224_C. + Session Cache API Change ----------------------------------------------------------------- @@ -890,8 +916,9 @@ Since the structure of `mbedtls_ssl_session` is no longer public from 3.0 onwards, portable session cache implementations must not access fields of `mbedtls_ssl_session`. See the corresponding migration guide. Users that find themselves unable to migrate their session cache functionality without -accessing fields of `mbedtls_ssl_session` should describe their usecase +accessing fields of `mbedtls_ssl_session` should describe their use case on the Mbed TLS mailing list. + SHA-512 and SHA-256 output type change -------------------------- @@ -905,6 +932,7 @@ Removal of some SSL error codes ----------------------------------------------------------------- This affects users manually checking for the following error codes: + - `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` - `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` - `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` @@ -915,18 +943,24 @@ This affects users manually checking for the following error codes: Migration paths: - `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` should never be returned from Mbed TLS, and there is no need to check for it. + Users should simply remove manual checks for those codes, and let the Mbed TLS team know if -- contrary to the team's understanding -- there is in fact a situation where one of them was ever returned. + - `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate - is too large to fit into the output buffers. Users should check for - `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially compare the size of their - own certificate against the configured size of the output buffer to understand if - the error is due to an overly large certificate. --`MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN`, `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` and all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`. + is too large to fit into the output buffers. + + Users should check for `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially + compare the size of their own certificate against the configured size of the output buffer to + understand if the error is due to an overly large certificate. + +- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` - Modified semantics of mbedtls_ssl_{get,set}_session() +- all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives. + +Modified semantics of mbedtls_ssl_{get,set}_session() ----------------------------------------------------------------- This affects users who call `mbedtls_ssl_get_session()` or @@ -954,10 +988,10 @@ Migration path: data instead. - Calling `mbedtls_ssl_set_session()` multiple times in Mbed TLS 2.x is not useful since subsequent calls overwrite the effect of previous - calls. Applications achieve equivalent functional behaviour by + calls. Applications achieve equivalent functional behavior by issuing only the very last call to `mbedtls_ssl_set_session()`. - Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option +Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option -- This change affects users who were enabling MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE From 7b0c4dea59381cbd9048db783ff147585d0896b3 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 16:05:28 +0100 Subject: [PATCH 05/51] Fix missing part of sentence Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index ef6df7ae5..bb21dedd8 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -320,7 +320,7 @@ 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 behavior pass TODO +extension included in a CSR as critical. To get the previous behavior pass 0. TLS now favors faster curves over larger curves ----------------------------------------------- From 1cb2331495798254799510a8d0b6ffbd94f6f883 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 16:28:54 +0100 Subject: [PATCH 06/51] Remove line that got into the wrong place Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index bb21dedd8..513aba851 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -75,7 +75,6 @@ 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. -`0`. Strengthen default algorithm selection for X.509 and TLS -------------------------------------------------------- From 949c21b3360398a9af01293c535410e8959386d9 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 18:05:04 +0100 Subject: [PATCH 07/51] Minor updates to migration guide Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 513aba851..737b4eecc 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -11,8 +11,8 @@ two questions: (1) am I affected? (2) if yes, what's my migration path? The changes are detailed below, and include: -- Removal of many insecure / obsolete features -- Tidying up of configuration options (including removing some less useful options) +- Removal of many insecure or obsolete features +- Tidying up of configuration options (including removing some less useful options). - Changing function signatures (e.g., adding return codes or extra parameters); introducing const to arguments. - Removal of functions marked as deprecated in 2.x @@ -258,7 +258,7 @@ 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. +of the 2.x releases — no longer included in 3.0) might help you do that. Remove 3DES ciphersuites -- @@ -289,7 +289,7 @@ 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 +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. @@ -378,8 +378,8 @@ the previous key export API in the following ways: shutting down the TLS connection. For users which do not rely on raw keys and IV, adjusting to the new -callback type should be straightforward - see the example programs -programs/ssl/ssl_client2 and programs/ssl/ssl_server2 for callbacks +callback type should be straightforward — see the example programs +`programs/ssl/ssl_client2` and `programs/ssl/ssl_server2` for callbacks for NSSKeylog, EAP-TLS and DTLS-SRTP. Users which require access to the raw keys used to secure application @@ -418,7 +418,7 @@ This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, `mbedtls_pk_parse_keyfile()`. You now need to pass a properly seeded, cryptographically secure RNG when -calling these functions. It is used for blinding, a counter-measure against +calling these functions. It is used for blinding, a countermeasure against side-channel attacks. The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed @@ -427,8 +427,8 @@ The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed This doesn't affect users of the default configuration; it only affects people who were explicitly setting this option. -This was a trade-off between code size and counter-measures; it is no longer -relevant as the counter-measure is now always on at no cost in code size. +This was a trade-off between code size and countermeasures; it is no longer +relevant as the countermeasure is now always on at no cost in code size. Remove MaximumFragmentLength (MFL) query API ----------------------------------------------------------------- @@ -944,7 +944,7 @@ Migration paths: should never be returned from Mbed TLS, and there is no need to check for it. Users should simply remove manual checks for those codes, and let the Mbed TLS - team know if -- contrary to the team's understanding -- there is in fact a situation + team know if — contrary to the team's understanding — there is in fact a situation where one of them was ever returned. - `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and From a0e8db09acfe85db8e93c2bafd4d9e1d9b7d649c Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 18:05:38 +0100 Subject: [PATCH 08/51] Change headings to level 3 to enable use of sections Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 207 ++++++++++++------------------------ 1 file changed, 69 insertions(+), 138 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 737b4eecc..dd94644b5 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -1,5 +1,4 @@ -Migrating from Mbed TLS 2.x to Mbed TLS 3.0 -=========================================== +# 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 @@ -16,8 +15,7 @@ The changes are detailed below, and include: - Changing function signatures (e.g., adding return codes or extra parameters); introducing const to arguments. - Removal of functions marked as deprecated in 2.x -Introduce a level of indirection and versioning in the config files -------------------------------------------------------------------- +### Introduce a level of indirection and versioning in the config files `config.h` was split into `build_info.h` and `mbedtls_config.h`. @@ -37,8 +35,7 @@ used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same value. The only value supported by Mbed TLS 3.0.0 is `0x03000000`. -Remove support for TLS 1.0, 1.1 and DTLS 1.0 -------------------------------------------- +### Remove support 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. @@ -65,8 +62,7 @@ configuring ciphersuites separately for each version via `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. -Remove support for SSL 3.0 --------------------------- +### Remove support for SSL 3.0 This doesn't affect people using the default configuration as it was already disabled by default. @@ -76,8 +72,7 @@ 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. -Strengthen default algorithm selection for X.509 and TLS --------------------------------------------------------- +### Strengthen default algorithm selection for X.509 and TLS The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. @@ -95,8 +90,7 @@ my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. -Deprecated functions were removed from hashing modules ------------------------------------------------------- +### Deprecated functions were removed from hashing modules Modules: MD5, SHA1, SHA256, SHA512, MD. @@ -110,8 +104,7 @@ Modules: MD5, SHA1, SHA256, SHA512, MD. 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 ---------------------------------------------------------- +### 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 @@ -119,15 +112,13 @@ Deprecated error codes for hardware failures were removed - 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 ---------------------------------------------------------- +### 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 ----------------------------------------------------------------- +### 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. @@ -141,8 +132,7 @@ 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 certs module from the library ----------------------------------------- +### 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. @@ -152,8 +142,7 @@ 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 ------------------------- +### Remove the HAVEGE module This doesn't affect people using the default configuration as it was already disabled by default. @@ -166,8 +155,7 @@ file created securely during device provisioning. See for more information. -Remove support for parsing SSLv2 ClientHello --------------------------------------------- +### Remove support for parsing SSLv2 ClientHello This doesn't affect people using the default configuration as it was already disabled by default. @@ -177,8 +165,7 @@ 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 truncated HMAC ---------------------------------- +### Remove support for truncated HMAC This affects users of truncated HMAC, that is, users who called `mbedtls_ssl_conf_truncated_hmac( ..., MBEDTLS_SSL_TRUNC_HMAC_ENABLED)`, @@ -188,8 +175,7 @@ regardless of whether the standard version was used or compatibility version The recommended migration path for people who want minimal overhead is to use a CCM-8 ciphersuite. -Remove support for TLS record-level compression ------------------------------------------------ +### Remove support for TLS record-level compression This doesn't affect people using the default configuration as it was already disabled by default. @@ -201,8 +187,7 @@ 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 ---------------------------------------------- +### Remove support for TLS RC4-based ciphersuites This does not affect people who used the default `mbedtls_config.h` and the default list of ciphersuites, as RC4-based ciphersuites were already not negotiated in @@ -212,8 +197,7 @@ 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 ----------------------------------------------- +### Remove support for TLS single-DES ciphersuites This doesn't affect people using the default configuration as it was already disabled by default. @@ -222,8 +206,7 @@ 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 ---------------------------------------------------------- +### Remove support for TLS record-level hardware acceleration This doesn't affect people using the default configuration as it was already disabled by default. @@ -232,8 +215,7 @@ 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 ------------------------------------ +### Remove wrapper for libpkcs11-helper This doesn't affect people using the default configuration as it was already disabled by default. @@ -243,16 +225,14 @@ 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` ----------------------------------------------------------- +### 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 -------------------------------------------------------------------- +### 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. @@ -260,8 +240,7 @@ 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. -Remove 3DES ciphersuites --- +### Remove 3DES ciphersuites This change does not affect users using default settings for 3DES in `mbedtls_config.h` because the 3DES ciphersuites were disabled by that. @@ -271,8 +250,7 @@ more standard bodies are recommending against its use in TLS. The migration path here is to chose from the recommended in literature alternatives. -CCM interface changes: impact for alternative implementations -------------------------------------------------------------- +### 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: @@ -281,8 +259,7 @@ 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. -Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations ----------------------------------------------------------------------------- +### 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. @@ -297,8 +274,7 @@ 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. -Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options --- +### Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options This change affects users who modified the default `mbedtls_config.h` padding granularity settings, i.e. enabled at least one of the options. @@ -312,8 +288,7 @@ code maintenance. The new single option `MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY` can be used for both DTLS-CID and TLS 1.3. -Change the API to allow adding critical extensions to CSRs ------------------------------------------------------------------- +### Change the API to allow adding critical extensions to CSRs This affects applications that call the `mbedtls_x509write_csr_set_extension` function. @@ -321,15 +296,13 @@ 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 behavior pass 0. -TLS now favors faster curves over larger curves ------------------------------------------------ +### TLS now favors faster curves over larger curves The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves. If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection. -GCM interface changes: impact for alternative implementations -------------------------------------------------------------- +### GCM interface changes: impact for alternative implementations The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: @@ -339,8 +312,7 @@ The GCM multipart interface has changed as described in [“GCM multipart interf * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. * `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. -GCM multipart interface: application changes --------------------------------------------- +### GCM multipart interface: application changes The GCM module now supports arbitrary chunked input in the multipart interface. This changes the interface for applications using the GCM module directly for multipart operations. @@ -352,8 +324,7 @@ Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `ps * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. * `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. -SSL key export interface change -------------------------------- +### SSL key export interface change This affects users of the SSL key export APIs: ``` @@ -389,8 +360,7 @@ on the wire. Such users are also encouraged to reach out to the Mbed TLS team on the mailing list, to let the team know about their use case. -The RNG parameter is now mandatory for all functions that accept one --------------------------------------------------------------------- +### The RNG parameter is now mandatory for all functions that accept one This change affects all users who called a function accepting a `f_rng` parameter with `NULL` as the value of this argument; this is no longer @@ -410,8 +380,7 @@ Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` configuration options) may have their own internal and are free to ignore the `f_rng` argument but must allow users to pass one anyway. -Some functions gained an RNG parameter --------------------------------------- +### Some functions gained an RNG parameter This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, `mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and @@ -421,8 +390,7 @@ You now need to pass a properly seeded, cryptographically secure RNG when calling these functions. It is used for blinding, a countermeasure against side-channel attacks. -The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed ------------------------------------------------------------------- +### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed This doesn't affect users of the default configuration; it only affects people who were explicitly setting this option. @@ -430,8 +398,7 @@ who were explicitly setting this option. This was a trade-off between code size and countermeasures; it is no longer relevant as the countermeasure is now always on at no cost in code size. -Remove MaximumFragmentLength (MFL) query API ------------------------------------------------------------------ +### Remove MaximumFragmentLength (MFL) query API This affects users which use the MFL query APIs `mbedtls_ssl_get_{input,output}_max_frag_len()` to @@ -442,8 +409,7 @@ Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` instead, which also provides such upper bounds but takes more factors than just the MFL configuration into account. -Change MBEDTLS_ECP_FIXED_POINT_OPTIM behavior ------------------------------------------------------- +### Change MBEDTLS_ECP_FIXED_POINT_OPTIM behavior The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increase code size and it does not increase peak RAM usage anymore. @@ -453,8 +419,7 @@ 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. -Replaced MBEDTLS_SHA512_NO_SHA384 with MBEDTLS_SHA384_C ------------------------------------------------------- +### Replaced MBEDTLS_SHA512_NO_SHA384 with MBEDTLS_SHA384_C This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is @@ -466,8 +431,7 @@ If you were using a config file with MBEDTLS_SHA512_C and without MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add `#define MBEDTLS_SHA384_C` to your config file. -Move part of timing module out of the library --- +### Move part of timing module out of the library The change affects users who use any of the following functions: `mbedtls_timing_self_test()`, `mbedtls_hardclock_poll()`, @@ -476,8 +440,7 @@ The change affects users who use any of the following functions: If you were relying on these functions, you'll now need to change to using your platform's corresponding functions directly. -Extra parameter for the output buffer size ------------------------------------------- +### Extra parameter for the output buffer size The following functions now take an extra parameter indicating the size of the output buffer: @@ -486,8 +449,7 @@ The following functions now take an extra parameter indicating the size of the o The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. -Relaxed semantics for PSK configuration ------------------------------------------------------------------ +### Relaxed semantics for PSK configuration This affects users which call the PSK configuration APIs `mbedtlsl_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()` @@ -505,8 +467,7 @@ remove all but the last call, so that only one call to _either_ `mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()` remains. -Remove the configuration to enable weak ciphersuites in SSL / TLS ------------------------------------------------------------------ +### Remove the configuration to enable weak ciphersuites in SSL / TLS This does not affect users who use the default `mbedtls_config.h`, as this option was already off by default. @@ -518,8 +479,7 @@ and if your peer doesn't support any, encourage them to upgrade their software. If you were using a ciphersuite without encryption, you just have to enable MBEDTLS_CIPHER_NULL_CIPHER now. -Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option -------------------------------------------------------------- +### Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to set the maximum length of incoming and outgoing plaintext fragments, @@ -529,8 +489,7 @@ This option is replaced by the more fine-grained options `MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set the maximum incoming and outgoing plaintext fragment lengths, respectively. -Remove the option to build the library without any entropy sources ------------------------------------------------------------------- +### Remove the `MBEDTLS_TEST_NULL_ENTROPY` configuration option This does not affect users who use the default `mbedtls_config.h`, as this option was already off by default. @@ -541,8 +500,7 @@ and make sure your device is provisioned with a strong random seed. Alternatively, for testing purposes only, you can create and register a fake entropy function. -Remove the mode parameter from RSA functions --------------------------------------------- +### Remove the mode parameter from RSA functions This affects all users who use the RSA encryption, decryption, sign and verify APIs. @@ -555,15 +513,13 @@ the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were callin RSA operations with the wrong mode, which rarely makes sense from a security perspective, this is no longer supported. -Remove the RNG parameter from RSA verify functions --------------------------------------------------- +### Remove the RNG parameter from RSA verify functions RSA verification functions also no longer take random generator arguments (this was only needed when using a private key). This affects all applications using the RSA verify functions. -Remove the SSL API mbedtls_ssl_get_session_pointer() ------------------------------------------------------------------ +### Remove the SSL API mbedtls_ssl_get_session_pointer() This affects two classes of users: @@ -586,8 +542,7 @@ Migration paths: calls to `mbedtls_ssl_get_session()` as demonstrated in the example program `programs/ssl/ssl_client2.c`. -Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION --------------------------------------------------------------------------- +### Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION This change does not affect users of the default configuration; it only affects users who enable this option. @@ -604,8 +559,7 @@ equivalent to `mbedtls_x509_crt_parse_der()`, and/or unsupported certificate extension and additionally the "certificate policies" extension if it contains any unsupported certificate policies. -Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` -------------------------------------------------------------------- +### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` This change affects users who have chosen the configuration options to disable the library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509 @@ -623,8 +577,7 @@ verification is for some reason undesirable, it can still be disabled by means of the verification callback function passed to `mbedtls_x509_crt_verify()` (see the documentation of this function for more information). -Remove MD2, MD4, RC4, Blowfish and XTEA algorithms --- +### Remove MD2, MD4, RC4, Blowfish and XTEA algorithms This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. @@ -632,8 +585,7 @@ They are already niche or obsolete and most of them are weak or broken. For those reasons possible users should consider switching to modern and safe alternatives to be found in literature. -Remove MBEDTLS_SSL_DTLS_BADMAC_LIMIT option -------------------------------------------- +### Remove MBEDTLS_SSL_DTLS_BADMAC_LIMIT option This change does not affect users who used the default `mbedtls_config.h`, as the option MBEDTLS_SSL_DTLS_BADMAC_LIMIT was already on by default. @@ -644,8 +596,7 @@ disabling it. This option is no longer present, but its functionality is now always enabled. -Deprecated functions were removed from AES ------------------------------------------- +### Deprecated functions were removed from AES The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were removed. @@ -658,15 +609,13 @@ If you're providing an alternative implementation using replacing the removed functions with `mbedtls_internal_aes_encrypt()` and `mbedtls_internal_aes_decrypt()` respectively. -Deprecated functions were removed from bignum ---------------------------------------------- +### Deprecated functions were removed from bignum The function `mbedtls_mpi_is_prime()` was removed. Please use `mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the number of Miller-Rabin rounds. -Deprecated functions were removed from cipher ---------------------------------------------- +### Deprecated functions were removed from cipher The functions `mbedtls_cipher_auth_encrypt()` and `mbedtls_cipher_auth_decrypt()` were removed. They were superseded by @@ -674,23 +623,20 @@ The functions `mbedtls_cipher_auth_encrypt()` and respectively which additionally support key wrapping algorithms such as NIST_KW. -Deprecated functions were removed from DRBGs --------------------------------------------- +### Deprecated functions were removed from DRBGs The functions `mbedtls_ctr_drbg_update()` and `mbedtls_hmac_drbg_update()` were removed. They were superseded by `mbedtls_ctr_drbg_update_ret()` and `mbedtls_hmac_drbg_update_ret()` respectively. -Deprecated functions were removed from ECDSA --------------------------------------------- +### Deprecated functions were removed from ECDSA The functions `mbedtls_ecdsa_write_signature_det()` and `mbedtls_ecdsa_sign_det()` were removed. They were superseded by `mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` respectively. -Deprecated functions were removed from SSL ------------------------------------------- +### Deprecated functions were removed from SSL The function `mbedtls_ssl_conf_dh_param()` was removed. Please use `mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead. @@ -700,8 +646,7 @@ The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use `mbedtls_ssl_get_max_in_record_payload()` instead. -Deprecated hex-encoded primes were removed from DHM ---------------------------------------------------- +### Deprecated hex-encoded primes were removed from DHM The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`, `MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`, @@ -713,14 +658,12 @@ removed from the library. Please use parameters from RFC3526 (still in the library, only in binary form) or RFC 7919 (also available in the library) or other trusted sources instead. -Deprecated net.h file was removed ---------------------------------- +### Deprecated net.h file was removed The file `include/mbedtls/net.h` was removed because its only function was to include `mbedtls/net_sockets.h` which now should be included directly. -Remove MBEDTLS_CHECK_PARAMS option ----------------------------------- +### Remove MBEDTLS_CHECK_PARAMS option This change does not affect users who use the default configuration; it only affects users who enabled that option. @@ -753,8 +696,7 @@ because the parameters concerned are usually constants in applications. For more information see issue #4313. -Remove MBEDTLS_SSL_RECORD_CHECKING option and enable its action by default --------------------------------------------------------------------------- +### Remove MBEDTLS_SSL_RECORD_CHECKING option and enable its action by default This change does not affect users who use the default mbedtls_config.h, as the option MBEDTLS_SSL_RECORD_CHECKING was already on by default. @@ -767,8 +709,7 @@ However, the same effect can be achieve by using link-time garbage collection. Users who changed the default setting of the option need to change the config/ build system to remove that change. -Remove the `MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3` option --- +### 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 @@ -782,8 +723,7 @@ configuration. If you are working with the pre-V3 certificates you need to switch to the current ones. -Rename mbedtls_*_ret() cryptography functions whose deprecated variants have been removed ------------------ +### Rename mbedtls_*_ret() cryptography functions whose deprecated variants have been removed This change affects users who were using the `mbedtls_*_ret()` cryptography functions. @@ -822,8 +762,7 @@ and include the `compat_2.x.h` header file which holds macros with proper renaming or to rename those function in their code according to the list from mentioned header file. -Signature functions now require the hash length to match the expected value ---------------------------------------------------------------------------- +### Signature functions now require the hash length to match the expected value This affects users of the PK API as well as users of the low-level API in the RSA module. Users of the PSA API or of the ECDSA module are unaffected. @@ -847,8 +786,7 @@ The signature functions in the PK module no longer accept 0 as the `hash_len` pa The migration path is to pass the correct value to those functions. -Remove the padding parameters from mbedtls_rsa_init() ------------------------------------------------------ +### Remove the padding parameters from mbedtls_rsa_init() This affects all users who use the RSA encryption, decryption, sign and verify APIs. @@ -877,8 +815,7 @@ To use PKCS#1 v1.5 padding, instead of mbedtls_rsa_init(ctx); ``` -Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C ------------------------------------------------------------------ +### Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are @@ -889,8 +826,7 @@ you will need to add `#define MBEDTLS_SHA224_C` option your config. Current version of the library does not support enabling MBEDTLS_SHA256_C without MBEDTLS_SHA224_C. -Session Cache API Change ------------------------------------------------------------------ +### Session Cache API Change This affects users who use `mbedtls_ssl_conf_session_cache()` to configure a custom session cache implementation different @@ -918,8 +854,7 @@ find themselves unable to migrate their session cache functionality without accessing fields of `mbedtls_ssl_session` should describe their use case on the Mbed TLS mailing list. -SHA-512 and SHA-256 output type change --------------------------- +### SHA-512 and SHA-256 output type change The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. @@ -927,8 +862,7 @@ This makes no difference to a vast majority of applications. If your code takes Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. -Removal of some SSL error codes ------------------------------------------------------------------ +### Removal of some SSL error codes This affects users manually checking for the following error codes: @@ -959,8 +893,7 @@ Migration paths: - all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives. -Modified semantics of mbedtls_ssl_{get,set}_session() ------------------------------------------------------------------ +### Modified semantics of mbedtls_ssl_{get,set}_session() This affects users who call `mbedtls_ssl_get_session()` or `mbedtls_ssl_set_session()` multiple times on the same SSL context @@ -990,8 +923,7 @@ Migration path: calls. Applications achieve equivalent functional behavior by issuing only the very last call to `mbedtls_ssl_set_session()`. -Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option - -- +### Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option This change affects users who were enabling MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE option in the `mbedtls_config.h` @@ -1005,8 +937,7 @@ e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE has the same effect as enabling the removed option. The default state is to use the server order of suites. -Some function parameters were made const ----------------------------------------- +### 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. From d267ec361d413bed20628949ca32ba933fef64b2 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 21:31:58 +0100 Subject: [PATCH 09/51] Add formatting codes to level 3 headings Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index dd94644b5..3911141ae 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -409,7 +409,7 @@ Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` instead, which also provides such upper bounds but takes more factors than just the MFL configuration into account. -### Change MBEDTLS_ECP_FIXED_POINT_OPTIM behavior +### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increase code size and it does not increase peak RAM usage anymore. @@ -419,7 +419,7 @@ 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. -### Replaced MBEDTLS_SHA512_NO_SHA384 with MBEDTLS_SHA384_C +### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C` This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is @@ -519,7 +519,7 @@ RSA verification functions also no longer take random generator arguments (this was only needed when using a private key). This affects all applications using the RSA verify functions. -### Remove the SSL API mbedtls_ssl_get_session_pointer() +### Remove the SSL API `mbedtls_ssl_get_session_pointer()` This affects two classes of users: @@ -585,7 +585,7 @@ They are already niche or obsolete and most of them are weak or broken. For those reasons possible users should consider switching to modern and safe alternatives to be found in literature. -### Remove MBEDTLS_SSL_DTLS_BADMAC_LIMIT option +### Remove `MBEDTLS_SSL_DTLS_BADMAC_LIMIT` option This change does not affect users who used the default `mbedtls_config.h`, as the option MBEDTLS_SSL_DTLS_BADMAC_LIMIT was already on by default. @@ -663,7 +663,7 @@ other trusted sources instead. The file `include/mbedtls/net.h` was removed because its only function was to include `mbedtls/net_sockets.h` which now should be included directly. -### Remove MBEDTLS_CHECK_PARAMS option +### Remove `MBEDTLS_CHECK_PARAMS` option This change does not affect users who use the default configuration; it only affects users who enabled that option. @@ -696,7 +696,7 @@ because the parameters concerned are usually constants in applications. For more information see issue #4313. -### Remove MBEDTLS_SSL_RECORD_CHECKING option and enable its action by default +### Remove `MBEDTLS_SSL_RECORD_CHECKING` option and enable its action by default This change does not affect users who use the default mbedtls_config.h, as the option MBEDTLS_SSL_RECORD_CHECKING was already on by default. @@ -815,7 +815,7 @@ To use PKCS#1 v1.5 padding, instead of mbedtls_rsa_init(ctx); ``` -### Separated MBEDTLS_SHA224_C and MBEDTLS_SHA256_C +### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C` This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are @@ -893,7 +893,7 @@ Migration paths: - all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives. -### Modified semantics of mbedtls_ssl_{get,set}_session() +### Modified semantics of `mbedtls_ssl_{get,set}_session()` This affects users who call `mbedtls_ssl_get_session()` or `mbedtls_ssl_set_session()` multiple times on the same SSL context @@ -923,7 +923,7 @@ Migration path: calls. Applications achieve equivalent functional behavior by issuing only the very last call to `mbedtls_ssl_set_session()`. -### Turn MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE configuration option into a runtime option +### Turn `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE` configuration option into a runtime option This change affects users who were enabling MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE option in the `mbedtls_config.h` From 36bb5ff6e3b0fba1a685eab2774ec8ac1b821599 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 21:39:55 +0100 Subject: [PATCH 10/51] minor updates Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 3911141ae..b0903e3da 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -411,7 +411,7 @@ than just the MFL configuration into account. ### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior -The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increase code size and it does +The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases 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` From d8a1017abfa6f806c8b41ad7213e55140b88b8cf Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 21:45:24 +0100 Subject: [PATCH 11/51] add section headings Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index b0903e3da..bbb6d8ed5 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -15,6 +15,20 @@ The changes are detailed below, and include: - Changing function signatures (e.g., adding return codes or extra parameters); introducing const to arguments. - Removal of functions marked as deprecated in 2.x +## Low-level crypto + +## High-level crypto + +## PSA + +## The ALT interface + +## X.509 + +## SSL + +## Tooling + ### Introduce a level of indirection and versioning in the config files `config.h` was split into `build_info.h` and `mbedtls_config.h`. From 30dc603958f7756ab7bce6507c3ad463d9aabdce Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 22:20:58 +0100 Subject: [PATCH 12/51] Reorder sections Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 1333 ++++++++++++++++++----------------- 1 file changed, 676 insertions(+), 657 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index bbb6d8ed5..7f866aa96 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -15,17 +15,7 @@ The changes are detailed below, and include: - Changing function signatures (e.g., adding return codes or extra parameters); introducing const to arguments. - Removal of functions marked as deprecated in 2.x -## Low-level crypto -## High-level crypto - -## PSA - -## The ALT interface - -## X.509 - -## SSL ## Tooling @@ -49,380 +39,6 @@ used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same value. The only value supported by Mbed TLS 3.0.0 is `0x03000000`. -### Remove support 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. - -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 negotiation 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. - -### 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. - -### Strengthen default algorithm selection for X.509 and TLS - -The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. - -Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. - -The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. - -The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. - -If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: -``` -mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; -my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); -``` - -If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. - -### Deprecated functions were removed from hashing modules - -Modules: MD5, SHA1, SHA256, SHA512, MD. - -- The functions `mbedtls_xxx_starts_ret()`, `mbedtls_xxx_update_ret()`, - `mbedtls_xxx_finish_ret()` and `mbedtls_xxx_ret()` were renamed to replace - the corresponding functions without `_ret` appended. Please call the name without `_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_internal_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 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 truncated HMAC - -This affects users of truncated HMAC, that is, users who called -`mbedtls_ssl_conf_truncated_hmac( ..., MBEDTLS_SSL_TRUNC_HMAC_ENABLED)`, -regardless of whether the standard version was used or compatibility version -(`MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT`). - -The recommended migration path for people who want minimal overhead is to use a -CCM-8 ciphersuite. - -### 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 `mbedtls_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. - -### Remove 3DES ciphersuites - -This change does not affect users using default settings for 3DES in `mbedtls_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 recommended in literature alternatives. - -### 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. - -### 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. - -### Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options - -This change affects users who modified the default `mbedtls_config.h` padding granularity -settings, i.e. enabled at least one of the options. - -The `mbedtls_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. - -### 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 behavior pass 0. - -### TLS now favors faster curves over larger curves - -The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves. - -If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection. - -### GCM interface changes: impact for alternative implementations - -The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: - -* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. -* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: - * Always return the partial output immediately, even if it does not consist of a whole number of blocks. - * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. -* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. - -### GCM multipart interface: application changes - -The GCM module now supports arbitrary chunked input in the multipart interface. -This changes the interface for applications using the GCM module directly for multipart operations. -Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. - -* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data. -* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case: - * As long as the input remains block-aligned, the output length is exactly the input length, as before. - * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. -* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. - -### SSL key export interface change - -This affects users of the SSL key export APIs: -``` - mbedtls_ssl_conf_export_keys_cb() - mbedtls_ssl_conf_export_keys_ext_cb() -``` - -Those APIs have been removed and replaced by the new API -`mbedtls_ssl_set_export_keys_cb()`. This API differs from -the previous key export API in the following ways: - -- It is no longer bound to an SSL configuration, but to an - SSL context. This allows users to more easily identify the - connection an exported key belongs to. -- It no longer exports raw keys and IV. -- A secret type parameter has been added to identify which key - is being exported. For TLS 1.2, only the master secret is - exported, but upcoming TLS 1.3 support will add other kinds of keys. -- The callback now specifies a void return type, rather than - returning an error code. It is the responsibility of the application - to handle failures in the key export callback, for example by - shutting down the TLS connection. - -For users which do not rely on raw keys and IV, adjusting to the new -callback type should be straightforward — see the example programs -`programs/ssl/ssl_client2` and `programs/ssl/ssl_server2` for callbacks -for NSSKeylog, EAP-TLS and DTLS-SRTP. - -Users which require access to the raw keys used to secure application -traffic may derive those by hand based on the master secret and the -handshake transcript hashes which can be obtained from the raw data -on the wire. Such users are also encouraged to reach out to the -Mbed TLS team on the mailing list, to let the team know about their -use case. - -### The RNG parameter is now mandatory for all functions that accept one - -This change affects all users who called a function accepting a `f_rng` -parameter with `NULL` as the value of this argument; this is no longer -supported. - -The changed functions are: the X.509 CRT and CSR writing functions; the PK and -RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM -and ECDH that compute the shared secret; the scalar multiplication functions in -ECP. - -You now need to pass a properly seeded, cryptographically secure RNG to all -functions that accept a `f_rng` parameter. It is of course still possible to -pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a -context. - -Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` -configuration options) may have their own internal and are free to ignore the -`f_rng` argument but must allow users to pass one anyway. - -### Some functions gained an RNG parameter - -This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, -`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and -`mbedtls_pk_parse_keyfile()`. - -You now need to pass a properly seeded, cryptographically secure RNG when -calling these functions. It is used for blinding, a countermeasure against -side-channel attacks. - -### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed - -This doesn't affect users of the default configuration; it only affects people -who were explicitly setting this option. - -This was a trade-off between code size and countermeasures; it is no longer -relevant as the countermeasure is now always on at no cost in code size. - -### Remove MaximumFragmentLength (MFL) query API - -This affects users which use the MFL query APIs -`mbedtls_ssl_get_{input,output}_max_frag_len()` to -infer upper bounds on the plaintext size of incoming and -outgoing record. - -Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` -instead, which also provides such upper bounds but takes more factors -than just the MFL configuration into account. - ### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases code size and it does @@ -433,18 +49,6 @@ 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. -### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C` - -This does not affect users who use the default `mbedtls_config.h`. -MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is -enabled by default. - -If you were using a config file with both MBEDTLS_SHA512_C and -MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384. -If you were using a config file with MBEDTLS_SHA512_C and without -MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add -`#define MBEDTLS_SHA384_C` to your config file. - ### Move part of timing module out of the library The change affects users who use any of the following functions: @@ -454,224 +58,6 @@ The change affects users who use any of the following functions: If you were relying on these functions, you'll now need to change to using your platform's corresponding functions directly. -### Extra parameter for the output buffer size - -The following functions now take an extra parameter indicating the size of the output buffer: - -* `mbedtls_ecdsa_write_signature()`, `mbedtls_ecdsa_write_signature_restartable()` -* `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()` - -The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. - -### 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. - -### Remove the configuration to enable weak ciphersuites in SSL / TLS - -This does not affect users who use the default `mbedtls_config.h`, as this option was -already off by default. - -If you were using a weak cipher, 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. - -If you were using a ciphersuite without encryption, you just have to -enable MBEDTLS_CIPHER_NULL_CIPHER now. - -### Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option - -This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to -set the maximum length of incoming and outgoing plaintext fragments, -which can save memory by reducing the size of the TLS I/O buffers. - -This option is replaced by the more fine-grained options -`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set -the maximum incoming and outgoing plaintext fragment lengths, respectively. - -### Remove the `MBEDTLS_TEST_NULL_ENTROPY` configuration option - -This does not affect users who use the default `mbedtls_config.h`, as this option was -already off by default. - -If you were using the `MBEDTLS_TEST_NULL_ENTROPY` option and your platform -doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED` -and make sure your device is provisioned with a strong random seed. -Alternatively, for testing purposes only, you can create and register a fake -entropy function. - -### Remove the mode parameter from RSA functions - -This affects all users who use the RSA encryption, decryption, sign and -verify APIs. - -The RSA module no longer supports private-key operations with the public key or -vice versa. As a consequence, RSA operation functions no longer have a mode -parameter. If you were calling RSA operations with the normal mode (public key -for verification or encryption, private key for signature or decryption), remove -the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling -RSA operations with the wrong mode, which rarely makes sense from a security -perspective, this is no longer supported. - -### Remove the RNG parameter from RSA verify functions - -RSA verification functions also no longer take random generator arguments (this -was only needed when using a private key). This affects all applications using -the RSA verify functions. - -### Remove the SSL API `mbedtls_ssl_get_session_pointer()` - -This affects two classes of users: - -1. Users who manually inspect parts of the current session through - direct structure field access. - -2. Users of session resumption who query the current session - via `mbedtls_ssl_get_session_pointer()` prior to saving or exporting - it via `mbedtls_ssl_session_copy()` or `mbedtls_ssl_session_save()`, - respectively. - -Migration paths: - -1. Mbed TLS 3.0 does not offer a migration path for the use case 1: Like many - other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no - longer part of the public API in Mbed TLS 3.0, and direct structure field - access is no longer supported. Please see the corresponding migration guide. - -2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by - calls to `mbedtls_ssl_get_session()` as demonstrated in the example - program `programs/ssl/ssl_client2.c`. - -### Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION - -This change does not affect users of the default configuration; it only affects -users who enable this option. - -The X.509 standard says that implementations must reject critical extensions that -they don't recognize, and this is what Mbed TLS does by default. This option -allowed to continue parsing those certificates but didn't provide a convenient -way to handle those extensions. - -The migration path from that option is to use the -`mbedtls_x509_crt_parse_der_with_ext_cb()` function which is functionally -equivalent to `mbedtls_x509_crt_parse_der()`, and/or -`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every -unsupported certificate extension and additionally the "certificate policies" -extension if it contains any unsupported certificate policies. - -### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` - -This change affects users who have chosen the configuration options to disable the -library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509 -certificates. - -The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE` -configuration options are removed and the X509 code now behaves as if they were -always enabled. It is consequently not possible anymore to disable at compile -time the verification of the `keyUsage` and `extendedKeyUsage` fields of X509 -certificates. - -The verification of the `keyUsage` and `extendedKeyUsage` fields is important, -disabling it can cause security issues and it is thus not recommended. If the -verification is for some reason undesirable, it can still be disabled by means -of the verification callback function passed to `mbedtls_x509_crt_verify()` (see -the documentation of this function for more information). - -### Remove MD2, MD4, RC4, Blowfish and XTEA algorithms - -This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. - -They are already niche or obsolete and most of them are weak or broken. For -those reasons possible users should consider switching to modern and safe -alternatives to be found in literature. - -### Remove `MBEDTLS_SSL_DTLS_BADMAC_LIMIT` option - -This change does not affect users who used the default `mbedtls_config.h`, as the option -MBEDTLS_SSL_DTLS_BADMAC_LIMIT was already on by default. - -This option was a trade-off between functionality and code size: it allowed -users who didn't need that feature to avoid paying the cost in code size, by -disabling it. - -This option is no longer present, but its functionality is now always enabled. - -### Deprecated functions were removed from AES - -The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were -removed. - -If you're simply using the AES module, you should be calling the higher-level -functions `mbedtls_aes_crypt_xxx()`. - -If you're providing an alternative implementation using -`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be -replacing the removed functions with `mbedtls_internal_aes_encrypt()` and -`mbedtls_internal_aes_decrypt()` respectively. - -### Deprecated functions were removed from bignum - -The function `mbedtls_mpi_is_prime()` was removed. Please use -`mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the -number of Miller-Rabin rounds. - -### Deprecated functions were removed from cipher - -The functions `mbedtls_cipher_auth_encrypt()` and -`mbedtls_cipher_auth_decrypt()` were removed. They were superseded by -`mbedtls_cipher_auth_encrypt_ext()` and `mbedtls_cipher_auth_decrypt_ext()` -respectively which additionally support key wrapping algorithms such as -NIST_KW. - -### Deprecated functions were removed from DRBGs - -The functions `mbedtls_ctr_drbg_update()` and `mbedtls_hmac_drbg_update()` -were removed. They were superseded by `mbedtls_ctr_drbg_update_ret()` and -`mbedtls_hmac_drbg_update_ret()` respectively. - -### Deprecated functions were removed from ECDSA - -The functions `mbedtls_ecdsa_write_signature_det()` and -`mbedtls_ecdsa_sign_det()` were removed. They were superseded by -`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` -respectively. - -### Deprecated functions were removed from SSL - -The function `mbedtls_ssl_conf_dh_param()` was removed. Please use -`mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead. - -The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use -`mbedtls_ssl_get_max_out_record_payload()` and -`mbedtls_ssl_get_max_in_record_payload()` -instead. - -### Deprecated hex-encoded primes were removed from DHM - -The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`, -`MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`, -`MBEDTLS_DHM_RFC3526_MODP_3072_P`, `MBEDTLS_DHM_RFC3526_MODP_3072_G`, -`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were -removed. The primes from RFC 5114 are deprecated because their derivation is not -documented and therefore their usage constitutes a security risk; they are fully -removed from the library. Please use parameters from RFC3526 (still in the -library, only in binary form) or RFC 7919 (also available in the library) or -other trusted sources instead. - ### Deprecated net.h file was removed The file `include/mbedtls/net.h` was removed because its only function was to @@ -710,32 +96,263 @@ because the parameters concerned are usually constants in applications. For more information see issue #4313. -### Remove `MBEDTLS_SSL_RECORD_CHECKING` option and enable its action by default +### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C` -This change does not affect users who use the default mbedtls_config.h, as the -option MBEDTLS_SSL_RECORD_CHECKING was already on by default. +This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C +was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are +enabled. -This option was added only to control compilation of one function, -mbedtls_ssl_check_record(), which is only useful in some specific cases, so it -was made optional to allow users who don't need it to save some code space. -However, the same effect can be achieve by using link-time garbage collection. +If you were using custom config file with MBEDTLS_SHA256_C enabled, then +you will need to add `#define MBEDTLS_SHA224_C` option your config. +Current version of the library does not support enabling MBEDTLS_SHA256_C +without MBEDTLS_SHA224_C. -Users who changed the default setting of the option need to change the config/ -build system to remove that change. +### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C` -### Remove the `MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3` option +This does not affect users who use the default `mbedtls_config.h`. +MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is +enabled by default. -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. +If you were using a config file with both MBEDTLS_SHA512_C and +MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384. +If you were using a config file with MBEDTLS_SHA512_C and without +MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add +`#define MBEDTLS_SHA384_C` to your config file. -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. +### Remove the `MBEDTLS_TEST_NULL_ENTROPY` configuration option -If you are working with the pre-V3 certificates you need to switch to the -current ones. +This does not affect users who use the default `mbedtls_config.h`, as this option was +already off by default. + +If you were using the `MBEDTLS_TEST_NULL_ENTROPY` option and your platform +doesn't have any entropy source, you should use `MBEDTLS_ENTROPY_NV_SEED` +and make sure your device is provisioned with a strong random seed. +Alternatively, for testing purposes only, you can create and register a fake +entropy function. + +### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed + +This doesn't affect users of the default configuration; it only affects people +who were explicitly setting this option. + +This was a trade-off between code size and countermeasures; it is no longer +relevant as the countermeasure is now always on at no cost in code size. + +### 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. + + + +## Low-level crypto + +### The RNG parameter is now mandatory for all functions that accept one + +This change affects all users who called a function accepting a `f_rng` +parameter with `NULL` as the value of this argument; this is no longer +supported. + +The changed functions are: the X.509 CRT and CSR writing functions; the PK and +RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM +and ECDH that compute the shared secret; the scalar multiplication functions in +ECP. + +You now need to pass a properly seeded, cryptographically secure RNG to all +functions that accept a `f_rng` parameter. It is of course still possible to +pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a +context. + +Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` +configuration options) may have their own internal and are free to ignore the +`f_rng` argument but must allow users to pass one anyway. + +### Some functions gained an RNG parameter + +This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, +`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and +`mbedtls_pk_parse_keyfile()`. + +You now need to pass a properly seeded, cryptographically secure RNG when +calling these functions. It is used for blinding, a countermeasure against +side-channel attacks. + +### Deprecated functions were removed from bignum + +The function `mbedtls_mpi_is_prime()` was removed. Please use +`mbedtls_mpi_is_prime_ext()` instead which additionally allows specifying the +number of Miller-Rabin rounds. + +### Deprecated functions were removed from DRBGs + +The functions `mbedtls_ctr_drbg_update()` and `mbedtls_hmac_drbg_update()` +were removed. They were superseded by `mbedtls_ctr_drbg_update_ret()` and +`mbedtls_hmac_drbg_update_ret()` respectively. + +### Deprecated hex-encoded primes were removed from DHM + +The macros `MBEDTLS_DHM_RFC5114_MODP_2048_P`, `MBEDTLS_DHM_RFC5114_MODP_2048_G`, +`MBEDTLS_DHM_RFC3526_MODP_2048_P`, `MBEDTLS_DHM_RFC3526_MODP_2048_G`, +`MBEDTLS_DHM_RFC3526_MODP_3072_P`, `MBEDTLS_DHM_RFC3526_MODP_3072_G`, +`MBEDTLS_DHM_RFC3526_MODP_4096_P `and `MBEDTLS_DHM_RFC3526_MODP_4096_G` were +removed. The primes from RFC 5114 are deprecated because their derivation is not +documented and therefore their usage constitutes a security risk; they are fully +removed from the library. Please use parameters from RFC3526 (still in the +library, only in binary form) or RFC 7919 (also available in the library) or +other trusted sources instead. + +## High-level crypto + +### 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. + +### Deprecated functions were removed from hashing modules + +Modules: MD5, SHA1, SHA256, SHA512, MD. + +- The functions `mbedtls_xxx_starts_ret()`, `mbedtls_xxx_update_ret()`, + `mbedtls_xxx_finish_ret()` and `mbedtls_xxx_ret()` were renamed to replace + the corresponding functions without `_ret` appended. Please call the name without `_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. + +### Remove 3DES ciphersuites + +This change does not affect users using default settings for 3DES in `mbedtls_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 recommended in literature alternatives. + +### 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. + +### 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. + +### GCM multipart interface: application changes + +The GCM module now supports arbitrary chunked input in the multipart interface. +This changes the interface for applications using the GCM module directly for multipart operations. +Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. + +* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data. +* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case: + * As long as the input remains block-aligned, the output length is exactly the input length, as before. + * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. +* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. + +### GCM interface changes: impact for alternative implementations + +The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: + +* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. +* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: + * Always return the partial output immediately, even if it does not consist of a whole number of blocks. + * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. +* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. + +### Remove the mode parameter from RSA functions + +This affects all users who use the RSA encryption, decryption, sign and +verify APIs. + +The RSA module no longer supports private-key operations with the public key or +vice versa. As a consequence, RSA operation functions no longer have a mode +parameter. If you were calling RSA operations with the normal mode (public key +for verification or encryption, private key for signature or decryption), remove +the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling +RSA operations with the wrong mode, which rarely makes sense from a security +perspective, this is no longer supported. + +### Remove the RNG parameter from RSA verify functions + +RSA verification functions also no longer take random generator arguments (this +was only needed when using a private key). This affects all applications using +the RSA verify functions. + +### Remove MD2, MD4, RC4, Blowfish and XTEA algorithms + +This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. + +They are already niche or obsolete and most of them are weak or broken. For +those reasons possible users should consider switching to modern and safe +alternatives to be found in literature. + +### Deprecated functions were removed from AES + +The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were +removed. + +If you're simply using the AES module, you should be calling the higher-level +functions `mbedtls_aes_crypt_xxx()`. + +If you're providing an alternative implementation using +`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be +replacing the removed functions with `mbedtls_internal_aes_encrypt()` and +`mbedtls_internal_aes_decrypt()` respectively. + +### Deprecated functions were removed from cipher + +The functions `mbedtls_cipher_auth_encrypt()` and +`mbedtls_cipher_auth_decrypt()` were removed. They were superseded by +`mbedtls_cipher_auth_encrypt_ext()` and `mbedtls_cipher_auth_decrypt_ext()` +respectively which additionally support key wrapping algorithms such as +NIST_KW. + +### Deprecated functions were removed from ECDSA + +The functions `mbedtls_ecdsa_write_signature_det()` and +`mbedtls_ecdsa_sign_det()` were removed. They were superseded by +`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` +respectively. + +### Extra parameter for the output buffer size + +The following functions now take an extra parameter indicating the size of the output buffer: + +* `mbedtls_ecdsa_write_signature()`, `mbedtls_ecdsa_write_signature_restartable()` +* `mbedtls_pk_sign()`, `mbedtls_pk_sign_restartable()` + +The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. ### Rename mbedtls_*_ret() cryptography functions whose deprecated variants have been removed @@ -811,34 +428,452 @@ you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call to mbedtls_rsa_init(), to call mbedtls_rsa_set_padding() to set it. To choose the padding type when initializing a context, instead of + ```C mbedtls_rsa_init(ctx, padding, hash_id); ``` + , use + ```C mbedtls_rsa_init(ctx); mbedtls_rsa_set_padding(ctx, padding, hash_id); ``` To use PKCS#1 v1.5 padding, instead of + ```C mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, ); ``` + , just use + ```C mbedtls_rsa_init(ctx); ``` -### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C` +### SHA-512 and SHA-256 output type change -This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C -was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are -enabled. +The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. -If you were using custom config file with MBEDTLS_SHA256_C enabled, then -you will need to add `#define MBEDTLS_SHA224_C` option your config. -Current version of the library does not support enabling MBEDTLS_SHA256_C -without MBEDTLS_SHA224_C. +This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. + +Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. + +### 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. + + + +## PSA + +### 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. + + + +## The ALT interface + +### 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_internal_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. + +### 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. + + + +## X.509 + +### Strengthen default algorithm selection for X.509 and TLS + +The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. + +Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. + +The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. + +The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. + +If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: +``` +mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; +my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); +``` + +If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. + +### 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. + +### 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 behavior pass 0. + +### Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION + +This change does not affect users of the default configuration; it only affects +users who enable this option. + +The X.509 standard says that implementations must reject critical extensions that +they don't recognize, and this is what Mbed TLS does by default. This option +allowed to continue parsing those certificates but didn't provide a convenient +way to handle those extensions. + +The migration path from that option is to use the +`mbedtls_x509_crt_parse_der_with_ext_cb()` function which is functionally +equivalent to `mbedtls_x509_crt_parse_der()`, and/or +`mbedtls_x509_crt_parse_der_nocopy()` but it calls the callback with every +unsupported certificate extension and additionally the "certificate policies" +extension if it contains any unsupported certificate policies. + +### Remove `MBEDTLS_X509_CHECK_*_KEY_USAGE` options from `mbedtls_config.h` + +This change affects users who have chosen the configuration options to disable the +library's verification of the `keyUsage` and `extendedKeyUsage` fields of x509 +certificates. + +The `MBEDTLS_X509_CHECK_KEY_USAGE` and `MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE` +configuration options are removed and the X509 code now behaves as if they were +always enabled. It is consequently not possible anymore to disable at compile +time the verification of the `keyUsage` and `extendedKeyUsage` fields of X509 +certificates. + +The verification of the `keyUsage` and `extendedKeyUsage` fields is important, +disabling it can cause security issues and it is thus not recommended. If the +verification is for some reason undesirable, it can still be disabled by means +of the verification callback function passed to `mbedtls_x509_crt_verify()` (see +the documentation of this function for more information). + +### 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. + + + +## SSL + +### Remove support 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. + +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 negotiation 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. + +### 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 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 truncated HMAC + +This affects users of truncated HMAC, that is, users who called +`mbedtls_ssl_conf_truncated_hmac( ..., MBEDTLS_SSL_TRUNC_HMAC_ENABLED)`, +regardless of whether the standard version was used or compatibility version +(`MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT`). + +The recommended migration path for people who want minimal overhead is to use a +CCM-8 ciphersuite. + +### 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 `mbedtls_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 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. + +### Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options + +This change affects users who modified the default `mbedtls_config.h` padding granularity +settings, i.e. enabled at least one of the options. + +The `mbedtls_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. + +### TLS now favors faster curves over larger curves + +The default preference order for curves in TLS now favors resource usage (performance and memory consumption) over size. The exact order is unspecified and may change, but generally you can expect 256-bit curves to be preferred over larger curves. + +If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuring a TLS connection. + +### SSL key export interface change + +This affects users of the SSL key export APIs: +``` + mbedtls_ssl_conf_export_keys_cb() + mbedtls_ssl_conf_export_keys_ext_cb() +``` + +Those APIs have been removed and replaced by the new API +`mbedtls_ssl_set_export_keys_cb()`. This API differs from +the previous key export API in the following ways: + +- It is no longer bound to an SSL configuration, but to an + SSL context. This allows users to more easily identify the + connection an exported key belongs to. +- It no longer exports raw keys and IV. +- A secret type parameter has been added to identify which key + is being exported. For TLS 1.2, only the master secret is + exported, but upcoming TLS 1.3 support will add other kinds of keys. +- The callback now specifies a void return type, rather than + returning an error code. It is the responsibility of the application + to handle failures in the key export callback, for example by + shutting down the TLS connection. + +For users which do not rely on raw keys and IV, adjusting to the new +callback type should be straightforward — see the example programs +`programs/ssl/ssl_client2` and `programs/ssl/ssl_server2` for callbacks +for NSSKeylog, EAP-TLS and DTLS-SRTP. + +Users which require access to the raw keys used to secure application +traffic may derive those by hand based on the master secret and the +handshake transcript hashes which can be obtained from the raw data +on the wire. Such users are also encouraged to reach out to the +Mbed TLS team on the mailing list, to let the team know about their +use case. + +### Remove MaximumFragmentLength (MFL) query API + +This affects users which use the MFL query APIs +`mbedtls_ssl_get_{input,output}_max_frag_len()` to +infer upper bounds on the plaintext size of incoming and +outgoing record. + +Users should switch to `mbedtls_ssl_get_max_{in,out}_record_payload()` +instead, which also provides such upper bounds but takes more factors +than just the MFL configuration into account. + +### 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. + +### Remove the configuration to enable weak ciphersuites in SSL / TLS + +This does not affect users who use the default `mbedtls_config.h`, as this option was +already off by default. + +If you were using a weak cipher, 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. + +If you were using a ciphersuite without encryption, you just have to +enable MBEDTLS_CIPHER_NULL_CIPHER now. + +### Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option + +This affects users who use the `MBEDTLS_SSL_MAX_CONTENT_LEN` option to +set the maximum length of incoming and outgoing plaintext fragments, +which can save memory by reducing the size of the TLS I/O buffers. + +This option is replaced by the more fine-grained options +`MBEDTLS_SSL_IN_CONTENT_LEN` and `MBEDTLS_SSL_OUT_CONTENT_LEN` that set +the maximum incoming and outgoing plaintext fragment lengths, respectively. + +### Remove the SSL API `mbedtls_ssl_get_session_pointer()` + +This affects two classes of users: + +1. Users who manually inspect parts of the current session through + direct structure field access. + +2. Users of session resumption who query the current session + via `mbedtls_ssl_get_session_pointer()` prior to saving or exporting + it via `mbedtls_ssl_session_copy()` or `mbedtls_ssl_session_save()`, + respectively. + +Migration paths: + +1. Mbed TLS 3.0 does not offer a migration path for the use case 1: Like many + other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no + longer part of the public API in Mbed TLS 3.0, and direct structure field + access is no longer supported. Please see the corresponding migration guide. + +2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by + calls to `mbedtls_ssl_get_session()` as demonstrated in the example + program `programs/ssl/ssl_client2.c`. + +### Remove `MBEDTLS_SSL_DTLS_BADMAC_LIMIT` option + +This change does not affect users who used the default `mbedtls_config.h`, as the option +MBEDTLS_SSL_DTLS_BADMAC_LIMIT was already on by default. + +This option was a trade-off between functionality and code size: it allowed +users who didn't need that feature to avoid paying the cost in code size, by +disabling it. + +This option is no longer present, but its functionality is now always enabled. + +### Deprecated functions were removed from SSL + +The function `mbedtls_ssl_conf_dh_param()` was removed. Please use +`mbedtls_ssl_conf_dh_param_bin()` or `mbedtls_ssl_conf_dh_param_ctx()` instead. + +The function `mbedtls_ssl_get_max_frag_len()` was removed. Please use +`mbedtls_ssl_get_max_out_record_payload()` and +`mbedtls_ssl_get_max_in_record_payload()` +instead. + +### Remove `MBEDTLS_SSL_RECORD_CHECKING` option and enable its action by default + +This change does not affect users who use the default mbedtls_config.h, as the +option MBEDTLS_SSL_RECORD_CHECKING was already on by default. + +This option was added only to control compilation of one function, +mbedtls_ssl_check_record(), which is only useful in some specific cases, so it +was made optional to allow users who don't need it to save some code space. +However, the same effect can be achieve by using link-time garbage collection. + +Users who changed the default setting of the option need to change the config/ +build system to remove that change. ### Session Cache API Change @@ -868,14 +903,6 @@ find themselves unable to migrate their session cache functionality without accessing fields of `mbedtls_ssl_session` should describe their use case on the Mbed TLS mailing list. -### SHA-512 and SHA-256 output type change - -The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. - -This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. - -Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. - ### Removal of some SSL error codes This affects users manually checking for the following error codes: @@ -951,11 +978,3 @@ e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE has the same effect as enabling the removed option. The default state is to use the server order of suites. -### 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. From 4a5d3c08c66210119a0ac482d2b0cd8eb8d293d8 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Tue, 29 Jun 2021 22:29:03 +0100 Subject: [PATCH 13/51] Fix typo Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 7f866aa96..49b870a17 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -103,7 +103,7 @@ was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are enabled. If you were using custom config file with MBEDTLS_SHA256_C enabled, then -you will need to add `#define MBEDTLS_SHA224_C` option your config. +you will need to add `#define MBEDTLS_SHA224_C` option to your config. Current version of the library does not support enabling MBEDTLS_SHA256_C without MBEDTLS_SHA224_C. From 7078973b7b1d62f0d7766697207993186b45d565 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 09:18:55 +0100 Subject: [PATCH 14/51] Improve wording Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 49b870a17..2b20b5ce6 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -12,9 +12,8 @@ The changes are detailed below, and include: - Removal of many insecure or obsolete features - Tidying up of configuration options (including removing some less useful options). -- Changing function signatures (e.g., adding return codes or extra parameters); introducing const to arguments. -- Removal of functions marked as deprecated in 2.x - +- Changing function signatures, e.g. adding return codes, adding extra parameters, or making some arguments const. +- Removal of functions previously marked as deprecated. ## Tooling From b491b2b051cde5357dd1e9d4caf0c1faf1aa573d Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 09:46:07 +0100 Subject: [PATCH 15/51] Add SSL error code updates from #4724 Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 2b20b5ce6..4ac677633 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -902,7 +902,7 @@ find themselves unable to migrate their session cache functionality without accessing fields of `mbedtls_ssl_session` should describe their use case on the Mbed TLS mailing list. -### Removal of some SSL error codes +### Changes in the SSL error code space This affects users manually checking for the following error codes: @@ -916,11 +916,11 @@ This affects users manually checking for the following error codes: Migration paths: - `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` should never be returned from Mbed TLS, and there is no need to check for it. - + Users should simply remove manual checks for those codes, and let the Mbed TLS team know if — contrary to the team's understanding — there is in fact a situation where one of them was ever returned. - + - `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate is too large to fit into the output buffers. @@ -928,10 +928,29 @@ Migration paths: Users should check for `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially compare the size of their own certificate against the configured size of the output buffer to understand if the error is due to an overly large certificate. - -- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` -- all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives. +- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been + replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`. + +- All codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives. + + Users should check for the newly introduced generic error codes + + * `MBEDTLS_ERR_SSL_DECODE_ERROR` + * `MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER`, + * `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` + * `MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION` + * `MBEDTLS_ERR_SSL_BAD_CERTIFICATE` + * `MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME` + * `MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION` + * `MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL` + + and the pre-existing generic error codes + + * `MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE` + * `MBEDTLS_ERR_SSL_INTERNAL_ERROR` + + instead. ### Modified semantics of `mbedtls_ssl_{get,set}_session()` From e4ec84631b1e6b1553802ac49498203964e31b7d Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 09:52:40 +0100 Subject: [PATCH 16/51] Fix typos Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 4ac677633..352c48458 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -242,7 +242,7 @@ 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 recommended in literature alternatives. +The migration path here is to choose from the recommended in literature alternatives. ### Deprecated error codes for hardware failures were removed @@ -389,7 +389,7 @@ original names of those functions. The renamed functions are: To migrate to the this change the user can keep the `*_ret` names in their code and include the `compat_2.x.h` header file which holds macros with proper -renaming or to rename those function in their code according to the list from +renaming or to rename those functions in their code according to the list from mentioned header file. ### Signature functions now require the hash length to match the expected value @@ -432,7 +432,7 @@ To choose the padding type when initializing a context, instead of mbedtls_rsa_init(ctx, padding, hash_id); ``` -, use +use ```C mbedtls_rsa_init(ctx); @@ -445,7 +445,7 @@ To use PKCS#1 v1.5 padding, instead of mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, ); ``` -, just use +just use ```C mbedtls_rsa_init(ctx); @@ -869,7 +869,7 @@ option MBEDTLS_SSL_RECORD_CHECKING was already on by default. This option was added only to control compilation of one function, mbedtls_ssl_check_record(), which is only useful in some specific cases, so it was made optional to allow users who don't need it to save some code space. -However, the same effect can be achieve by using link-time garbage collection. +However, the same effect can be achieved by using link-time garbage collection. Users who changed the default setting of the option need to change the config/ build system to remove that change. From a481052407a89c924a29e147346283994f780d39 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 29 Jun 2021 22:45:26 +0200 Subject: [PATCH 17/51] Add migration guide and changelog entry for MBEDTLS_PRIVATE We forgot those in #4511. Signed-off-by: Gilles Peskine --- ChangeLog.d/private-fields.txt | 5 +++++ docs/3.0-migration-guide.md | 13 +++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 ChangeLog.d/private-fields.txt diff --git a/ChangeLog.d/private-fields.txt b/ChangeLog.d/private-fields.txt new file mode 100644 index 000000000..10b9a594a --- /dev/null +++ b/ChangeLog.d/private-fields.txt @@ -0,0 +1,5 @@ +API changes + * Direct access to fields of structures declared in public headers is no + longer supported except for fields that are documented public. Use accessor + functions instead. For more information, see the migration guide entry + "Most structure fields are now private". diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 352c48458..0ffd91954 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -150,6 +150,19 @@ file created securely during device provisioning. See for more information. +### Most structure fields are now private + +Direct access to fields of structures (`struct` types) declared in public headers is no longer supported. In Mbed TLS 3, the layout of structures is not considered part of the stable API, and minor versions (3.1, 3.2, etc.) may add, remove, rename, reorder or change the type of structure fields. + +There is a small number of exceptions where some fields are guaranteed to remain stable throughout the lifetime of Mbed TLS 3.x. These fields are explicitly documented as public. Please note that even if all the fields of a structure are public, future versions may add new fields. Also, as before, some public fields should be considered read-only, since modifying them may make the struture inconsistent; check the documentation in each case. + +Attempting to access a private field directly will result in a compilation error. + +If you were accessing structure fields directly, and these fields are not documented as public, you need to change your code. If an accessor (getter/setter) function exists, use that. Direct accessor functions are usually called `mbedtls__{get,set}_` or `mbedtls___{get,set}_`. Accessor functions that change the format may use different verbs, for example `read`/`write` for functions that import/export data from/to a text or byte string. + +If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/ARMmbed/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them the first minor release(s) (3.1, etc.). + +As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. ## Low-level crypto From a5a3cce49b73a925daf25fec0368fa768a02360b Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 11:06:58 +0100 Subject: [PATCH 18/51] Add link between sections Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 0ffd91954..1546f4d1a 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -847,7 +847,7 @@ Migration paths: 1. Mbed TLS 3.0 does not offer a migration path for the use case 1: Like many other Mbed TLS structures, the structure of `mbedtls_ssl_session` is no longer part of the public API in Mbed TLS 3.0, and direct structure field - access is no longer supported. Please see the corresponding migration guide. + access is no longer supported. Please see the [section on private structure fields](#most-structure-fields-are-now-private) for more details. 2. Users should replace calls to `mbedtls_ssl_get_session_pointer()` by calls to `mbedtls_ssl_get_session()` as demonstrated in the example From a54c16805e1c592edb0585a77f6d86215ab212ad Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 11:11:07 +0100 Subject: [PATCH 19/51] Improve wording relating to removal of MBEDTLS_ERR_SSL_BAD_HS_XXX Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 1546f4d1a..65b868a8d 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -945,7 +945,7 @@ Migration paths: - `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`. -- All codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives. +- All codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives, which give more information about the type of error raised. Users should check for the newly introduced generic error codes From d462ca1f72c30ea490fca4ed2c0857db0c9d15ad Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 11:26:08 +0100 Subject: [PATCH 20/51] Fix typos Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 65b868a8d..0e156b429 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -154,13 +154,13 @@ information. Direct access to fields of structures (`struct` types) declared in public headers is no longer supported. In Mbed TLS 3, the layout of structures is not considered part of the stable API, and minor versions (3.1, 3.2, etc.) may add, remove, rename, reorder or change the type of structure fields. -There is a small number of exceptions where some fields are guaranteed to remain stable throughout the lifetime of Mbed TLS 3.x. These fields are explicitly documented as public. Please note that even if all the fields of a structure are public, future versions may add new fields. Also, as before, some public fields should be considered read-only, since modifying them may make the struture inconsistent; check the documentation in each case. +There is a small number of exceptions where some fields are guaranteed to remain stable throughout the lifetime of Mbed TLS 3.x. These fields are explicitly documented as public. Please note that even if all the fields of a structure are public, future versions may add new fields. Also, as before, some public fields should be considered read-only, since modifying them may make the structure inconsistent; check the documentation in each case. Attempting to access a private field directly will result in a compilation error. If you were accessing structure fields directly, and these fields are not documented as public, you need to change your code. If an accessor (getter/setter) function exists, use that. Direct accessor functions are usually called `mbedtls__{get,set}_` or `mbedtls___{get,set}_`. Accessor functions that change the format may use different verbs, for example `read`/`write` for functions that import/export data from/to a text or byte string. -If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/ARMmbed/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them the first minor release(s) (3.1, etc.). +If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/ARMmbed/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.). As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. From 4ea5643046c2e53ee0cf512a699dd09f5fe4b6b8 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 14:16:22 +0100 Subject: [PATCH 21/51] Change some section names Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 0e156b429..b9200ac09 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -16,7 +16,7 @@ The changes are detailed below, and include: - Removal of functions previously marked as deprecated. -## Tooling +## General changes ### Introduce a level of indirection and versioning in the config files @@ -493,7 +493,7 @@ names provided by the 1.0 specification instead. -## The ALT interface +## Changes that only affect alternative implementations ### Internal / alt-focused headers were moved to a private location From a3758208ae818233446c89132835ba74a2028c25 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 14:17:03 +0100 Subject: [PATCH 22/51] Move sub-sections to more appropriate places Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 151 ++++++++++++++++++------------------ 1 file changed, 75 insertions(+), 76 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index b9200ac09..182a3bca6 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -38,16 +38,6 @@ used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same value. The only value supported by Mbed TLS 3.0.0 is `0x03000000`. -### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior - -The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases 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. - ### Move part of timing module out of the library The change affects users who use any of the following functions: @@ -95,29 +85,6 @@ because the parameters concerned are usually constants in applications. For more information see issue #4313. -### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C` - -This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C -was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are -enabled. - -If you were using custom config file with MBEDTLS_SHA256_C enabled, then -you will need to add `#define MBEDTLS_SHA224_C` option to your config. -Current version of the library does not support enabling MBEDTLS_SHA256_C -without MBEDTLS_SHA224_C. - -### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C` - -This does not affect users who use the default `mbedtls_config.h`. -MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is -enabled by default. - -If you were using a config file with both MBEDTLS_SHA512_C and -MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384. -If you were using a config file with MBEDTLS_SHA512_C and without -MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add -`#define MBEDTLS_SHA384_C` to your config file. - ### Remove the `MBEDTLS_TEST_NULL_ENTROPY` configuration option This does not affect users who use the default `mbedtls_config.h`, as this option was @@ -129,14 +96,6 @@ and make sure your device is provisioned with a strong random seed. Alternatively, for testing purposes only, you can create and register a fake entropy function. -### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed - -This doesn't affect users of the default configuration; it only affects people -who were explicitly setting this option. - -This was a trade-off between code size and countermeasures; it is no longer -relevant as the countermeasure is now always on at no cost in code size. - ### Remove the HAVEGE module This doesn't affect people using the default configuration as it was already @@ -164,6 +123,14 @@ If no accessor function exists, please open an [enhancement request against Mbed As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. +### 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. + ## Low-level crypto @@ -221,6 +188,56 @@ removed from the library. Please use parameters from RFC3526 (still in the library, only in binary form) or RFC 7919 (also available in the library) or other trusted sources instead. +### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior + +The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases 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. + +### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C` + +This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C +was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are +enabled. + +If you were using custom config file with MBEDTLS_SHA256_C enabled, then +you will need to add `#define MBEDTLS_SHA224_C` option to your config. +Current version of the library does not support enabling MBEDTLS_SHA256_C +without MBEDTLS_SHA224_C. + +### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C` + +This does not affect users who use the default `mbedtls_config.h`. +MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is +enabled by default. + +If you were using a config file with both MBEDTLS_SHA512_C and +MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384. +If you were using a config file with MBEDTLS_SHA512_C and without +MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add +`#define MBEDTLS_SHA384_C` to your config file. + +### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed + +This doesn't affect users of the default configuration; it only affects people +who were explicitly setting this option. + +This was a trade-off between code size and countermeasures; it is no longer +relevant as the countermeasure is now always on at no cost in code size. + +### SHA-512 and SHA-256 output type change + +The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. + +This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. + +Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. + + ## High-level crypto ### Remove wrapper for libpkcs11-helper @@ -464,14 +481,6 @@ just use mbedtls_rsa_init(ctx); ``` -### SHA-512 and SHA-256 output type change - -The output parameter of `mbedtls_sha256_finish_ret()`, `mbedtls_sha256_ret()`, `mbedtls_sha512_finish_ret()`, `mbedtls_sha512_ret()` now has a pointer type rather than array type. This makes no difference in terms of C semantics, but removes spurious warnings in some compilers when outputting a SHA-384 hash into a 48-byte buffer or a SHA-224 hash into a 28-byte buffer. - -This makes no difference to a vast majority of applications. If your code takes a pointer to one of these functions, you may need to change the type of the pointer. - -Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. - ### Some function parameters were made const Various functions in the PK and ASN.1 modules had a `const` qualifier added to @@ -482,7 +491,6 @@ those functions. In this case, you'll need to update the type of your pointers in order to match the new signature. - ## PSA ### Deprecated names for PSA constants and types were removed @@ -522,24 +530,6 @@ implement those additional five API functions. ## X.509 -### Strengthen default algorithm selection for X.509 and TLS - -The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. - -Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. - -The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. - -The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. - -If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: -``` -mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; -my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); -``` - -If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. - ### Remove the certs module from the library This should not affect production use of the library, as the certificates and @@ -715,14 +705,6 @@ 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. - ### Combine the `MBEDTLS_SSL_CID_PADDING_GRANULARITY` and `MBEDTLS_SSL_TLS1_3_PADDING_GRANULARITY` options This change affects users who modified the default `mbedtls_config.h` padding granularity @@ -1009,3 +991,20 @@ e.g.: `mbedtls_ssl_conf_preference_order(ssl_config, MBEDTLS_SSL_SRV_CIPHERSUITE has the same effect as enabling the removed option. The default state is to use the server order of suites. +### Strengthen default algorithm selection for X.509 and TLS + +The default X.509 verification profile (`mbedtls_x509_crt_profile_default`) and the default curve and hash selection in TLS have changed. They are now aligned, except that the X.509 profile only lists curves that support signature verification. + +Hashes and curves weaker than 255 bits (security strength less than 128 bits) are no longer accepted by default. The following hashes have been removed: SHA-1 (formerly only accepted for key exchanges but not for certificate signatures), SHA-224 (weaker hashes were already not accepted). The following curves have been removed: secp192r1, secp224r1, secp192k1, secp224k1. + +The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE` are no longer available. + +The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. + +If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: +``` +mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; +my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); +``` + +If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. From b1c6b4a7a54521561259b0142962e1e1f9b5a363 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 14:17:21 +0100 Subject: [PATCH 23/51] Add cross-reference Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 182a3bca6..4d3ae57b1 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -597,7 +597,9 @@ configuration. If you are working with the pre-V3 certificates you need to switch to the current ones. +### Strengthen default algorithm selection for X.509 +This is described in the section (Strengthen default algorithm selection for X.509 and TLS)[strengthen-default-algorithm-selection-for-x.509-and-tls]. ## SSL From c936bbb15a5fb5a50b6e17360fa9dd41270406f7 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 14:19:30 +0100 Subject: [PATCH 24/51] Make blank lines before sections consistent Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 4d3ae57b1..04eb37f64 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -500,7 +500,6 @@ API were removed from version 1.0 of specification. Please switch to the new names provided by the 1.0 specification instead. - ## Changes that only affect alternative implementations ### Internal / alt-focused headers were moved to a private location @@ -527,7 +526,6 @@ Alternative implementations of CCM (`MBEDTLS_CCM_ALT`) have now to implement those additional five API functions. - ## X.509 ### Remove the certs module from the library @@ -601,6 +599,7 @@ current ones. This is described in the section (Strengthen default algorithm selection for X.509 and TLS)[strengthen-default-algorithm-selection-for-x.509-and-tls]. + ## SSL ### Remove support for TLS 1.0, 1.1 and DTLS 1.0 From 92170cc3e1c725944da553a591c753ef02121e15 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 14:23:27 +0100 Subject: [PATCH 25/51] Add general cross-reference for low/high-level crypto Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 04eb37f64..35652c3f3 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -134,6 +134,9 @@ of the 2.x releases — no longer included in 3.0) might help you do that. ## Low-level crypto +Please also refer to the section [High-level crypto](#high-level-crypto) for +changes that could sit in either cateogry. + ### The RNG parameter is now mandatory for all functions that accept one This change affects all users who called a function accepting a `f_rng` @@ -240,6 +243,9 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f ## High-level crypto +Please also refer to the section [Low-level crypto](#low-level-crypto) for +changes that could sit in either cateogry. + ### Remove wrapper for libpkcs11-helper This doesn't affect people using the default configuration as it was already From 8d91ceb19d67fd144c37c1c1d723c97699bd7357 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 16:56:09 +0100 Subject: [PATCH 26/51] Remove empty 3.0-migration-guide.d This is now captured in 3.0-migration-guide.md Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.d/00README | 27 --------------------------- 1 file changed, 27 deletions(-) delete mode 100644 docs/3.0-migration-guide.d/00README diff --git a/docs/3.0-migration-guide.d/00README b/docs/3.0-migration-guide.d/00README deleted file mode 100644 index a41733e47..000000000 --- a/docs/3.0-migration-guide.d/00README +++ /dev/null @@ -1,27 +0,0 @@ -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. From 26ad6c7ea7f292bec43267562dc147bbbbf701f9 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 17:14:01 +0100 Subject: [PATCH 27/51] Fix typo Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 35652c3f3..081e7bbc7 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -135,7 +135,7 @@ of the 2.x releases — no longer included in 3.0) might help you do that. ## Low-level crypto Please also refer to the section [High-level crypto](#high-level-crypto) for -changes that could sit in either cateogry. +changes that could sit in either category. ### The RNG parameter is now mandatory for all functions that accept one @@ -244,7 +244,7 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f ## High-level crypto Please also refer to the section [Low-level crypto](#low-level-crypto) for -changes that could sit in either cateogry. +changes that could sit in either category. ### Remove wrapper for libpkcs11-helper From 6753a775b84eb4dccfd95dc37235b349e1063042 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 17:15:28 +0100 Subject: [PATCH 28/51] Fix grammatical error Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 081e7bbc7..8aa9f2faf 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -549,7 +549,7 @@ and it may change in incompatible ways at any time. 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 +The API is changed to include the parameter `critical` which enables marking an extension included in a CSR as critical. To get the previous behavior pass 0. ### Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION From 2e1e623d33ba8d8e0bdb03d51141b8998671999d Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 17:45:22 +0100 Subject: [PATCH 29/51] Correct hyperlink syntax Co-authored-by: Tomasz Rodziewicz <40165497+TRodziewicz@users.noreply.github.com> Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 8aa9f2faf..03b589097 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -603,7 +603,7 @@ current ones. ### Strengthen default algorithm selection for X.509 -This is described in the section (Strengthen default algorithm selection for X.509 and TLS)[strengthen-default-algorithm-selection-for-x.509-and-tls]. +This is described in the section [Strengthen default algorithm selection for X.509 and TLS](strengthen-default-algorithm-selection-for-x.509-and-tls). ## SSL From 9d3417845c8bd06b4b5078dbf2533529e6ebf437 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:35:43 +0100 Subject: [PATCH 30/51] Add backticks where needed Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 72 ++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 03b589097..d66cb7f69 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -389,7 +389,7 @@ The following functions now take an extra parameter indicating the size of the o The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. -### Rename mbedtls_*_ret() cryptography functions whose deprecated variants have been removed +### Rename `mbedtls_*_ret()` cryptography functions whose deprecated variants have been removed This change affects users who were using the `mbedtls_*_ret()` cryptography functions. @@ -398,30 +398,30 @@ Those functions were created based on now-deprecated functions according to a requirement that a function needs to return a value. This change brings back the original names of those functions. The renamed functions are: -| name before this change | after the change | -|------------------------------|--------------------------| -| mbedtls_ctr_drbg_update_ret | mbedtls_ctr_drbg_update | -| mbedtls_hmac_drbg_update_ret | mbedtls_hmac_drbg_update | -| mbedtls_md5_starts_ret | mbedtls_md5_starts | -| mbedtls_md5_update_ret | mbedtls_md5_update | -| mbedtls_md5_finish_ret | mbedtls_md5_finish | -| mbedtls_md5_ret | mbedtls_md5 | -| mbedtls_ripemd160_starts_ret | mbedtls_ripemd160_starts | -| mbedtls_ripemd160_update_ret | mbedtls_ripemd160_update | -| mbedtls_ripemd160_finish_ret | mbedtls_ripemd160_finish | -| mbedtls_ripemd160_ret | mbedtls_ripemd160 | -| mbedtls_sha1_starts_ret | mbedtls_sha1_starts | -| mbedtls_sha1_update_ret | mbedtls_sha1_update | -| mbedtls_sha1_finish_ret | mbedtls_sha1_finish | -| mbedtls_sha1_ret | mbedtls_sha1 | -| mbedtls_sha256_starts_ret | mbedtls_sha256_starts | -| mbedtls_sha256_update_ret | mbedtls_sha256_update | -| mbedtls_sha256_finish_ret | mbedtls_sha256_finish | -| mbedtls_sha256_ret | mbedtls_sha256 | -| mbedtls_sha512_starts_ret | mbedtls_sha512_starts | -| mbedtls_sha512_update_ret | mbedtls_sha512_update | -| mbedtls_sha512_finish_ret | mbedtls_sha512_finish | -| mbedtls_sha512_ret | mbedtls_sha512 | +| name before this change | after the change | +|--------------------------------|----------------------------| +| `mbedtls_ctr_drbg_update_ret` | `mbedtls_ctr_drbg_update` | +| `mbedtls_hmac_drbg_update_ret` | `mbedtls_hmac_drbg_update` | +| `mbedtls_md5_starts_ret` | `mbedtls_md5_starts` | +| `mbedtls_md5_update_ret` | `mbedtls_md5_update` | +| `mbedtls_md5_finish_ret` | `mbedtls_md5_finish` | +| `mbedtls_md5_ret` | `mbedtls_md5` | +| `mbedtls_ripemd160_starts_ret` | `mbedtls_ripemd160_starts` | +| `mbedtls_ripemd160_update_ret` | `mbedtls_ripemd160_update` | +| `mbedtls_ripemd160_finish_ret` | `mbedtls_ripemd160_finish` | +| `mbedtls_ripemd160_ret` | `mbedtls_ripemd160` | +| `mbedtls_sha1_starts_ret` | `mbedtls_sha1_starts` | +| `mbedtls_sha1_update_ret` | `mbedtls_sha1_update` | +| `mbedtls_sha1_finish_ret` | `mbedtls_sha1_finish` | +| `mbedtls_sha1_ret` | `mbedtls_sha1` | +| `mbedtls_sha256_starts_ret` | `mbedtls_sha256_starts` | +| `mbedtls_sha256_update_ret` | `mbedtls_sha256_update` | +| `mbedtls_sha256_finish_ret` | `mbedtls_sha256_finish` | +| `mbedtls_sha256_ret` | `mbedtls_sha256` | +| `mbedtls_sha512_starts_ret` | `mbedtls_sha512_starts` | +| `mbedtls_sha512_update_ret` | `mbedtls_sha512_update` | +| `mbedtls_sha512_finish_ret` | `mbedtls_sha512_finish` | +| `mbedtls_sha512_ret` | `mbedtls_sha512` | To migrate to the this change the user can keep the `*_ret` names in their code and include the `compat_2.x.h` header file which holds macros with proper @@ -452,15 +452,15 @@ The signature functions in the PK module no longer accept 0 as the `hash_len` pa The migration path is to pass the correct value to those functions. -### Remove the padding parameters from mbedtls_rsa_init() +### Remove the padding parameters from `mbedtls_rsa_init()` This affects all users who use the RSA encryption, decryption, sign and verify APIs. -The function mbedtls_rsa_init() no longer supports selecting the PKCS#1 v2.1 +The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1 encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call -to mbedtls_rsa_init(), to call mbedtls_rsa_set_padding() to set it. +to `mbedtls_rsa_init()`, to call `mbedtls_rsa_set_padding()` to set it. To choose the padding type when initializing a context, instead of @@ -526,8 +526,8 @@ and explain your need; we'll consider adding a new API in a future version. 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(). + `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. @@ -807,7 +807,7 @@ 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. If you were using a ciphersuite without encryption, you just have to -enable MBEDTLS_CIPHER_NULL_CIPHER now. +enable `MBEDTLS_CIPHER_NULL_CIPHER` now. ### Remove the `MBEDTLS_SSL_MAX_CONTENT_LEN` configuration option @@ -845,7 +845,7 @@ Migration paths: ### Remove `MBEDTLS_SSL_DTLS_BADMAC_LIMIT` option This change does not affect users who used the default `mbedtls_config.h`, as the option -MBEDTLS_SSL_DTLS_BADMAC_LIMIT was already on by default. +`MBEDTLS_SSL_DTLS_BADMAC_LIMIT` was already on by default. This option was a trade-off between functionality and code size: it allowed users who didn't need that feature to avoid paying the cost in code size, by @@ -865,11 +865,11 @@ instead. ### Remove `MBEDTLS_SSL_RECORD_CHECKING` option and enable its action by default -This change does not affect users who use the default mbedtls_config.h, as the -option MBEDTLS_SSL_RECORD_CHECKING was already on by default. +This change does not affect users who use the default `mbedtls_config.h`, as the +option `MBEDTLS_SSL_RECORD_CHECKING` was already on by default. This option was added only to control compilation of one function, -mbedtls_ssl_check_record(), which is only useful in some specific cases, so it + `mbedtls_ssl_check_record()`, which is only useful in some specific cases, so it was made optional to allow users who don't need it to save some code space. However, the same effect can be achieved by using link-time garbage collection. @@ -986,7 +986,7 @@ Migration path: ### Turn `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE` configuration option into a runtime option -This change affects users who were enabling MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE +This change affects users who were enabling `MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE` option in the `mbedtls_config.h` This option has been removed and a new function with similar functionality has From ce53b3afd6a9241772525a1bf8963a5a0e59543d Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:37:46 +0100 Subject: [PATCH 31/51] Remove reference to removed item Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index d66cb7f69..17fe956a4 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -916,13 +916,6 @@ This affects users manually checking for the following error codes: - `MBEDTLS_ERR_SSL_BAD_HS_XXX` Migration paths: -- `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` - should never be returned from Mbed TLS, and there is no need to check for it. - - Users should simply remove manual checks for those codes, and let the Mbed TLS - team know if — contrary to the team's understanding — there is in fact a situation - where one of them was ever returned. - - `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate is too large to fit into the output buffers. From 28701c63cbb0a74f28b45ba14e72769c7a0751ea Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:38:41 +0100 Subject: [PATCH 32/51] Fix grammatical error Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 17fe956a4..6960bea83 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -278,7 +278,8 @@ 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 choose from the recommended in literature alternatives. +The migration path here is to chose from the alternatives recommended in the +literature, such as AES. ### Deprecated error codes for hardware failures were removed From 7018053460ab9363dd0e545e3d98cceb320d386c Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:40:24 +0100 Subject: [PATCH 33/51] Reorder subsections Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 6960bea83..7f09449a2 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -38,6 +38,20 @@ used by the Mbed TLS release whose `MBEDTLS_VERSION_NUMBER` has the same value. The only value supported by Mbed TLS 3.0.0 is `0x03000000`. +### Most structure fields are now private + +Direct access to fields of structures (`struct` types) declared in public headers is no longer supported. In Mbed TLS 3, the layout of structures is not considered part of the stable API, and minor versions (3.1, 3.2, etc.) may add, remove, rename, reorder or change the type of structure fields. + +There is a small number of exceptions where some fields are guaranteed to remain stable throughout the lifetime of Mbed TLS 3.x. These fields are explicitly documented as public. Please note that even if all the fields of a structure are public, future versions may add new fields. Also, as before, some public fields should be considered read-only, since modifying them may make the structure inconsistent; check the documentation in each case. + +Attempting to access a private field directly will result in a compilation error. + +If you were accessing structure fields directly, and these fields are not documented as public, you need to change your code. If an accessor (getter/setter) function exists, use that. Direct accessor functions are usually called `mbedtls__{get,set}_` or `mbedtls___{get,set}_`. Accessor functions that change the format may use different verbs, for example `read`/`write` for functions that import/export data from/to a text or byte string. + +If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/ARMmbed/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.). + +As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. + ### Move part of timing module out of the library The change affects users who use any of the following functions: @@ -109,20 +123,6 @@ file created securely during device provisioning. See for more information. -### Most structure fields are now private - -Direct access to fields of structures (`struct` types) declared in public headers is no longer supported. In Mbed TLS 3, the layout of structures is not considered part of the stable API, and minor versions (3.1, 3.2, etc.) may add, remove, rename, reorder or change the type of structure fields. - -There is a small number of exceptions where some fields are guaranteed to remain stable throughout the lifetime of Mbed TLS 3.x. These fields are explicitly documented as public. Please note that even if all the fields of a structure are public, future versions may add new fields. Also, as before, some public fields should be considered read-only, since modifying them may make the structure inconsistent; check the documentation in each case. - -Attempting to access a private field directly will result in a compilation error. - -If you were accessing structure fields directly, and these fields are not documented as public, you need to change your code. If an accessor (getter/setter) function exists, use that. Direct accessor functions are usually called `mbedtls__{get,set}_` or `mbedtls___{get,set}_`. Accessor functions that change the format may use different verbs, for example `read`/`write` for functions that import/export data from/to a text or byte string. - -If no accessor function exists, please open an [enhancement request against Mbed TLS](https://github.com/ARMmbed/mbedtls/issues/new?template=feature_request.md) and describe your use case. The Mbed TLS development team is aware that some useful accessor functions are missing in the 3.0 release, and we expect to add them to the first minor release(s) (3.1, etc.). - -As a last resort, you can access the field `foo` of a structure `bar` by writing `bar.MBEDTLS_PRIVATE(foo)`. Note that you do so at your own risk, since such code is likely to break in a future minor version of Mbed TLS. - ### 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 From aa1fba2fedadbd0a455fc0bf8bb15719a6222527 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:41:24 +0100 Subject: [PATCH 34/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 7f09449a2..90d787773 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -246,16 +246,6 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f Please also refer to the section [Low-level crypto](#low-level-crypto) for changes that could sit in either category. -### 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. - ### Deprecated functions were removed from hashing modules Modules: MD5, SHA1, SHA256, SHA512, MD. @@ -606,6 +596,16 @@ current ones. This is described in the section [Strengthen default algorithm selection for X.509 and TLS](strengthen-default-algorithm-selection-for-x.509-and-tls). +### 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. + ## SSL From 2d05e0f440aa97692b2a109a9a774e1f0862a4e4 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:42:34 +0100 Subject: [PATCH 35/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 90d787773..1b24c4160 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -191,6 +191,20 @@ removed from the library. Please use parameters from RFC3526 (still in the library, only in binary form) or RFC 7919 (also available in the library) or other trusted sources instead. +### Deprecated functions were removed from hashing modules + +Modules: MD5, SHA1, SHA256, SHA512, MD. + +- The functions `mbedtls_xxx_starts_ret()`, `mbedtls_xxx_update_ret()`, + `mbedtls_xxx_finish_ret()` and `mbedtls_xxx_ret()` were renamed to replace + the corresponding functions without `_ret` appended. Please call the name without `_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. + ### Change `MBEDTLS_ECP_FIXED_POINT_OPTIM` behavior The option `MBEDTLS_ECP_FIXED_POINT_OPTIM` now increases code size and it does @@ -246,20 +260,6 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f Please also refer to the section [Low-level crypto](#low-level-crypto) for changes that could sit in either category. -### Deprecated functions were removed from hashing modules - -Modules: MD5, SHA1, SHA256, SHA512, MD. - -- The functions `mbedtls_xxx_starts_ret()`, `mbedtls_xxx_update_ret()`, - `mbedtls_xxx_finish_ret()` and `mbedtls_xxx_ret()` were renamed to replace - the corresponding functions without `_ret` appended. Please call the name without `_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. - ### Remove 3DES ciphersuites This change does not affect users using default settings for 3DES in `mbedtls_config.h` From 3f66943bddfc8772948d6094f00fff1fe295ba18 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:43:49 +0100 Subject: [PATCH 36/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 1b24c4160..2e08640d1 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -260,17 +260,6 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f Please also refer to the section [Low-level crypto](#low-level-crypto) for changes that could sit in either category. -### Remove 3DES ciphersuites - -This change does not affect users using default settings for 3DES in `mbedtls_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 alternatives recommended in the -literature, such as AES. - ### Deprecated error codes for hardware failures were removed - The macros `MBEDTLS_ERR_xxx_FEATURE_UNSUPPORTED` from various crypto modules @@ -1009,3 +998,14 @@ my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); ``` If you still need to allow hashes and curves in TLS that have been removed from the default configuration, call `mbedtls_ssl_conf_sig_hashes()` and `mbedtls_ssl_conf_curves()` with the desired lists. + +### Remove 3DES ciphersuites + +This change does not affect users using default settings for 3DES in `mbedtls_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 alternatives recommended in the +literature, such as AES. From 897a95f46c1aa15db24fd8cebff5b136cadb40a1 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:50:57 +0100 Subject: [PATCH 37/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 2e08640d1..09e5bd870 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -254,12 +254,6 @@ This makes no difference to a vast majority of applications. If your code takes Alternative implementations of the SHA256 and SHA512 modules must adjust their functions' prototype accordingly. - -## High-level crypto - -Please also refer to the section [Low-level crypto](#low-level-crypto) for -changes that could sit in either category. - ### Deprecated error codes for hardware failures were removed - The macros `MBEDTLS_ERR_xxx_FEATURE_UNSUPPORTED` from various crypto modules @@ -268,6 +262,12 @@ changes that could sit in either category. - The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead. + +## High-level crypto + +Please also refer to the section [Low-level crypto](#low-level-crypto) for +changes that could sit in either category. + ### Calling `mbedtls_cipher_finish()` is mandatory for all multi-part operations This only affects people who use the cipher module to perform AEAD operations From 68547187f6513efbc57b3b280e921696b7bb5ec6 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:53:09 +0100 Subject: [PATCH 38/51] Move subsections Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 44 ++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 09e5bd870..8a121feb4 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -238,6 +238,28 @@ If you were using a config file with MBEDTLS_SHA512_C and without MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add `#define MBEDTLS_SHA384_C` to your config file. +### GCM multipart interface: application changes + +The GCM module now supports arbitrary chunked input in the multipart interface. +This changes the interface for applications using the GCM module directly for multipart operations. +Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. + +* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data. +* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case: + * As long as the input remains block-aligned, the output length is exactly the input length, as before. + * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. +* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. + +### GCM interface changes: impact for alternative implementations + +The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: + +* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. +* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: + * Always return the partial output immediately, even if it does not consist of a whole number of blocks. + * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. +* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. + ### The configuration option `MBEDTLS_ECP_NO_INTERNAL_RNG` was removed This doesn't affect users of the default configuration; it only affects people @@ -283,28 +305,6 @@ 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. -### GCM multipart interface: application changes - -The GCM module now supports arbitrary chunked input in the multipart interface. -This changes the interface for applications using the GCM module directly for multipart operations. -Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `psa_aead_xxx` interfaces do not require any changes. - -* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). Call the new function `mbedtls_gcm_update_ad()` to pass the associated data. -* `mbedtls_gcm_update()` now takes an extra parameter to indicate the actual output length. In Mbed TLS 2.x, applications had to pass inputs consisting of whole 16-byte blocks except for the last block (this limitation has been lifted). In this case: - * As long as the input remains block-aligned, the output length is exactly the input length, as before. - * If the length of the last input is not a multiple of 16, alternative implementations may return the last partial block in the call to `mbedtls_gcm_finish()` instead of returning it in the last call to `mbedtls_gcm_update()`. -* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block. This is needed for alternative implementations that can only process a whole block at a time. - -### GCM interface changes: impact for alternative implementations - -The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: - -* `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. -* `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: - * Always return the partial output immediately, even if it does not consist of a whole number of blocks. - * Buffer the data for the last partial block, to be returned in the next call to `mbedtls_gcm_update()` or `mbedtls_gcm_finish()`. -* `mbedtls_gcm_finish()` now takes an extra output buffer for the last partial block if needed. - ### Remove the mode parameter from RSA functions This affects all users who use the RSA encryption, decryption, sign and From 507827e75ada6eb2da54fec7ed8eec97430088ec Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:54:35 +0100 Subject: [PATCH 39/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 8a121feb4..0c7be3060 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -284,6 +284,19 @@ Alternative implementations of the SHA256 and SHA512 modules must adjust their f - The macros `MBEDTLS_ERR_xxx_HW_ACCEL_FAILED` from various crypto modules were removed; `MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED` is now used instead. +### Remove the mode parameter from RSA functions + +This affects all users who use the RSA encryption, decryption, sign and +verify APIs. + +The RSA module no longer supports private-key operations with the public key or +vice versa. As a consequence, RSA operation functions no longer have a mode +parameter. If you were calling RSA operations with the normal mode (public key +for verification or encryption, private key for signature or decryption), remove +the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling +RSA operations with the wrong mode, which rarely makes sense from a security +perspective, this is no longer supported. + ## High-level crypto @@ -305,19 +318,6 @@ 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. -### Remove the mode parameter from RSA functions - -This affects all users who use the RSA encryption, decryption, sign and -verify APIs. - -The RSA module no longer supports private-key operations with the public key or -vice versa. As a consequence, RSA operation functions no longer have a mode -parameter. If you were calling RSA operations with the normal mode (public key -for verification or encryption, private key for signature or decryption), remove -the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were calling -RSA operations with the wrong mode, which rarely makes sense from a security -perspective, this is no longer supported. - ### Remove the RNG parameter from RSA verify functions RSA verification functions also no longer take random generator arguments (this From 715966862d36aacacc6b63c43182ed563f536ae6 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:56:20 +0100 Subject: [PATCH 40/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 0c7be3060..0d68f0a2b 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -297,6 +297,19 @@ the `MBEDTLS_MODE_PUBLIC` or `MBEDTLS_MODE_PRIVATE` argument. If you were callin RSA operations with the wrong mode, which rarely makes sense from a security perspective, this is no longer supported. +### Deprecated functions were removed from AES + +The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were +removed. + +If you're simply using the AES module, you should be calling the higher-level +functions `mbedtls_aes_crypt_xxx()`. + +If you're providing an alternative implementation using +`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be +replacing the removed functions with `mbedtls_internal_aes_encrypt()` and +`mbedtls_internal_aes_decrypt()` respectively. + ## High-level crypto @@ -332,19 +345,6 @@ They are already niche or obsolete and most of them are weak or broken. For those reasons possible users should consider switching to modern and safe alternatives to be found in literature. -### Deprecated functions were removed from AES - -The functions `mbedtls_aes_encrypt()` and `mbedtls_aes_decrypt()` were -removed. - -If you're simply using the AES module, you should be calling the higher-level -functions `mbedtls_aes_crypt_xxx()`. - -If you're providing an alternative implementation using -`MBEDTLS_AES_ENCRYPT_ALT` or `MBEDTLS_AES_DECRYPT_ALT`, you should be -replacing the removed functions with `mbedtls_internal_aes_encrypt()` and -`mbedtls_internal_aes_decrypt()` respectively. - ### Deprecated functions were removed from cipher The functions `mbedtls_cipher_auth_encrypt()` and From 8128b69ffe0d11166630e1d0aa9f625aa2b658b9 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:56:33 +0100 Subject: [PATCH 41/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 0d68f0a2b..5a4a2da71 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -310,6 +310,13 @@ If you're providing an alternative implementation using replacing the removed functions with `mbedtls_internal_aes_encrypt()` and `mbedtls_internal_aes_decrypt()` respectively. +### Deprecated functions were removed from ECDSA + +The functions `mbedtls_ecdsa_write_signature_det()` and +`mbedtls_ecdsa_sign_det()` were removed. They were superseded by +`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` +respectively. + ## High-level crypto @@ -353,13 +360,6 @@ The functions `mbedtls_cipher_auth_encrypt()` and respectively which additionally support key wrapping algorithms such as NIST_KW. -### Deprecated functions were removed from ECDSA - -The functions `mbedtls_ecdsa_write_signature_det()` and -`mbedtls_ecdsa_sign_det()` were removed. They were superseded by -`mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` -respectively. - ### Extra parameter for the output buffer size The following functions now take an extra parameter indicating the size of the output buffer: From b4d15b155693b82e190924032ef530648d9c2756 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:57:37 +0100 Subject: [PATCH 42/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 78 ++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 5a4a2da71..b345b9ddd 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -317,6 +317,45 @@ The functions `mbedtls_ecdsa_write_signature_det()` and `mbedtls_ecdsa_write_signature()` and `mbedtls_ecdsa_sign_det_ext()` respectively. +### Rename `mbedtls_*_ret()` cryptography functions whose deprecated variants have been removed + +This change affects users who were using the `mbedtls_*_ret()` cryptography +functions. + +Those functions were created based on now-deprecated functions according to a +requirement that a function needs to return a value. This change brings back the +original names of those functions. The renamed functions are: + +| name before this change | after the change | +|--------------------------------|----------------------------| +| `mbedtls_ctr_drbg_update_ret` | `mbedtls_ctr_drbg_update` | +| `mbedtls_hmac_drbg_update_ret` | `mbedtls_hmac_drbg_update` | +| `mbedtls_md5_starts_ret` | `mbedtls_md5_starts` | +| `mbedtls_md5_update_ret` | `mbedtls_md5_update` | +| `mbedtls_md5_finish_ret` | `mbedtls_md5_finish` | +| `mbedtls_md5_ret` | `mbedtls_md5` | +| `mbedtls_ripemd160_starts_ret` | `mbedtls_ripemd160_starts` | +| `mbedtls_ripemd160_update_ret` | `mbedtls_ripemd160_update` | +| `mbedtls_ripemd160_finish_ret` | `mbedtls_ripemd160_finish` | +| `mbedtls_ripemd160_ret` | `mbedtls_ripemd160` | +| `mbedtls_sha1_starts_ret` | `mbedtls_sha1_starts` | +| `mbedtls_sha1_update_ret` | `mbedtls_sha1_update` | +| `mbedtls_sha1_finish_ret` | `mbedtls_sha1_finish` | +| `mbedtls_sha1_ret` | `mbedtls_sha1` | +| `mbedtls_sha256_starts_ret` | `mbedtls_sha256_starts` | +| `mbedtls_sha256_update_ret` | `mbedtls_sha256_update` | +| `mbedtls_sha256_finish_ret` | `mbedtls_sha256_finish` | +| `mbedtls_sha256_ret` | `mbedtls_sha256` | +| `mbedtls_sha512_starts_ret` | `mbedtls_sha512_starts` | +| `mbedtls_sha512_update_ret` | `mbedtls_sha512_update` | +| `mbedtls_sha512_finish_ret` | `mbedtls_sha512_finish` | +| `mbedtls_sha512_ret` | `mbedtls_sha512` | + +To migrate to the this change the user can keep the `*_ret` names in their code +and include the `compat_2.x.h` header file which holds macros with proper +renaming or to rename those functions in their code according to the list from +mentioned header file. + ## High-level crypto @@ -369,45 +408,6 @@ The following functions now take an extra parameter indicating the size of the o The requirements for the output buffer have not changed, but passing a buffer that is too small now reliably causes the functions to return an error, rather than overflowing the buffer. -### Rename `mbedtls_*_ret()` cryptography functions whose deprecated variants have been removed - -This change affects users who were using the `mbedtls_*_ret()` cryptography -functions. - -Those functions were created based on now-deprecated functions according to a -requirement that a function needs to return a value. This change brings back the -original names of those functions. The renamed functions are: - -| name before this change | after the change | -|--------------------------------|----------------------------| -| `mbedtls_ctr_drbg_update_ret` | `mbedtls_ctr_drbg_update` | -| `mbedtls_hmac_drbg_update_ret` | `mbedtls_hmac_drbg_update` | -| `mbedtls_md5_starts_ret` | `mbedtls_md5_starts` | -| `mbedtls_md5_update_ret` | `mbedtls_md5_update` | -| `mbedtls_md5_finish_ret` | `mbedtls_md5_finish` | -| `mbedtls_md5_ret` | `mbedtls_md5` | -| `mbedtls_ripemd160_starts_ret` | `mbedtls_ripemd160_starts` | -| `mbedtls_ripemd160_update_ret` | `mbedtls_ripemd160_update` | -| `mbedtls_ripemd160_finish_ret` | `mbedtls_ripemd160_finish` | -| `mbedtls_ripemd160_ret` | `mbedtls_ripemd160` | -| `mbedtls_sha1_starts_ret` | `mbedtls_sha1_starts` | -| `mbedtls_sha1_update_ret` | `mbedtls_sha1_update` | -| `mbedtls_sha1_finish_ret` | `mbedtls_sha1_finish` | -| `mbedtls_sha1_ret` | `mbedtls_sha1` | -| `mbedtls_sha256_starts_ret` | `mbedtls_sha256_starts` | -| `mbedtls_sha256_update_ret` | `mbedtls_sha256_update` | -| `mbedtls_sha256_finish_ret` | `mbedtls_sha256_finish` | -| `mbedtls_sha256_ret` | `mbedtls_sha256` | -| `mbedtls_sha512_starts_ret` | `mbedtls_sha512_starts` | -| `mbedtls_sha512_update_ret` | `mbedtls_sha512_update` | -| `mbedtls_sha512_finish_ret` | `mbedtls_sha512_finish` | -| `mbedtls_sha512_ret` | `mbedtls_sha512` | - -To migrate to the this change the user can keep the `*_ret` names in their code -and include the `compat_2.x.h` header file which holds macros with proper -renaming or to rename those functions in their code according to the list from -mentioned header file. - ### Signature functions now require the hash length to match the expected value This affects users of the PK API as well as users of the low-level API in the RSA module. Users of the PSA API or of the ECDSA module are unaffected. From 2b03457ca5ea49d2fc261d810067a381d2110d53 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 18:59:49 +0100 Subject: [PATCH 43/51] Improve wording Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index b345b9ddd..a6b71f643 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -175,9 +175,9 @@ number of Miller-Rabin rounds. ### Deprecated functions were removed from DRBGs -The functions `mbedtls_ctr_drbg_update()` and `mbedtls_hmac_drbg_update()` -were removed. They were superseded by `mbedtls_ctr_drbg_update_ret()` and -`mbedtls_hmac_drbg_update_ret()` respectively. +The functions `mbedtls_ctr_drbg_update_ret()` and `mbedtls_hmac_drbg_update_ret()` +were renamed to replace the corresponding functions without `_ret` appended. Please call +the name without `_ret` appended and check the return value. ### Deprecated hex-encoded primes were removed from DHM From 2482650483e108b46c0e2b9c64a67039c0d31f14 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 19:00:48 +0100 Subject: [PATCH 44/51] Correct hyperlink Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index a6b71f643..e91211a2b 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -252,7 +252,7 @@ Applications using one-shot GCM or using GCM via the `mbedtls_cipher_xxx` or `ps ### GCM interface changes: impact for alternative implementations -The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface:-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: +The GCM multipart interface has changed as described in [“GCM multipart interface: application changes”](#gcm-multipart-interface-application-changes). The consequences for an alternative implementation of GCM (`MBEDTLS_GCM_ALT`) are as follows: * `mbedtls_gcm_starts()` now only sets the mode and the nonce (IV). The new function `mbedtls_gcm_update_ad()` receives the associated data. It may be called multiple times. * `mbedtls_gcm_update()` now allows arbitrary-length inputs, takes an extra parameter to indicate the actual output length. Alternative implementations may choose between two modes: From 7d2ac88f93886271a3b7ed471158beaa9733238c Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 19:02:36 +0100 Subject: [PATCH 45/51] Correct hyperlink Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index e91211a2b..0794aba29 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -583,7 +583,7 @@ current ones. ### Strengthen default algorithm selection for X.509 -This is described in the section [Strengthen default algorithm selection for X.509 and TLS](strengthen-default-algorithm-selection-for-x.509-and-tls). +This is described in the section [Strengthen default algorithm selection for X.509 and TLS](#strengthen-default-algorithm-selection-for-x.509-and-tls). ### Remove wrapper for libpkcs11-helper From a0148317327c1a59b94fe130a4dc252daa8f038b Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 19:08:51 +0100 Subject: [PATCH 46/51] Add missing backticks Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 0794aba29..c6e9c74f7 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -217,25 +217,25 @@ of this option for details. ### Separated `MBEDTLS_SHA224_C` and `MBEDTLS_SHA256_C` -This does not affect users who use the default `mbedtls_config.h`. MBEDTLS_SHA256_C -was enabled by default. Now both MBEDTLS_SHA256_C and MBEDTLS_SHA224_C are +This does not affect users who use the default `mbedtls_config.h`. `MBEDTLS_SHA256_C` +was enabled by default. Now both `MBEDTLS_SHA256_C` and `MBEDTLS_SHA224_C` are enabled. -If you were using custom config file with MBEDTLS_SHA256_C enabled, then +If you were using custom config file with `MBEDTLS_SHA256_C` enabled, then you will need to add `#define MBEDTLS_SHA224_C` option to your config. -Current version of the library does not support enabling MBEDTLS_SHA256_C -without MBEDTLS_SHA224_C. +Current version of the library does not support enabling `MBEDTLS_SHA256_C` +without `MBEDTLS_SHA224_C`. ### Replaced `MBEDTLS_SHA512_NO_SHA384` with `MBEDTLS_SHA384_C` This does not affect users who use the default `mbedtls_config.h`. -MBEDTLS_SHA512_NO_SHA384 was disabled by default, now MBEDTLS_SHA384_C is +`MBEDTLS_SHA512_NO_SHA384` was disabled by default, now `MBEDTLS_SHA384_C` is enabled by default. -If you were using a config file with both MBEDTLS_SHA512_C and -MBEDTLS_SHA512_NO_SHA384, then just remove the MBEDTLS_SHA512_NO_SHA384. -If you were using a config file with MBEDTLS_SHA512_C and without -MBEDTLS_SHA512_NO_SHA384 and you need the SHA-384 algorithm, then add +If you were using a config file with both `MBEDTLS_SHA512_C` and +MBEDTLS_SHA512_NO_SHA384, then just remove the `MBEDTLS_SHA512_NO_SHA384`. +If you were using a config file with `MBEDTLS_SHA512_C` and without +`MBEDTLS_SHA512_NO_SHA384` and you need the SHA-384 algorithm, then add `#define MBEDTLS_SHA384_C` to your config file. ### GCM multipart interface: application changes @@ -532,7 +532,7 @@ function. The API is changed to include the parameter `critical` which enables marking an extension included in a CSR as critical. To get the previous behavior pass 0. -### Remove the config option MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION +### Remove the config option `MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION` This change does not affect users of the default configuration; it only affects users who enable this option. From 10963278e7a14dfdfafd22c864c47a2fb463c771 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 19:11:22 +0100 Subject: [PATCH 47/51] Mark all code blocks as C Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index c6e9c74f7..1b673f7ac 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -725,7 +725,7 @@ If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuri ### SSL key export interface change This affects users of the SSL key export APIs: -``` +```C mbedtls_ssl_conf_export_keys_cb() mbedtls_ssl_conf_export_keys_ext_cb() ``` @@ -876,7 +876,7 @@ Those users will need to modify the API of their session cache implementation to that of a key-value store with keys being session IDs and values being instances of `mbedtls_ssl_session`: -``` +```C typedef int mbedtls_ssl_cache_get_t( void *data, unsigned char const *session_id, size_t session_id_len, @@ -992,7 +992,7 @@ The compile-time options `MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES` and `M The curve secp256k1 has also been removed from the default X.509 and TLS profiles. [RFC 8422](https://datatracker.ietf.org/doc/html/rfc8422#section-5.1.1) deprecates it in TLS, and it is very rarely used, although it is not known to be weak at the time of writing. If you still need to accept certificates signed with algorithms that have been removed from the default profile, call `mbedtls_x509_crt_verify_with_profile` instead of `mbedtls_x509_crt_verify` and pass a profile that allows the curves and hashes you want. For example, to allow SHA-224: -``` +```C mbedtls_x509_crt_profile my_profile = mbedtls_x509_crt_profile_default; my_profile.allowed_mds |= MBEDTLS_X509_ID_FLAG( MBEDTLS_MD_SHA224 ); ``` From 26c12eb52349283eb3534bdb360974d7b646c14c Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 19:58:00 +0100 Subject: [PATCH 48/51] Remove C from code block Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 1b673f7ac..9b3a0e9b7 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -725,7 +725,7 @@ If you prefer a different order, call `mbedtls_ssl_conf_curves()` when configuri ### SSL key export interface change This affects users of the SSL key export APIs: -```C +``` mbedtls_ssl_conf_export_keys_cb() mbedtls_ssl_conf_export_keys_ext_cb() ``` From b0e6bb54f9191e323363218838c1b24816165d24 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 20:03:55 +0100 Subject: [PATCH 49/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 9b3a0e9b7..8b3275c09 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -356,6 +356,12 @@ and include the `compat_2.x.h` header file which holds macros with proper renaming or to rename those functions in their code according to the list from mentioned header file. +### Remove the RNG parameter from RSA verify functions + +RSA verification functions also no longer take random generator arguments (this +was only needed when using a private key). This affects all applications using +the RSA verify functions. + ## High-level crypto @@ -377,12 +383,6 @@ 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. -### Remove the RNG parameter from RSA verify functions - -RSA verification functions also no longer take random generator arguments (this -was only needed when using a private key). This affects all applications using -the RSA verify functions. - ### Remove MD2, MD4, RC4, Blowfish and XTEA algorithms This change affects users of the MD2, MD4, RC4, Blowfish and XTEA algorithms. From 9637bd30a38b02c9e5196821bcb47474ce8c9080 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 20:07:57 +0100 Subject: [PATCH 50/51] Move subsections Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 60 ++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 8b3275c09..06f389df7 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -137,36 +137,6 @@ of the 2.x releases — no longer included in 3.0) might help you do that. Please also refer to the section [High-level crypto](#high-level-crypto) for changes that could sit in either category. -### The RNG parameter is now mandatory for all functions that accept one - -This change affects all users who called a function accepting a `f_rng` -parameter with `NULL` as the value of this argument; this is no longer -supported. - -The changed functions are: the X.509 CRT and CSR writing functions; the PK and -RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM -and ECDH that compute the shared secret; the scalar multiplication functions in -ECP. - -You now need to pass a properly seeded, cryptographically secure RNG to all -functions that accept a `f_rng` parameter. It is of course still possible to -pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a -context. - -Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` -configuration options) may have their own internal and are free to ignore the -`f_rng` argument but must allow users to pass one anyway. - -### Some functions gained an RNG parameter - -This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, -`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and -`mbedtls_pk_parse_keyfile()`. - -You now need to pass a properly seeded, cryptographically secure RNG when -calling these functions. It is used for blinding, a countermeasure against -side-channel attacks. - ### Deprecated functions were removed from bignum The function `mbedtls_mpi_is_prime()` was removed. Please use @@ -476,6 +446,36 @@ 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. +### The RNG parameter is now mandatory for all functions that accept one + +This change affects all users who called a function accepting a `f_rng` +parameter with `NULL` as the value of this argument; this is no longer +supported. + +The changed functions are: the X.509 CRT and CSR writing functions; the PK and +RSA sign and decrypt functions; `mbedtls_rsa_private()`; the functions in DHM +and ECDH that compute the shared secret; the scalar multiplication functions in +ECP. + +You now need to pass a properly seeded, cryptographically secure RNG to all +functions that accept a `f_rng` parameter. It is of course still possible to +pass `NULL` as the context pointer `p_rng` if your RNG function doesn't need a +context. + +Alternative implementations of a module (enabled with the `MBEDTLS_module_ALT` +configuration options) may have their own internal and are free to ignore the +`f_rng` argument but must allow users to pass one anyway. + +### Some functions gained an RNG parameter + +This affects users of the following functions: `mbedtls_ecp_check_pub_priv()`, +`mbedtls_pk_check_pair()`, `mbedtls_pk_parse_key()`, and +`mbedtls_pk_parse_keyfile()`. + +You now need to pass a properly seeded, cryptographically secure RNG when +calling these functions. It is used for blinding, a countermeasure against +side-channel attacks. + ## PSA From 7b743193b09cd2118074d62a3a14af149cb8d630 Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 20:10:10 +0100 Subject: [PATCH 51/51] Move subsection Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 70 ++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 06f389df7..a814c929c 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -332,6 +332,41 @@ RSA verification functions also no longer take random generator arguments (this was only needed when using a private key). This affects all applications using the RSA verify functions. +### Remove the padding parameters from `mbedtls_rsa_init()` + +This affects all users who use the RSA encryption, decryption, sign and +verify APIs. + +The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1 +encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If +you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call +to `mbedtls_rsa_init()`, to call `mbedtls_rsa_set_padding()` to set it. + +To choose the padding type when initializing a context, instead of + +```C + mbedtls_rsa_init(ctx, padding, hash_id); +``` + +use + +```C + mbedtls_rsa_init(ctx); + mbedtls_rsa_set_padding(ctx, padding, hash_id); +``` + +To use PKCS#1 v1.5 padding, instead of + +```C + mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, ); +``` + +just use + +```C + mbedtls_rsa_init(ctx); +``` + ## High-level crypto @@ -402,41 +437,6 @@ The signature functions in the PK module no longer accept 0 as the `hash_len` pa The migration path is to pass the correct value to those functions. -### Remove the padding parameters from `mbedtls_rsa_init()` - -This affects all users who use the RSA encryption, decryption, sign and -verify APIs. - -The function `mbedtls_rsa_init()` no longer supports selecting the PKCS#1 v2.1 -encoding and its hash. It just selects the PKCS#1 v1.5 encoding by default. If -you were using the PKCS#1 v2.1 encoding you now need, subsequently to the call -to `mbedtls_rsa_init()`, to call `mbedtls_rsa_set_padding()` to set it. - -To choose the padding type when initializing a context, instead of - -```C - mbedtls_rsa_init(ctx, padding, hash_id); -``` - -use - -```C - mbedtls_rsa_init(ctx); - mbedtls_rsa_set_padding(ctx, padding, hash_id); -``` - -To use PKCS#1 v1.5 padding, instead of - -```C - mbedtls_rsa_init(ctx, MBEDTLS_RSA_PKCS_V15, ); -``` - -just use - -```C - mbedtls_rsa_init(ctx); -``` - ### Some function parameters were made const Various functions in the PK and ASN.1 modules had a `const` qualifier added to