Release Mbed TLS 4.0.0-beta · Mbed-TLS/mbedtls

Description

The Mbed TLS 4.0.0-beta and TF-PSA-Crypto 1.0.0-beta releases introduce a major codebase restructuring:

PSA Crypto functionality now resides in its own repository Mbed-TLS/TF-PSA-Crypto.
TLS and X.509 components remain in Mbed TLS.

API Changes & Migration

These betas include significant API changes that break backward compatibility with previous releases. Please test your integration thoroughly and follow the 4.0-migration-guide to update your codebase to the new interfaces.

Please note

These beta versions must be used together to validate your integration against the newly split interfaces.
The 4.0 Migration Guide is currently under construction and will be continuously updated as we prepare for the full, non-beta release.

Intended audience for this beta

Integrators: To evaluate the impact of the Mbed TLS split and API changes on your codebase.
Early adopters: Anyone who wants to experiment with the upcoming interfaces and provide feedback before the formal release.

These betas are not production-ready. For deployments requiring stability and the latest security fixes, please continue using the LTS release Mbed TLS 3.6.4

Security Advisories

For full details, please see the following links:

Release Notes

API changes

The experimental functions psa_generate_key_ext() and
psa_key_derivation_output_key_ext() have been replaced by
psa_generate_key_custom() and psa_key_derivation_output_key_custom().
They have almost exactly the same interface, but the variable-length
data is passed in a separate parameter instead of a flexible array
member. This resolves a build failure under C++ compilers that do not
support flexible array members (a C99 feature not adopted by C++).
Fixes #9020.
Align the mbedtls_ssl_ticket_setup() function with the PSA Crypto API.
Instead of taking a mbedtls_cipher_type_t as an argument, this function
now takes 3 new arguments: a PSA algorithm, key type and key size, to
specify the AEAD for ticket protection.
The PSA and Mbed TLS error spaces are now unified. mbedtls_xxx()
functions can now return PSA_ERROR_xxx values.
There is no longer a distinction between "low-level" and "high-level"
Mbed TLS error codes.
This will not affect most applications since the error values are
between -32767 and -1 as before.
All API functions now use the PSA random generator psa_get_random()
internally. As a consequence, functions no longer take RNG parameters.
Please refer to the migration guide at :
tf-psa-crypto/docs/4.0-migration-guide.md.

Default behavior changes

In a PSA-client-only build (i.e. MBEDTLS_PSA_CRYPTO_CLIENT &&
!MBEDTLS_PSA_CRYPTO_C), do not automatically enable local crypto when the
corresponding PSA mechanism is enabled, since the server provides the
crypto. Fixes #9126.
The PK, X.509, PKCS7 and TLS modules now always use the PSA subsystem
to perform cryptographic operations, with a few exceptions documented
in docs/architecture/psa-migration/psa-limitations.md. This
corresponds to the behavior of Mbed TLS 3.x when
MBEDTLS_USE_PSA_CRYPTO is enabled. In effect, MBEDTLS_USE_PSA_CRYPTO
is now always enabled.
psa_crypto_init() must be called before performing any cryptographic
operation, including indirect requests such as parsing a key or
certificate or starting a TLS handshake.
The PSA_WANT_XXX symbols as defined in
tf-psa-crypto/include/psa/crypto_config.h are now always used in the
configuration of the cryptographic mechanisms exposed by the PSA API.
This corresponds to the configuration behavior of Mbed TLS 3.x when
MBEDTLS_PSA_CRYPTO_CONFIG is enabled. In effect, MBEDTLS_PSA_CRYPTO_CONFIG
is now always enabled and the configuration option has been removed.
In TLS clients, if mbedtls_ssl_set_hostname() has not been called,
mbedtls_ssl_handshake() now fails with
MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME
if certificate-based authentication of the server is attempted.
This is because authenticating a server without knowing what name
to expect is usually insecure.

Removals

Drop support for VIA Padlock. Removes MBEDTLS_PADLOCK_C.
Fixes #5903.
Drop support for crypto alt interface. Removes MBEDTLS_XXX_ALT options
at the module and function level for crypto mechanisms only. The remaining
alt interfaces for platform, threading and timing are unchanged.
Fixes #8149.
Remove support for the RSA-PSK key exchange in TLS 1.2.
Remove deprecated mbedtls_x509write_crt_set_serial(). The function was
already deprecated and superseeded by
mbedtls_x509write_crt_set_serial_raw().
Remove the function mbedtls_ssl_conf_curves() which had been deprecated
in favour of mbedtls_ssl_conf_groups() since Mbed TLS 3.1.
Remove support for the DHE-PSK key exchange in TLS 1.2.
Remove support for the DHE-RSA key exchange in TLS 1.2.
Following the removal of DHM module (#9972 and TF-PSA-Crypto#175) the
following SSL functions are removed:
- mbedtls_ssl_conf_dh_param_bin
- mbedtls_ssl_conf_dh_param_ctx
- mbedtls_ssl_conf_dhm_min_bitlen
Remove support for the RSA key exchange in TLS 1.2.
Remove mbedtls_low_level_sterr() and mbedtls_high_level_strerr(),
since these concepts no longer exists. There is just mbedtls_strerror().
* Removal of the following sample programs:
pkey/rsa_genkey.c
pkey/pk_decrypt.c
pkey/dh_genprime.c
pkey/rsa_verify.c
pkey/mpi_demo.c
pkey/rsa_decrypt.c
pkey/key_app.c
pkey/dh_server.c
pkey/ecdh_curve25519.c
pkey/pk_encrypt.c
pkey/rsa_sign.c
pkey/key_app_writer.c
pkey/dh_client.c
pkey/ecdsa.c
pkey/rsa_encrypt.c
wince_main.c
aes/crypt_and_hash.c
random/gen_random_ctr_drbg.c
random/gen_entropy.c
hash/md_hmac_demo.c
hash/hello.c
hash/generic_sum.c
cipher/cipher_aead_demo.c
Remove compat-2-x.h header from mbedtls.
The library no longer offers interfaces to look up values by OID
or OID by enum values.
The header <mbedtls/oid.h> now only defines functions to convert
between binary and dotted string OID representations, and macros
for OID strings that are relevant to X.509.
The compilation option MBEDTLS_OID_C no longer
exists. OID tables are included in the build automatically as needed.

Features

When the new compilation option MBEDTLS_PSA_KEY_STORE_DYNAMIC is enabled,
the number of volatile PSA keys is virtually unlimited, at the expense
of increased code size. This option is off by default, but enabled in
the default mbedtls_config.h. Fixes #9216.
Add a new psa_key_agreement() PSA API to perform key agreement and return
an identifier for the newly created key.
Added new configuration option MBEDTLS_PSA_STATIC_KEY_SLOTS, which
uses static storage for keys, enabling malloc-less use of key slots.
The size of each buffer is given by the option
MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE. By default it accommodates the
largest PSA key enabled in the build.
Add an interruptible version of key agreement to the PSA interface.
See psa_key_agreement_iop_setup() and related functions.
Add an interruptible version of generate key to the PSA interface.
See psa_generate_key_iop_setup() and related functions.
Add the function mbedtls_ssl_export_keying_material() which allows the
client and server to extract additional shared symmetric keys from an SSL
session, according to the TLS-Exporter specification in RFC 8446 and 5705.
This requires MBEDTLS_SSL_KEYING_MATERIAL_EXPORT to be defined in
mbedtls_config.h.

Security

Unlike previously documented, enabling MBEDTLS_PSA_HMAC_DRBG_MD_TYPE does
not cause the PSA subsystem to use HMAC_DRBG: it uses HMAC_DRBG only when
MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG and MBEDTLS_CTR_DRBG_C are disabled.
CVE-2024-45157
Fix a stack buffer overflow in mbedtls_ecdsa_der_to_raw() and
mbedtls_ecdsa_raw_to_der() when the bits parameter is larger than the
largest supported curve. In some configurations with PSA disabled,
all values of bits are affected. This never happens in internal library
calls, but can affect applications that call these functions directly.
CVE-2024-45158
With TLS 1.3, when a server enables optional authentication of the
client, if the client-provided certificate does not have appropriate values
in keyUsage or extKeyUsage extensions, then the return value of
mbedtls_ssl_get_verify_result() would incorrectly have the
MBEDTLS_X509_BADCERT_KEY_USAGE and MBEDTLS_X509_BADCERT_EXT_KEY_USAGE bits
clear. As a result, an attacker that had a certificate valid for uses other
than TLS client authentication could be able to use it for TLS client
authentication anyway. Only TLS 1.3 servers were affected, and only with
optional authentication (required would abort the handshake with a fatal
alert).
CVE-2024-45159
Fix a buffer underrun in mbedtls_pk_write_key_der() when
called on an opaque key, MBEDTLS_USE_PSA_CRYPTO is enabled,
and the output buffer is smaller than the actual output.
Fix a related buffer underrun in mbedtls_pk_write_key_pem()
when called on an opaque RSA key, MBEDTLS_USE_PSA_CRYPTO is enabled
and MBEDTLS_MPI_MAX_SIZE is smaller than needed for a 4096-bit RSA key.
CVE-2024-49195
Note that TLS clients should generally call mbedtls_ssl_set_hostname()
if they use certificate authentication (i.e. not pre-shared keys).
Otherwise, in many scenarios, the server could be impersonated.
The library will now prevent the handshake and return
MBEDTLS_ERR_SSL_CERTIFICATE_VERIFICATION_WITHOUT_HOSTNAME
if mbedtls_ssl_set_hostname() has not been called.
Reported by Daniel Stenberg.
CVE-2025-27809
Fix a vulnerability in the TLS 1.2 handshake. If memory allocation failed
or there was a cryptographic hardware failure when calculating the
Finished message, it could be calculated incorrectly. This would break
the security guarantees of the TLS handshake.
CVE-2025-27810
Fix possible use-after-free or double-free in code calling
mbedtls_x509_string_to_names(). This was caused by the function calling
mbedtls_asn1_free_named_data_list() on its head argument, while the
documentation did no suggest it did, making it likely for callers relying
on the documented behaviour to still hold pointers to memory blocks after
they were free()d, resulting in high risk of use-after-free or double-free,
with consequences ranging up to arbitrary code execution.
In particular, the two sample programs x509/cert_write and x509/cert_req
were affected (use-after-free if the san string contains more than one DN).
Code that does not call mbedtls_string_to_names() directly is not affected.
Found by Linh Le and Ngan Nguyen from Calif.
CVE-2025-47917
Fix a bug in mbedtls_x509_string_to_names() and the
mbedtls_x509write_{crt,csr}set{subject,issuer}_name() functions,
where some inputs would cause an inconsistent state to be reached, causing
a NULL dereference either in the function itself, or in subsequent
users of the output structure, such as mbedtls_x509_write_names(). This
only affects applications that create (as opposed to consume) X.509
certificates, CSRs or CRLs. Found by Linh Le and Ngan Nguyen from Calif.
CVE-2025-48965

Bugfix

Fix TLS 1.3 client build and runtime when support for session tickets is
disabled (MBEDTLS_SSL_SESSION_TICKETS configuration option). Fixes #6395.
Fix compilation error when memcpy() is a function-like macros. Fixes #8994.
MBEDTLS_ASN1_PARSE_C and MBEDTLS_ASN1_WRITE_C are now automatically enabled
as soon as MBEDTLS_RSA_C is enabled. Fixes #9041.
Fix undefined behaviour (incrementing a NULL pointer by zero length) when
passing in zero length additional data to multipart AEAD.
Fix rare concurrent access bug where attempting to operate on a
non-existent key while concurrently creating a new key could potentially
corrupt the key store.
Fix error handling when creating a key in a dynamic secure element
(feature enabled by MBEDTLS_PSA_CRYPTO_SE_C). In a low memory condition,
the creation could return PSA_SUCCESS but using or destroying the key
would not work. Fixes #8537.
Fix issue of redefinition warning messages for _GNU_SOURCE in
entropy_poll.c and sha_256.c. There was a build warning during
building for linux platform.
Resolves #9026
Fix a compilation warning in pk.c when PSA is enabled and RSA is disabled.
Fix the build when MBEDTLS_PSA_CRYPTO_CONFIG is enabled and the built-in
CMAC is enabled, but no built-in unauthenticated cipher is enabled.
Fixes #9209.
Fix redefinition warnings when SECP192R1 and/or SECP192K1 are disabled.
Fixes #9029.
Fix psa_cipher_decrypt() with CCM* rejecting messages less than 3 bytes
long. Credit to Cryptofuzz. Fixes #9314.
Fix interference between PSA volatile keys and built-in keys
when MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS is enabled and
MBEDTLS_PSA_KEY_SLOT_COUNT is more than 4096.
Document and enforce the limitation of mbedtls_psa_register_se_key()
to persistent keys. Resolves #9253.
Fix Clang compilation error when MBEDTLS_USE_PSA_CRYPTO is enabled
but MBEDTLS_DHM_C is disabled. Reported by Michael Schuster in #9188.
Fix server mode only build when MBEDTLS_SSL_SRV_C is enabled but
MBEDTLS_SSL_CLI_C is disabled. Reported by M-Bab on GitHub in #9186.
When MBEDTLS_PSA_CRYPTO_C was disabled and MBEDTLS_ECDSA_C enabled,
some code was defining 0-size arrays, resulting in compilation errors.
Fixed by disabling the offending code in configurations without PSA
Crypto, where it never worked. Fixes #9311.
Fixes an issue where some TLS 1.2 clients could not connect to an
Mbed TLS 3.6.0 server, due to incorrect handling of
legacy_compression_methods in the ClientHello.
fixes #8995, #9243.
Fix a memory leak that could occur when failing to process an RSA
key through some PSA functions due to low memory conditions.
Fixed a regression introduced in 3.6.0 where the CA callback set with
mbedtls_ssl_conf_ca_cb() would stop working when connections were
upgraded to TLS 1.3. Fixed by adding support for the CA callback with TLS
1.3.
Fixed a regression introduced in 3.6.0 where clients that relied on
optional/none authentication mode, by calling mbedtls_ssl_conf_authmode()
with MBEDTLS_SSL_VERIFY_OPTIONAL or MBEDTLS_SSL_VERIFY_NONE, would stop
working when connections were upgraded to TLS 1.3. Fixed by adding
support for optional/none with TLS 1.3 as well. Note that the TLS 1.3
standard makes server authentication mandatory; users are advised not to
use authmode none, and to carefully check the results when using optional
mode.
Fixed a regression introduced in 3.6.0 where context-specific certificate
verify callbacks, set with mbedtls_ssl_set_verify() as opposed to
mbedtls_ssl_conf_verify(), would stop working when connections were
upgraded to TLS 1.3. Fixed by adding support for context-specific verify
callback in TLS 1.3.
Fix unintended performance regression when using short RSA public keys.
Fixes #9232.
When MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE is disabled, work with
peers that have middlebox compatibility enabled, as long as no
problematic middlebox is in the way. Fixes #9551.
Fix invalid JSON schemas for driver descriptions used by
generate_driver_wrappers.py.
Use 'mbedtls_net_close' instead of 'close' in 'mbedtls_net_bind'
and 'mbedtls_net_connect' to prevent possible double close fd
problems. Fixes #9711.
Fix undefined behavior in some cases when mbedtls_psa_raw_to_der() or
mbedtls_psa_der_to_raw() is called with bits=0.
Fix compilation on MS-DOS DJGPP. Fixes #9813.
Fix missing constraints on the AES-NI inline assembly which is used on
GCC-like compilers when building AES for generic x86_64 targets. This
may have resulted in incorrect code with some compilers, depending on
optimizations. Fixes #9819.
Support re-assembly of fragmented handshake messages in TLS (both
1.2 and 1.3). The lack of support was causing handshake failures with
some servers, especially with TLS 1.3 in practice. There are a few
limitations, notably a fragmented ClientHello is only supported when
TLS 1.3 support is enabled. See the documentation of
mbedtls_ssl_handshake() for details.
Fix definition of MBEDTLS_PRINTF_SIZET to prevent runtime crashes that
occurred whenever SSL debugging was enabled on a copy of Mbed TLS built
with Visual Studio 2013 or MinGW.
Fixes #10017.
Silence spurious -Wunterminated-string-initialization warnings introduced
by GCC 15. Fixes #9944.

Changes

Warn if mbedtls/check_config.h is included manually, as this can
lead to spurious errors. Error if a adjust.h header is included
manually, as this can lead to silently inconsistent configurations,
potentially resulting in buffer overflows.
When migrating from Mbed TLS 2.x, if you had a custom config.h that
included check_config.h, remove this inclusion from the Mbed TLS 3.x
configuration file (renamed to mbedtls_config.h). This change was made
in Mbed TLS 3.0, but was not announced in a changelog entry at the time.
Functions regarding numeric string conversions for OIDs have been moved
from the OID module and now reside in X.509 module. This helps to reduce
the code size as these functions are not commonly used outside of X.509.
Improve performance of PSA key generation with ECC keys: it no longer
computes the public key (which was immediately discarded). Fixes #9732.
Cryptography and platform configuration options have been migrated
from the Mbed TLS library configuration file mbedtls_config.h to
crypto_config.h that will become the TF-PSA-Crypto configuration file,
see config-split.md for more information. The reference and test custom
configuration files respectively in configs/ and tests/configs/ have
been updated accordingly.
To migrate custom Mbed TLS configurations where
MBEDTLS_PSA_CRYPTO_CONFIG is disabled, you should first adapt them
to the PSA configuration scheme based on PSA_WANT_XXX symbols
(see psa-conditional-inclusion-c.md for more information).
To migrate custom Mbed TLS configurations where
MBEDTLS_PSA_CRYPTO_CONFIG is enabled, you should migrate the
cryptographic and platform configuration options from mbedtls_config.h
to crypto_config.h (see config-split.md for more information and configs/
for examples).
Move the crypto part of the library (content of tf-psa-crypto directory)
from the Mbed TLS to the TF-PSA-Crypto repository. The crypto code and
tests development will now occur in TF-PSA-Crypto, which Mbed TLS
references as a Git submodule.
The function mbedtls_x509_string_to_names() now requires its head argument
to point to NULL on entry. This makes it likely that existing risky uses of
this function (see the entry in the Security section) will be detected and
fixed.

Note

❕ mbedtls-4.0.0-beta.tar.bz2 are our official release files. source.tar.gz and source.zip are automatically generated snapshot's that github is generating. They do not include external dependencies, and can't be configured

Checksum

The SHA256 hashes for the archives are:
210ac92706a8dd57180a3fee32fbfe879426aa062e31b94f3a287fdd0db61069 mbedtls-4.0.0-beta.tar.bz2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Mbed TLS 4.0.0-beta