* In code, use `#include <mbedtls/build_info.h>`. 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:
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.
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
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
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.
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:
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.
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()
