lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-10-26 00:37:41 +03:00
Code Activity

Merge tag 'v4.0.0' into mbedtls-4.0.0_mergeback

Browse Source 
Mbed TLS 4.0.0

Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
This commit is contained in:
Minos Galanakis
2025-10-15 16:58:25 +01:00
parent 3765e5ca7e ec4044008d
commit 2842c33e2c
69 changed files with 767 additions and 2045 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
BRANCHES.md
View File

@@ -6,9 +6,8 @@ At any point in time, we have a number of maintained branches, currently consist
this always contains the latest release, including all publicly available
security fixes.
- The [`development`](https://github.com/Mbed-TLS/mbedtls/tree/development) branch:
this is where the next major version of Mbed TLS (version 4.0) is being
prepared. It has API changes that make it incompatible with Mbed TLS 3.x,
as well as all the new features and bug fixes and security fixes.
this is where the next minor version of Mbed TLS 4.x is prepared. It contains
new features, bug fixes, and security fixes.
- One or more long-time support (LTS) branches: these only get bug fixes and
security fixes. Currently, the supported LTS branches are:
- [`mbedtls-3.6`](https://github.com/Mbed-TLS/mbedtls/tree/mbedtls-3.6).
@@ -19,7 +18,7 @@ These branches will not receive any changes or updates.
We use [Semantic Versioning](https://semver.org/). In particular, we maintain
API compatibility in the `main` branch across minor version changes (e.g.
the API of 3.(x+1) is backward compatible with 3.x). We only break API
the API of 4.(x+1) is backward compatible with 4.x). We only break API
compatibility on major version changes (e.g. from 3.x to 4.0). We also maintain
ABI compatibility within LTS branches; see the next section for details.
@@ -66,25 +65,6 @@ crypto that was found to be weak) may need to be changed. In case security
comes in conflict with backwards compatibility, we will put security first,
but always attempt to provide a compatibility option.
## Backward compatibility for the key store
We maintain backward compatibility with previous versions of the
PSA Crypto persistent storage since Mbed TLS 2.25.0, provided that the
storage backend (PSA ITS implementation) is configured in a compatible way.
We intend to maintain this backward compatibility throughout a major version
of Mbed TLS (for example, all Mbed TLS 3.y versions will be able to read
keys written under any Mbed TLS 3.x with x <= y).
Mbed TLS 3.x can also read keys written by Mbed TLS 2.25.0 through 2.28.x
LTS, but future major version upgrades (for example from 2.28.x/3.x to 4.y)
may require the use of an upgrade tool.
Note that this guarantee does not currently fully extend to drivers, which
are an experimental feature. We intend to maintain compatibility with the
basic use of drivers from Mbed TLS 2.28.0 onwards, even if driver APIs
change. However, for more experimental parts of the driver interface, such
as the use of driver state, we do not yet guarantee backward compatibility.
## Long-time support branches
For the LTS branches, additionally we try very hard to also maintain ABI

192
ChangeLog
View File

@@ -1,16 +1,8 @@
Mbed TLS ChangeLog (Sorted per branch, date)
= Mbed TLS 4.0.0-beta branch released 2025-07-04
= Mbed TLS 4.0.0 branch released 2025-10-15
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
@@ -24,14 +16,32 @@ API changes
* All API functions now use the PSA random generator psa_generate_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.
docs/4.0-migration-guide.md.
* The list passed to mbedtls_ssl_conf_alpn_protocols() is now declared
as having const elements, reflecting the fact that the library will
not modify it
* Change the serial argument of the mbedtls_x509write_crt_set_serial_raw
function to a const to align with the rest of the API.
* Change the signature of the runtime version information methods that took
a char* as an argument to take zero arguments and return a const char*
instead. This aligns us with the interface used in TF PSA Crypto 1.0.
If you need to support linking against both Mbed TLS 3.x and 4.x, please
use the build-time version macros or mbedtls_version_get_number() to
determine the correct signature for mbedtls_version_get_string() and
mbedtls_version_get_string_full() before calling them.
Fixes issue #10308.
* Make the following error codes aliases of their PSA equivalents, where
xxx is a module, e.g. X509 or SSL.
MBEDTLS_ERR_xxx_BAD_INPUT_DATA -> PSA_ERROR_INVALID_ARGUMENT
MBEDTLS_ERR_xxx_ALLOC_FAILED -> PSA_ERROR_INSUFFICIENT_MEMORY
MBEDTLS_ERR_xxx_BUFFER_TOO_SMALL -> PSA_ERROR_BUFFER_TOO_SMALL
MBEDTLS_ERR_PKCS7_VERIFY_FAIL -> PSA_ERROR_INVALID_SIGNATURE
* Add MBEDTLS_SSL_NULL_CIPHERSUITES configuration option. It enables
TLS 1.2 ciphersuites without encryption and is disabled by default.
This new option replaces MBEDTLS_CIPHER_NULL_CIPHER.
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
* The X.509 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
@@ -40,12 +50,6 @@ Default behavior changes
* 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
@@ -54,12 +58,6 @@ Default behavior changes
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 superseded by
@@ -108,23 +106,31 @@ Removals
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.
* The header <mbedtls/check_config.h> no longer exists. Including it
from a custom config file was no longer needed since Mbed TLS 3.0,
and could lead to spurious errors. The checks that it performed are
now done automatically when building the library.
* Support for secp192k1, secp192r1, secp224k1 and secp224r1 EC curves is
removed from TLS.
* Remove mbedtls_pk_type_t from the public interface and replace it with
mbedtls_pk_sigalg_t.
* Remove MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT. Now only the
standard version (defined in RFC 9146) of DTLS connection ID is supported.
* Remove mbedtls_ssl_conf_min_version(), mbedtls_ssl_conf_max_version(), and
the associated constants MBEDTLS_SSL_MAJOR_VERSION_x and
MBEDTLS_SSL_MINOR_VERSION_y. Use mbedtls_ssl_conf_min_tls_version() and
mbedtls_ssl_conf_max_tls_version() with MBEDTLS_SSL_VERSION_TLS1_y instead.
Note that the new names of the new constants use the TLS protocol versions,
unlike the old constants whose names are based on internal encodings.
* Remove mbedtls_ssl_conf_sig_hashes(). Use mbedtls_ssl_conf_sig_algs()
instead.
* Removed all public key sample programs from the programs/pkey
directory.
* Removed support for TLS 1.2 static ECDH key
exchanges (ECDH-ECDSA and ECDH-RSA).
* Drop support for the GNU Make and Microsoft Visual Studio build systems.
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.
@@ -132,16 +138,6 @@ Features
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
@@ -153,13 +149,6 @@ Security
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.
@@ -193,53 +182,26 @@ Security
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
* Fix a bug in tf-psa-crypto's mbedtls_asn1_store_named_data() where it
would sometimes leave an item in the output list in an inconsistent
state with val.p == NULL but val.len > 0. Affected functions used in X.509
would then dereference a NULL pointer. Applications that do not
call this function (directly, or indirectly through X.509 writing) are not
affected. 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 Clang compilation error when finite-field Diffie-Hellman 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
@@ -257,23 +219,13 @@ Bugfix
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
@@ -286,36 +238,16 @@ Bugfix
Fixes #10017.
* Silence spurious -Wunterminated-string-initialization warnings introduced
by GCC 15. Fixes #9944.
* Fix potential CMake parallel build failure when building both the static
and shared libraries.
* Fix a build error or incorrect TLS session
lifetime on platforms where mbedtls_time_t
is not time_t. Fixes #10236.
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

3
ChangeLog.d/10285.txt
View File

@@ -1,3 +0,0 @@
Removals
* Removed all public key sample programs from the programs/pkey
directory.

2
ChangeLog.d/9684.txt
View File

@@ -1,2 +0,0 @@
Removals
* Remove support for the DHE-PSK key exchange in TLS 1.2.

2
ChangeLog.d/9685.txt
View File

@@ -1,2 +0,0 @@
Removals
* Remove support for the DHE-RSA key exchange in TLS 1.2.

5
ChangeLog.d/9874.txt
View File

@@ -1,5 +0,0 @@
API changes
* 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.

5
ChangeLog.d/9892.txt
View File

@@ -1,5 +0,0 @@
Removals
* Remove deprecated mbedtls_x509write_crt_set_serial(). The function was
already deprecated and superseded by
mbedtls_x509write_crt_set_serial_raw().

6
ChangeLog.d/9956.txt
View File

@@ -1,6 +0,0 @@
Removals
* 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

26
ChangeLog.d/9964.txt
View File

@@ -1,26 +0,0 @@
Removals
* Sample programs for the legacy crypto API have been removed.
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

6
ChangeLog.d/add-tls-exporter.txt
View File

@@ -1,6 +0,0 @@
Features
* 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.

5
ChangeLog.d/check_config.txt
View File

@@ -1,5 +0,0 @@
Removals
* The header <mbedtls/check_config.h> no longer exists. Including it
from a custom config file was no longer needed since Mbed TLS 3.0,
and could lead to spurious errors. The checks that it performed are
now done automatically when building the library.

12
ChangeLog.d/error-unification.txt
View File

@@ -1,12 +0,0 @@
API changes
* 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.
Removals
* Remove mbedtls_low_level_strerr() and mbedtls_high_level_strerr(),
since these concepts no longer exists. There is just mbedtls_strerror().

8
ChangeLog.d/fix-asn1-store-named-data.txt
View File

@@ -1,8 +0,0 @@
Security
* Fix a bug in tf-psa-crypto's mbedtls_asn1_store_named_data() where it
would sometimes leave an item in the output list in an inconsistent
state with val.p == NULL but val.len > 0. Affected functions used in X.509
would then dereference a NULL pointer. Applications that do not
call this function (directly, or indirectly through X.509 writing) are not
affected. Found by Linh Le and Ngan Nguyen from Calif.

5
ChangeLog.d/fix-clang-psa-build-without-dhm.txt
View File

@@ -1,5 +0,0 @@
Bugfix
* Fix Clang compilation error when finite-field Diffie-Hellman is disabled.
Reported by Michael Schuster in #9188.

2
ChangeLog.d/fix-compilation-when-memcpy-is-function-like-macro.txt
View File

@@ -1,2 +0,0 @@
Bugfix
* Fix compilation error when memcpy() is a function-like macros. Fixes #8994.

2
ChangeLog.d/fix-compilation-with-djgpp.txt
View File

@@ -1,2 +0,0 @@
Bugfix
* Fix compilation on MS-DOS DJGPP. Fixes #9813.

3
ChangeLog.d/fix-dependency-on-generated-files.txt
View File

@@ -1,3 +0,0 @@
Bugfix
* Fix potential CMake parallel build failure when building both the static
and shared libraries.

6
ChangeLog.d/fix-legacy-compression-issue.txt
View File

@@ -1,6 +0,0 @@
Bugfix
* 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.

5
ChangeLog.d/fix-msvc-version-guard-format-zu.txt
View File

@@ -1,5 +0,0 @@
Bugfix
* 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.

3
ChangeLog.d/fix-server-mode-only-build.txt
View File

@@ -1,3 +0,0 @@
Bugfix
* 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.

19
ChangeLog.d/fix-string-to-names-memory-management.txt
View File

@@ -1,19 +0,0 @@
Security
* 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
Changes
* 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.

10
ChangeLog.d/fix-string-to-names-store-named-data.txt
View File

@@ -1,10 +0,0 @@
Security
* 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

12
ChangeLog.d/fix_reporting_of_key_usage_issues.txt
View File

@@ -1,12 +0,0 @@
Security
* 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

2
ChangeLog.d/make-visualc.txt
View File

@@ -1,2 +0,0 @@
Removals
* Drop support for the GNU Make and Microsoft Visual Studio build systems.

4
ChangeLog.d/mbedtls-ssl-null-ciphersuites.txt
View File

@@ -1,4 +0,0 @@
API changes
* Add MBEDTLS_SSL_NULL_CIPHERSUITES configuration option. It enables
TLS 1.2 ciphersuites without encryption and is disabled by default.
This new option replaces MBEDTLS_CIPHER_NULL_CIPHER.

4
ChangeLog.d/mbedtls_ssl_conf_alpn_protocols.txt
View File

@@ -1,4 +0,0 @@
API changes
* The list passed to mbedtls_ssl_conf_alpn_protocols() is now declared
as having const elements, reflecting the fact that the library will
not modify it

18
ChangeLog.d/mbedtls_ssl_set_hostname.txt
View File

@@ -1,18 +0,0 @@
Default behavior changes
* 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.
Security
* 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

8
ChangeLog.d/oid.txt
View File

@@ -1,8 +0,0 @@
Removals
* 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.

11
ChangeLog.d/psa-always-on.txt
View File

@@ -1,11 +0,0 @@
Default behavior changes
* The X.509 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.

6
ChangeLog.d/removal-of-rng.txt
View File

@@ -1,6 +0,0 @@
API changes
* All API functions now use the PSA random generator psa_generate_random()
internally. As a consequence, functions no longer take RNG parameters.
Please refer to the migration guide at :
docs/4.0-migration-guide.md.

2
ChangeLog.d/remove-compat-2.x.txt
View File

@@ -1,2 +0,0 @@
Removals
* Remove compat-2-x.h header from mbedtls.

11
ChangeLog.d/remove-deprecated-items.txt
View File

@@ -1,11 +0,0 @@
Removals
* Remove MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT. Now only the
standard version (defined in RFC 9146) of DTLS connection ID is supported.
* Remove mbedtls_ssl_conf_min_version(), mbedtls_ssl_conf_max_version(), and
the associated constants MBEDTLS_SSL_MAJOR_VERSION_x and
MBEDTLS_SSL_MINOR_VERSION_y. Use mbedtls_ssl_conf_min_tls_version() and
mbedtls_ssl_conf_max_tls_version() with MBEDTLS_SSL_VERSION_TLS1_y instead.
Note that the new names of the new constants use the TLS protocol versions,
unlike the old constants whose names are based on internal encodings.
* Remove mbedtls_ssl_conf_sig_hashes(). Use mbedtls_ssl_conf_sig_algs()
instead.

2
ChangeLog.d/remove_RSA_key_exchange.txt
View File

@@ -1,2 +0,0 @@
Removals
* Remove support for the RSA key exchange in TLS 1.2.

3
ChangeLog.d/remove_mbedtls_pk_type.txt
View File

@@ -1,3 +0,0 @@
Removals
* Remove mbedtls_pk_type_t from the public interface and replace it with
mbedtls_pk_sigalg_t.

4
ChangeLog.d/replace-close-with-mbedtls_net_close.txt
View File

@@ -1,4 +0,0 @@
Bugfix
* Use 'mbedtls_net_close' instead of 'close' in 'mbedtls_net_bind'
and 'mbedtls_net_connect' to prevent possible double close fd
problems. Fixes #9711.

4
ChangeLog.d/replace_time_t.txt
View File

@@ -1,4 +0,0 @@
Bugfix
* Fix a build error or incorrect TLS session
lifetime on platforms where mbedtls_time_t
is not time_t. Fixes #10236.

5
ChangeLog.d/repo-split.txt
View File

@@ -1,5 +0,0 @@
Changes
* 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.

4
ChangeLog.d/rm-ssl-conf-curves.txt
View File

@@ -1,4 +0,0 @@
Removals
* Remove the function mbedtls_ssl_conf_curves() which had been deprecated
in favour of mbedtls_ssl_conf_groups() since Mbed TLS 3.1.

9
ChangeLog.d/runtime-version-interface.txt
View File

@@ -1,9 +0,0 @@
API changes
* Change the signature of the runtime version information methods that took
a char* as an argument to take zero arguments and return a const char*
instead. This aligns us with the interface used in TF PSA Crypto 1.0.
If you need to support linking against both Mbed TLS 3.x and 4.x, please
use the build-time version macros or mbedtls_version_get_number() to
determine the correct signature for mbedtls_version_get_string() and
mbedtls_version_get_string_full() before calling them.
Fixes issue #10308.

3
ChangeLog.d/secp256k1-removal.txt
View File

@@ -1,3 +0,0 @@
Removals
* Support for secp192k1, secp192r1, secp224k1 and secp224r1 EC curves is
removed from TLS.

4
ChangeLog.d/split-numeric-string-conversions-out-of-the-oid-module.txt
View File

@@ -1,4 +0,0 @@
Changes
* 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.

3
ChangeLog.d/static-ecdh-removal.txt
View File

@@ -1,3 +0,0 @@
Removals
* Removed support for TLS 1.2 static ECDH key
exchanges (ECDH-ECDSA and ECDH-RSA).

7
ChangeLog.d/tls-hs-defrag-in.txt
View File

@@ -1,7 +0,0 @@
Bugfix
* 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.

2
ChangeLog.d/tls-key-exchange-rsa.txt
View File

@@ -1,2 +0,0 @@
Removals
* Remove support for the RSA-PSK key exchange in TLS 1.2.

6
ChangeLog.d/tls12-check-finished-calc.txt
View File

@@ -1,6 +0,0 @@
Security
* 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

18
ChangeLog.d/tls13-cert-regressions.txt
View File

@@ -1,18 +0,0 @@
Bugfix
* 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.

4
ChangeLog.d/tls13-middlebox-compat-disabled.txt
View File

@@ -1,4 +0,0 @@
Bugfix
* 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.

3
ChangeLog.d/tls13-without-tickets.txt
View File

@@ -1,3 +0,0 @@
Bugfix
* Fix TLS 1.3 client build and runtime when support for session tickets is
disabled (MBEDTLS_SSL_SESSION_TICKETS configuration option). Fixes #6395.

7
ChangeLog.d/unify-errors.txt
View File

@@ -1,7 +0,0 @@
API changes
* Make the following error codes aliases of their PSA equivalents, where
xxx is a module, e.g. X509 or SSL.
MBEDTLS_ERR_xxx_BAD_INPUT_DATA -> PSA_ERROR_INVALID_ARGUMENT
MBEDTLS_ERR_xxx_ALLOC_FAILED -> PSA_ERROR_INSUFFICIENT_MEMORY
MBEDTLS_ERR_xxx_BUFFER_TOO_SMALL -> PSA_ERROR_BUFFER_TOO_SMALL
MBEDTLS_ERR_PKCS7_VERIFY_FAIL -> PSA_ERROR_INVALID_SIGNATURE

3
ChangeLog.d/unterminated-string-initialization.txt
View File

@@ -1,3 +0,0 @@
Bugfix
* Silence spurious -Wunterminated-string-initialization warnings introduced
by GCC 15. Fixes #9944.

3
ChangeLog.d/x509write_crt_set_serial_raw-alignment.txt
View File

@@ -1,3 +0,0 @@
API changes
* Change the serial argument of the mbedtls_x509write_crt_set_serial_raw
function to a const to align with the rest of the API.

143
README.md
View File

@@ -1,55 +1,62 @@
README for Mbed TLS
===================
Mbed TLS is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems.
Mbed TLS includes a reference implementation of the [PSA Cryptography API](#psa-cryptography-api). This is currently a preview for evaluation purposes only.
Mbed TLS is a C library that implements X.509 certificate manipulation and the TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems.
Mbed TLS includes the [TF-PSA-Crypto repository](https://github.com/Mbed-TLS/TF-PSA-Crypto) that provides an implementation of the [PSA Cryptography API](https://arm-software.github.io/psa-api).
Configuration
-------------
Configuration options related to X.509 and TLS are available in `include/mbedtls/mbedtls_config.h`, while cryptography and platform options are located in the TF-PSA-Crypto configuration file `tf-psa-crypto/include/psa/crypto_config.h`.
Mbed TLS should build out of the box on most systems. Some platform specific options are available in the fully documented configuration file `include/mbedtls/mbedtls_config.h`, which is also the place where features can be selected. This file can be edited manually, or in a more programmatic way using the Python 3 script `scripts/config.py` (use `--help` for usage instructions).
With the default platform options, Mbed TLS should build out of the box on most systems.
Compiler options can be set using conventional environment variables such as `CC` and `CFLAGS`.
These configuration files can be edited manually, or programmatically using the Python script `scripts/config.py` (run with --help for usage instructions).
We provide some non-standard configurations focused on specific use cases in the `configs/` directory. You can read more about those in `configs/README.txt`
We provide some non-standard configurations focused on specific use cases in the `configs/` directory. You can read more about those in `configs/README.txt`.
Documentation
-------------
The main Mbed TLS documentation is available via [ReadTheDocs](https://mbed-tls.readthedocs.io/).
Documentation for the PSA Cryptography API is available [on GitHub](https://arm-software.github.io/psa-api/crypto/).
To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration:
1. Make sure that [Doxygen](http://www.doxygen.nl/) is installed.
1. Run `mkdir /path/to/build_dir && cd /path/to/build_dir`
1. Run `cmake /path/to/mbedtls/source`
1. Run `make apidoc`
1. Browse `apidoc/index.html` or `apidoc/modules.html`.
1. Run `cmake -B /path/to/build_dir /path/to/mbedtls/source`
1. Run `cmake --build /path/to/build_dir --target mbedtls-apidoc`
1. Open one of the main generated HTML files:
* `apidoc/index.html`
* `apidoc/modules.html` or `apidoc/topics.html`
For other sources of documentation, see the [SUPPORT](SUPPORT.md) document.
Compiling
---------
We use CMake to configure and drive our build process. Three libraries are built: libtfpsacrypto, libmbedx509, and libmbedtls. Note that libmbedtls depends on libmbedx509 and libtfpsacrypto, and libmbedx509 depends on libtfpsacrypto. As a result, some linkers will expect flags to be in a specific order, for example the GNU linker wants `-lmbedtls -lmbedx509 -ltfpsacrypto`.
We use CMake to configure and drive our build process. Three libraries are built: `libtfpsacrypto`, `libmbedx509`, and `libmbedtls`. Note that `libmbedtls` depends on `libmbedx509` and `libtfpsacrypto`, and `libmbedx509` depends on `libtfpsacrypto`. As a result, some linkers will expect flags to be in a specific order, for example the GNU linker wants `-lmbedtls -lmbedx509 -ltfpsacrypto`. The cryptographic library `libtfpsacrypto` is also provided under its legacy name, `libmbedcrypto`.
### Tool versions
You need the following tools to build the library:
You need the following tools to build the library from the main branch with the provided CMake files. Mbed TLS minimum tool version requirements are set based on the versions shipped in the latest or penultimate (depending on the release cadence) long-term support releases of major Linux distributions, namely at time of writing: Ubuntu 22.04, RHEL 9, and SLES 15 SP4.
* CMake 3.10.2 or later.
* A build system that CMake supports.
* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, IAR 8 and Visual Studio 2017. More recent versions should work. Slightly older versions may work.
* Python 3.8 to generate the test code. Python is also needed to integrate PSA drivers and to build the development branch (see next section).
* CMake 3.20.2 or later.
* A build system like Make or Ninja for which CMake can generate build files.
* A C99 toolchain (compiler, linker, archiver). We actively test with GCC 5.4, Clang 3.8, Arm Compiler 6, and Visual Studio 2017 Compiler. More recent versions should work. Slightly older versions may work.
* Python 3.8 or later to generate the test code. Python is also needed to build the development branch (see next section).
* Perl to run the tests, and to generate some source files in the development branch.
* Doxygen 1.8.11 or later (if building the documentation; slightly older versions should work).
* Doxygen 1.8.14 or later (if building the documentation; slightly older versions should work).
### Git usage
The `development` branch and the `mbedtls-3.6` long-term support branch of Mbed TLS use a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules) ([framework](https://github.com/Mbed-TLS/mbedtls-framework)). This is not needed to merely compile the library at a release tag. This is not needed to consume a release archive (zip or tar).
The supported branches (see [`BRANCHES.md`](BRANCHES.md)) use [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules). They contain two submodules: the [framework](https://github.com/Mbed-TLS/mbedtls-framework) submodule and the [tf-psa-crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto) submodule, except for the 3.6 LTS branch, which contains only the framework submodule. Release tags also use Git submodules.
After cloning or checking out a branch or tag, run:
```
git submodule update --init --recursive
```
to initialize and update the submodules before building.
However, the official source release tarballs (e.g. [mbedtls-4.0.0.tar.bz2](https://github.com/Mbed-TLS/mbedtls/releases/download/mbedtls-4.0.0/mbedtls-4.0.0.tar.bz2)) include the contents of the submodules.
### Generated source files in the development branch
@@ -57,12 +64,12 @@ The source code of Mbed TLS includes some files that are automatically generated
The following tools are required:
* Perl, for some library source files and for Visual Studio build files.
* Python 3.8 and some Python packages, for some library source files, sample programs and test data. To install the necessary packages, run:
* Perl, for some library source files.
* Python 3 and some Python packages, for some library source files, sample programs and test data. To install the necessary packages, run:
```
python3 -m pip install --user -r scripts/basic.requirements.txt
```
Depending on your Python installation, you may need to invoke `python` instead of `python3`. To install the packages system-wide, omit the `--user` option.
Depending on your Python installation, you may need to invoke `python` instead of `python3`. To install the packages system-wide or in a virtual environment, omit the `--user` option.
* A C compiler for the host platform, for some test data.
The scripts that generate the configuration-independent files will look for a host C compiler in the following places (in order of preference):
@@ -90,14 +97,10 @@ In order to run the tests, enter:
ctest
The test suites need Python to be built and Perl to be executed. If you don't have one of these installed, you'll want to disable the test suites with:
The test suites need Python to be built. If you don't have Python installed, you'll want to disable the test suites with:
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
If you disabled the test suites, but kept the programs enabled, you can still run a much smaller set of tests with:
programs/test/selftest
To configure CMake for building shared libraries, use:
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
@@ -109,9 +112,11 @@ There are many different build types available with CMake. Most of them are avai
- `Coverage`. This generates code coverage information in addition to debug information.
- `ASan`. This instruments the code with AddressSanitizer to check for memory errors. (This includes LeakSanitizer, with recent version of gcc and clang.) (With recent version of clang, this mode also instruments the code with UndefinedSanitizer to check for undefined behaviour.)
- `ASanDbg`. Same as ASan but slower, with debug information and better stack traces.
- `MemSan`. This instruments the code with MemorySanitizer to check for uninitialised memory reads. Experimental, needs recent clang on Linux/x86\_64.
- `MemSan`. This instruments the code with MemorySanitizer to check for uninitialised memory reads.
- `MemSanDbg`. Same as MemSan but slower, with debug information, better stack traces and origin tracking.
- `Check`. This activates the compiler warnings that depend on optimization and treats all warnings as errors.
- `TSan`. This instruments the code with ThreadSanitizer to detect data races and other threading-related concurrency issues at runtime.
- `TSanDbg`. Same as TSan but slower, with debug information, better stack traces and origin tracking.
Switching build types in CMake is simple. For debug mode, enter at the command line:
@@ -130,7 +135,7 @@ for example:
CC=your_cc cmake /path/to/mbedtls_source
If you already invoked cmake and want to change those settings, you need to
remove the build directory and create it again.
invoke the configuration phase of CMake again with the new settings.
Note that it is possible to build in-place; this will however overwrite the
legacy Makefiles still used for testing purposes (see
@@ -139,7 +144,7 @@ showing them as modified). In order to do so, from the Mbed TLS source
directory, use:
cmake .
make
cmake --build .
If you want to change `CC` or `CFLAGS` afterwards, you will need to remove the
CMake cache. This can be done with the following command using GNU find:
@@ -149,25 +154,31 @@ CMake cache. This can be done with the following command using GNU find:
You can now make the desired change:
CC=your_cc cmake .
make
cmake --build .
Regarding variables, also note that if you set CFLAGS when invoking cmake,
your value of CFLAGS doesn't override the content provided by cmake (depending
your value of CFLAGS doesn't override the content provided by CMake (depending
on the build mode as seen above), it's merely prepended to it.
#### Consuming Mbed TLS
Mbed TLS provides a package config file for consumption as a dependency in other
CMake projects. You can include Mbed TLS's CMake targets yourself with:
Mbed TLS provides a CMake package configuration file for consumption as a
dependency in other CMake projects. You can load its CMake targets with:
find_package(MbedTLS)
find_package(MbedTLS REQUIRED)
If prompted, set `MbedTLS_DIR` to `${YOUR_MBEDTLS_INSTALL_DIR}/cmake`. This
creates the following targets:
You can help CMake find the package:
- `MbedTLS::tfpsacrypto` (Crypto library)
- `MbedTLS::mbedtls` (TLS library)
- `MbedTLS::mbedx509` (X509 library)
- By setting the variable `MbedTLS_DIR` to `${YOUR_MBEDTLS_BUILD_DIR}/cmake`,
as shown in `programs/test/cmake_package/CMakeLists.txt`, or
- By adding the Mbed TLS installation prefix to `CMAKE_PREFIX_PATH`,
as shown in `programs/test/cmake_package_install/CMakeLists.txt`.
After a successful `find_package(MbedTLS)`, the following imported targets are available:
- `MbedTLS::tfpsacrypto`, the crypto library
- `MbedTLS::mbedtls`, the TLS library
- `MbedTLS::mbedx509`, the X.509 library
You can then use these directly through `target_link_libraries()`:
@@ -188,14 +199,6 @@ Mbed TLS supports being built as a CMake subproject. One can
use `add_subdirectory()` from a parent CMake project to include Mbed TLS as a
subproject.
### Microsoft Visual Studio
The build files for Microsoft Visual Studio are generated for Visual Studio 2017.
The solution file `mbedTLS.sln` contains all the basic projects needed to build the library and all the programs. The files in tests are not generated and compiled, as these need Python and perl environments as well. However, the selftest program in `programs/test/` is still available.
In the development branch of Mbed TLS, the Visual Studio solution files need to be generated first as described in [“Generated source files in the development branch”](#generated-source-files-in-the-development-branch).
Example programs
----------------
@@ -205,14 +208,13 @@ Please note that the goal of these sample programs is to demonstrate specific fe
Tests
-----
Mbed TLS includes an elaborate test suite in `tests/` that initially requires Python to generate the tests files (e.g. `test\_suite\_ssl.c`). These files are generated from a `function file` (e.g. `suites/test\_suite\_ssl.function`) and a `data file` (e.g. `suites/test\_suite\_ssl.data`). The `function file` contains the test functions. The `data file` contains the test cases, specified as parameters that will be passed to the test function.
Mbed TLS includes an elaborate test suite in `tests/` that initially requires Python to generate the tests files (e.g. `test_suite_ssl.c`). These files are generated from a `function file` (e.g. `suites/test_suite_ssl.function`) and a `data file` (e.g. `suites/test_suite_ssl.data`). The `function file` contains the test functions. The `data file` contains the test cases, specified as parameters that will be passed to the test function.
For machines with a Unix shell and OpenSSL (and optionally GnuTLS) installed, additional test scripts are available:
- `tests/ssl-opt.sh` runs integration tests for various TLS options (renegotiation, resumption, etc.) and tests interoperability of these options with other implementations.
- `tests/compat.sh` tests interoperability of every ciphersuite with other implementations.
- `tests/scripts/test-ref-configs.pl` test builds in various reduced configurations.
- `tests/scripts/depends.py` test builds in configurations with a single curve, key exchange, hash, cipher, or pkalg on.
- `tests/scripts/depends.py` tests builds in configurations with a single curve, key exchange, hash, cipher, or pkalg on.
- `tests/scripts/all.sh` runs a combination of the above tests, plus some more, with various build options (such as ASan, full `mbedtls_config.h`, etc).
Instead of manually installing the required versions of all tools required for testing, it is possible to use the Docker images from our CI systems, as explained in [our testing infrastructure repository](https://github.com/Mbed-TLS/mbedtls-test/blob/main/README.md#quick-start).
@@ -236,48 +238,11 @@ Mbed TLS is mostly written in portable C99; however, it has a few platform requi
- Mixed-endian platforms are not supported.
- SIZE_MAX must be at least as big as INT_MAX and UINT_MAX.
PSA cryptography API
--------------------
### PSA API
Arm's [Platform Security Architecture (PSA)](https://developer.arm.com/architectures/security-architectures/platform-security-architecture) is a holistic set of threat models, security analyses, hardware and firmware architecture specifications, and an open source firmware reference implementation. PSA provides a recipe, based on industry best practice, that allows security to be consistently designed in, at both a hardware and firmware level.
The [PSA cryptography API](https://arm-software.github.io/psa-api/crypto/) provides access to a set of cryptographic primitives. It has a dual purpose. First, it can be used in a PSA-compliant platform to build services, such as secure boot, secure storage and secure communication. Second, it can also be used independently of other PSA components on any platform.
The design goals of the PSA cryptography API include:
* The API distinguishes caller memory from internal memory, which allows the library to be implemented in an isolated space for additional security. Library calls can be implemented as direct function calls if isolation is not desired, and as remote procedure calls if isolation is desired.
* The structure of internal data is hidden to the application, which allows substituting alternative implementations at build time or run time, for example, in order to take advantage of hardware accelerators.
* All access to the keys happens through key identifiers, which allows support for external cryptoprocessors that is transparent to applications.
* The interface to algorithms is generic, favoring algorithm agility.
* The interface is designed to be easy to use and hard to accidentally misuse.
Arm welcomes feedback on the design of the API. If you think something could be improved, please open an issue on our Github repository. Alternatively, if you prefer to provide your feedback privately, please email us at [`mbed-crypto@arm.com`](mailto:mbed-crypto@arm.com). All feedback received by email is treated confidentially.
### PSA implementation in Mbed TLS
Mbed TLS includes a reference implementation of the PSA Cryptography API.
However, it does not aim to implement the whole specification; in particular it does not implement all the algorithms.
### PSA drivers
Mbed TLS supports drivers for cryptographic accelerators, secure elements and random generators. This is work in progress. Please note that the driver interfaces are not fully stable yet and may change without notice. We intend to preserve backward compatibility for application code (using the PSA Crypto API), but the code of the drivers may have to change in future minor releases of Mbed TLS.
Please see the [PSA driver example and guide](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-driver-example-and-guide.md) for information on writing a driver.
License
-------
Unless specifically indicated otherwise in a file, Mbed TLS files are provided under a dual [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) OR [GPL-2.0-or-later](https://spdx.org/licenses/GPL-2.0-or-later.html) license. See the [LICENSE](LICENSE) file for the full text of these licenses, and [the 'License and Copyright' section in the contributing guidelines](CONTRIBUTING.md#License-and-Copyright) for more information.
### Third-party code included in Mbed TLS
This project contains code from other projects. This code is located within the `tf-psa-crypto/drivers/` directory. The original license text is included within project subdirectories, where it differs from the normal Mbed TLS license, and/or in source files. The projects are listed below:
* `drivers/everest/`: Files stem from [Project Everest](https://project-everest.github.io/) and are distributed under the Apache 2.0 license.
* `drivers/p256-m/p256-m/`: Files have been taken from the [p256-m](https://github.com/mpg/p256-m) repository. The code in the original repository is distributed under the Apache 2.0 license. It is distributed in Mbed TLS under a dual Apache-2.0 OR GPL-2.0-or-later license with permission from the author.
Contributing
------------

37
SECURITY.md
View File

@@ -37,10 +37,6 @@ being implemented. (For example Mbed TLS alone won't guarantee that the
messages will arrive without delay, as the TLS protocol doesn't guarantee that
either.)
**Warning!** Block ciphers do not yet achieve full protection against attackers
who can measure the timing of packets with sufficient precision. For details
and workarounds see the [Block Ciphers](#block-ciphers) section.
### Local attacks
In this section, we consider an attacker who can run software on the same
@@ -69,9 +65,6 @@ physical side channels as well. Remote and physical timing attacks are covered
in the [Remote attacks](remote-attacks) and [Physical
attacks](physical-attacks) sections respectively.
**Warning!** Block ciphers do not yet achieve full protection. For
details and workarounds see the [Block Ciphers](#block-ciphers) section.
#### Local non-timing side channels
The attacker code running on the platform has access to some sensor capable of
@@ -115,36 +108,6 @@ protection against a class of attacks outside of the above described threat
model. Neither does it mean that the failure of such a countermeasure is
considered a vulnerability.
#### Block ciphers
Currently there are four block ciphers in Mbed TLS: AES, CAMELLIA, ARIA and
DES. The pure software implementation in Mbed TLS implementation uses lookup
tables, which are vulnerable to timing attacks.
These timing attacks can be physical, local or depending on network latency
even a remote. The attacks can result in key recovery.
**Workarounds:**
- Turn on hardware acceleration for AES. This is supported only on selected
architectures and currently only available for AES. See configuration options
`MBEDTLS_AESCE_C`, `MBEDTLS_AESNI_C` for details.
- Add a secure alternative implementation (typically hardware acceleration) for
the vulnerable cipher. See the [Alternative Implementations
Guide](docs/architecture/alternative-implementations.md) for more information.
- Use cryptographic mechanisms that are not based on block ciphers. In
particular, for authenticated encryption, use ChaCha20/Poly1305 instead of
block cipher modes. For random generation, use HMAC\_DRBG instead of CTR\_DRBG.
#### Everest
The HACL* implementation of X25519 taken from the Everest project only protects
against remote timing attacks. (See their [Security
Policy](https://github.com/hacl-star/hacl-star/blob/main/SECURITY.md).)
The Everest variant is only used when `MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED`
configuration option is defined. This option is off by default.
#### Formatting of X.509 certificates and certificate signing requests
When parsing X.509 certificates and certificate signing requests (CSRs),

36
configs/README.txt
View File

@@ -1,24 +1,28 @@
This directory contains example configuration files.
The examples are generally focused on a particular usage case (eg, support for
a restricted number of ciphersuites) and aim at minimizing resource usage for
this target. They can be used as a basis for custom configurations.
The examples are generally focused on a particular use case (eg, support for
a restricted set of ciphersuites) and aim to minimize resource usage for
the target. They can be used as a basis for custom configurations.
These files are complete replacements for the default mbedtls_config.h. To use one of
them, you can pick one of the following methods:
These files come in pairs and are complete replacements for the default
mbedtls_config.h and crypto_config.h. The two files of a pair share the same or
very similar name, with the crypto file prefixed by "crypto-". Note
that some of the cryptography configuration files may be located in
tf-psa-crypto/configs.
1. Replace the default file include/mbedtls/mbedtls_config.h with the chosen one.
To use one of these pairs, you can pick one of the following methods:
2. Define MBEDTLS_CONFIG_FILE and adjust the include path accordingly.
For example, using make:
1. Replace the default files include/mbedtls/mbedtls_config.h and
tf-psa-crypto/include/psa/crypto_config.h with the chosen ones.
CFLAGS="-I$PWD/configs -DMBEDTLS_CONFIG_FILE='<foo.h>'" make
2. Use the MBEDTLS_CONFIG_FILE and TF_PSA_CRYPTO_CONFIG_FILE CMake options. For
example, to build out-of-tree with the config-ccm-psk-tls1_2.h and
crypto-config-ccm-psk-tls1_2.h configuration pair:
Or, using cmake:
cmake -DMBEDTLS_CONFIG_FILE="configs/config-ccm-psk-tls1_2.h" \
-DTF_PSA_CRYPTO_CONFIG_FILE="configs/crypto-config-ccm-psk-tls1_2.h"
-B build-psktls12 .
cmake --build build-psktls12
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
CFLAGS="-I$PWD/configs -DMBEDTLS_CONFIG_FILE='<foo.h>'" cmake .
make
Note that the second method also works if you want to keep your custom
configuration file outside the Mbed TLS tree.
The second method also works if you want to keep your custom configuration
files outside the Mbed TLS tree.

1039
docs/3.0-migration-guide.md
View File

File diff suppressed because it is too large Load Diff

622
docs/4.0-migration-guide.md Normal file
View File

@@ -0,0 +1,622 @@
# Migrating from Mbed TLS 3.x to Mbed TLS 4.0
This guide details the steps required to migrate from Mbed TLS version 3.x to Mbed TLS version 4.0 or greater. Unlike normal releases, Mbed TLS 4.0 breaks compatibility with previous versions, so users, integrators and package maintainers might need to change their own code in order to make it work with Mbed TLS 4.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. Here is a summary of the main points:
- Mbed TLS has been split between two products: TF-PSA-Crypto for cryptography, and Mbed TLS for X.509 and (D)TLS.
- CMake is now the only supported build system.
- The cryptography API is now mostly the PSA API: most legacy cryptography APIs have been removed. This has led to adaptations in some X.509 and TLS APIs, notably because the library always uses the PSA random generator.
- Various deprecated or minor functionality has been removed.
Please consult the [TF-PSA-Crypto migration guide](../tf-psa-crypto/docs/1.0-migration-guide.md) for all information related to the crytography part of the library.
## CMake as the only build system
Mbed TLS now uses CMake exclusively to configure and drive its build process.
Support for the GNU Make and Microsoft Visual Studio project-based build systems has been removed.
The previous `.sln` and `.vcxproj` files are no longer distributed or generated.
See the `Compiling` section in README.md for instructions on building the Mbed TLS libraries and tests with CMake.
If you develop in Microsoft Visual Studio, you could either generate a Visual Studio solution using a CMake generator, or open the CMake project directly in Visual Studio.
### Translating Make commands to CMake
With the removal of GNU Make support, all build, test, and installation operations must now be performed using CMake.
This section provides a quick reference for translating common `make` commands into their CMake equivalents.
#### Basic build workflow
Run `cmake -S . -B build` once before building to configure the build and generate native build files (e.g., Makefiles) in the `build` directory.
This sets up an out-of-tree build, which is recommended.
| Make command | CMake equivalent | Description |
|----------------|------------------------------------------------|--------------------------------------------------------------------|
| `make` | `cmake --build build` | Build the libraries, programs, and tests in the `build` directory. |
| `make test` | `ctest --test-dir build` | Run the tests produced by the previous build. |
| `make clean` | `cmake --build build --target clean` | Remove build artifacts produced by the previous build. |
| `make install` | `cmake --install build --prefix build/install` | Install the built libraries, headers, and tests to `build/install`. |
#### Building specific targets
Unless otherwise specified, the CMake command in the table below should be preceded by a `cmake -S . -B build` call to configure the build and generate build files in the `build` directory.
| Make command | CMake equivalent | Description |
|-----------------|---------------------------------------------------------------------|---------------------------|
| `make lib` | `cmake --build build --target lib` | Build only the libraries. |
| `make tests` | `cmake -S . -B build -DENABLE_PROGRAMS=Off && cmake --build build` | Build test suites. |
| `make programs` | `cmake --build build --target programs` | Build example programs. |
| `make apidoc` | `cmake --build build --target mbedtls-apidoc` | Build documentation. |
Target names may differ slightly; use `cmake --build build --target help` to list all available CMake targets.
There is no CMake equivalent for `make generated_files` or `make neat`.
Generated files are automatically created in the build tree with `cmake --build build` and removed with `cmake --build build --target clean`.
If you need to build the generated files in the source tree without involving CMake, you can call `framework/scripts/make_generated_files.py`.
There is currently no equivalent for `make uninstall` in the Mbed TLS CMake build system.
#### Common build options
The following table illustrates the approximate CMake equivalents of common make commands.
Most CMake examples show only the configuration step, others (like installation) correspond to different stages of the build process.
| Make usage | CMake usage | Description |
|----------------------------|-------------------------------------------------------|----------------------|
| `make DEBUG=1` | `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug` | Build in debug mode. |
| `make SHARED=1` | `cmake -S . -B build -DUSE_SHARED_MBEDTLS_LIBRARY=On` | Also build shared libraries. |
| `make GEN_FILES=""` | `cmake -S . -B build -DGEN_FILES=OFF` | Skip generating files (not a strict equivalent). |
| `make DESTDIR=install_dir` | `cmake --install build --prefix install_dir` | Specify installation path. |
| `make CC=clang` | `cmake -S . -B build -DCMAKE_C_COMPILER=clang` | Set the compiler. |
| `make CFLAGS='-O2 -Wall'` | `cmake -S . -B build -DCMAKE_C_FLAGS="-O2 -Wall"` | Set compiler flags. |
## Repository split
In Mbed TLS 4.0, the project was split into two repositories:
- [Mbed TLS](https://github.com/Mbed-TLS/mbedtls): provides TLS and X.509 functionality.
- [TF-PSA-Crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto): provides the standalone cryptography library, implementing the PSA Cryptography API.
Mbed TLS consumes TF-PSA-Crypto as a submodule.
You should stay with Mbed TLS if you use TLS or X.509 functionality. You still have direct access to the cryptography library.
### File and directory relocations
The following table summarizes the file and directory relocations resulting from the repository split between Mbed TLS and TF-PSA-Crypto.
These changes reflect the move of cryptographic, cryptographic-adjacent, and platform components from Mbed TLS into the new TF-PSA-Crypto repository.
| Original location | New location(s) | Notes |
|-----------------------------------------|--------------------------------------------------------------------------------------|-------|
| `library/*` (<sup>†</sup>) | `tf-psa-crypto/core/`<br>`tf-psa-crypto/drivers/builtin/src/` | Contains cryptographic, cryptographic-adjacent (e.g., ASN.1, Base64), and platform C modules and headers. |
| `include/mbedtls/*` (<sup>†</sup>) | `tf-psa-crypto/include/mbedtls/`<br>`tf-psa-crypto/drivers/builtin/include/private/` | Public headers moved to `include/mbedtls`; now internal headers moved to `include/private`. |
| `include/psa` | `tf-psa-crypto/include/psa` | All PSA headers consolidated here. |
| `3rdparty/everest`<br>`3rdparty/p256-m` | `tf-psa-crypto/drivers/everest`<br>`tf-psa-crypto/drivers/p256-m` | Third-party crypto driver implementations. |
(<sup>†</sup>) The `library` and `include/mbedtls` directories still exist in Mbed TLS, but now contain only TLS and X.509 components.
### Configuration file split
Cryptography and platform configuration options have been moved from `include/mbedtls/mbedtls_config.h` to `tf-psa-crypto/include/psa/crypto_config.h`, which is now mandatory.
See [Compile-time configuration](#compile-time-configuration).
The header `include/mbedtls/mbedtls_config.h` still exists and now contains only the TLS and X.509 configuration options.
If you use the Python script `scripts/config.py` to adjust your configuration, you do not need to modify your scripts to specify which configuration file to edit, the script automatically updates the correct file.
There have been significant changes in the configuration options, primarily affecting cryptography.
#### Cryptography configuration
- See [psa-transition.md](https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/psa-transition.md#compile-time-configuration).
- See also the following sections in the TF-PSA-Crypto 1.0 migration guide:
- *PSA as the Only Cryptography API* and its sub-section *Impact on the Library Configuration*
- *Random Number Generation Configuration*
#### TLS configuration
For details about TLS-related changes, see [Changes to TLS options](#changes-to-tls-options).
### Impact on some usages of the library
#### Checking out a branch or a tag
After checking out a branch or tag of the Mbed TLS repository, you must now recursively update the submodules, as TF-PSA-Crypto contains itself a nested submodule:
```
git submodule update --init --recursive
```
#### Linking directly to a built library
The Mbed TLS CMake build system still provides the cryptography libraries under their legacy name, `libmbedcrypto.<ext>`, so you can continue linking against them.
These libraries are still located in the `library` directory within the build tree.
The cryptography libraries are also now provided as `libtfpsacrypto.<ext>`, consistent with the naming used in the TF-PSA-Crypto repository.
You may need to update include paths to the public header files, see [File and Directory Relocations](#file-and-directory-relocations) for details.
#### Using Mbed TLS as a CMake subproject
The base name of the libraries are now `tfpsacrypto` (formely `mbedcrypto`), `mbedx509` and `mbedtls`.
As before, these base names are also the names of CMake targets to build each library.
If your CMake scripts reference a cryptography library target, you need to update its name accordingly.
For example, the following CMake code:
```
target_link_libraries(mytarget PRIVATE mbedcrypto)
```
should be updated to:
```
target_link_libraries(mytarget PRIVATE tfpsacrypto)
```
You can refer to the following example demonstrating how to consume Mbed TLS as a CMake subproject:
- `programs/test/cmake_subproject`
#### Using Mbed TLS as a CMake package
The same renaming applies to the cryptography library targets declared as part of the Mbed TLS CMake package, use `MbedTLS::tfpsacrypto` instead of `MbedTLS::mbedcrypto`.
For example, the following CMake code:
```
find_package(MbedTLS REQUIRED)
target_link_libraries(myapp PRIVATE MbedTLS::mbedcrypto)
```
should be updated to:
```
find_package(MbedTLS REQUIRED)
target_link_libraries(myapp PRIVATE MbedTLS::tfpsacrypto)
```
You can also refer to the following example programs demonstrating how to consume Mbed TLS as a CMake package:
- `programs/test/cmake_package`
- `programs/test/cmake_package_install`
#### Using the Mbed TLS Crypto pkg-config file
The Mbed TLS CMake build system still provides the pkg-config file mbedcrypto.pc, so you can continue using it.
Internally, it now references the tfpsacrypto library.
A new pkg-config file, `tfpsacrypto.pc`, is also provided.
Both `mbedcrypto.pc` and `tfpsacrypto.pc` are functionally equivalent, providing the same compiler and linker flags.
#### Using Mbed TLS as an installed library
The Mbed TLS CMake build system still installs the cryptography libraries under their legacy name, `libmbedcrypto.<ext>`, so you can continue linking against them.
The cryptography library is also now provided as `libtfpsacrypto.<ext>`.
Regarding the headers, the main change is the relocation of some headers to subdirectories called `private`.
These headers are installed primarily to satisfy compiler dependencies.
Others remain for historical reasons and may be cleaned up in later versions of the library.
We strongly recommend not relying on the declarations in these headers, as they may be removed or modified without notice.
See the section Private Declarations in the TF-PSA-Crypto 1.0 migration guide for more information.
Finally, note the new `include/tf-psa-crypto` directory, which contains the TF-PSA-Crypto version and build-time configuration headers.
### Audience-Specific Notes
#### Application Developers using a distribution package
- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on:
- Linking against the cryptography library or CMake targets.
- Using the Mbed TLS Crypto pkg-config file.
- Using Mbed TLS as an installed library
### Developer or package maintainers
If you build or distribute Mbed TLS:
- The build system is now CMake only, Makefiles and Visual Studio projects are removed.
- You may need to adapt packaging scripts to handle the TF-PSA-Crypto submodule.
- You should update submodules recursively after checkout.
- Review [File and directory relocations](#file-and-directory-relocations) for updated paths.
- See [Impact on usages of the library](#impact-on-some-usages-of-the-library) for the possible impacts on:
- Linking against the cryptography library or CMake targets.
- Using the Mbed TLS Crypto pkg-config file (`mbedcrypto.pc` or `tfpsacrypto.pc`).
- Using Mbed TLS as an installed library
- Configuration note: cryptography and platform options are now in `crypto_config.h` (see [Configuration file split](#configuration-file-split)).
### Platform Integrators
If you integrate Mbed TLS with a platform or hardware drivers:
- TF-PSA-Crypto is now a submodule, update integration scripts to initialize submodules recursively.
- The PSA driver wrapper is now generated in TF-PSA-Crypto.
- Platform-specific configuration are now handled in `crypto_config.h`.
- See [Repository split](#repository-split) for how platform components moved to TF-PSA-Crypto.
## Compile-time configuration
### Configuration file split
All configuration options that are relevant to TF-PSA-Crypto must now be configured in one of its configuration files, namely:
* `TF_PSA_CRYPTO_CONFIG_FILE`, if set on the preprocessor command line;
* otherwise `<psa/crypto_config.h>`;
* additionally `TF_PSA_CRYPTO_USER_CONFIG_FILE`, if set.
Configuration options that are relevant to X.509 or TLS should still be set in the Mbed TLS configuration file (`MBEDTLS_CONFIG_FILE` or `<mbedtls/mbedtls_config.h>`, plus `MBEDTLS_USER_CONFIG_FILE` if it is set). However, you can define all options in the crypto configuration, and Mbed TLS will pick them up.
Generally speaking, the options that must be configured in TF-PSA-Crypto are:
* options related to platform settings;
* options related to the choice of cryptographic mechanisms included in the build;
* options related to the inner workings of cryptographic mechanisms, such as size/memory/performance compromises;
* options related to crypto-adjacent features, such as ASN.1 and Base64.
See `include/psa/crypto_config.h` in TF-PSA-Crypto and `include/mbedtls/mbedtls_config.h` in Mbed TLS for details.
Notably, `<psa/crypto_config.h>` is no longer limited to `PSA_WANT_xxx` options.
Note that many options related to cryptography have changed; see the TF-PSA-Crypto migration guide for details.
### Split of `build_info.h` and `version.h`
The header file `<mbedtls/build_info.h>`, which includes the configuration file and provides the adjusted configuration macros, now has an similar file `<tf-psa-crypto/build_info.h>` in TF-PSA-Crypto. The Mbed TLS header includes the TF-PSA-Crypto header, so including `<mbedtls/build_info.h>` remains sufficient to obtain information about the crypto configuration.
TF-PSA-Crypto exposes its version through `<tf-psa-crypto/version.h>`, similar to `<mbedtls/version.h>` in Mbed TLS.
### Removal of `check_config.h`
The header `mbedtls/check_config.h` is no longer present. Including it from user configuration files was already obsolete in Mbed TLS 3.x, since it enforces properties the configuration as adjusted by `mbedtls/build_info.h`, not properties that the user configuration is expected to meet.
### Changes to TLS options
#### Enabling null cipher suites
The option to enable null cipher suites in TLS 1.2 has been renamed from `MBEDTLS_CIPHER_NULL_CIPHER` to `MBEDTLS_SSL_NULL_CIPHERSUITES`. It remains disabled in the default configuration.
#### Removal of backward compatibility options
The option `MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT` has been removed. Only the version standardized in RFC 9146 is supported now.
## PSA as the only cryptography API
The PSA API is now the only API for cryptographic primitives.
### Impact on application code
The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) 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.
A few functions take different parameters to migrate them to the PSA API. See “[Function prototype changes](#function-prototype-changes)”.
### No random generator instantiation
Formerly, applications using TLS, asymmetric cryptography operations involving a private key, or other features needing random numbers, needed to provide a random generator, generally by instantiating an entropy context (`mbedtls_entropy_context`) and a DRBG context (`mbedtls_ctr_drbg_context` or `mbedtls_hmac_drbg_context`). This is no longer necessary, or possible. All features that require a random generator (RNG) now use the one provided by the PSA subsystem.
Instead, applications that use random generators or keys (even public keys) need to call `psa_crypto_init()` before any cryptographic operation or key management operation.
See also [function prototype changes](#function-prototype-changes), many of which are related to the move from RNG callbacks to a global RNG.
### Impact on the library configuration
Mbed TLS follows the configuration of TF-PSA-Crypto with respect to cryptographic mechanisms. They are now based on `PSA_WANT_xxx` macros instead of legacy configuration macros such as `MBEDTLS_RSA_C`, `MBEDTLS_PKCS1_V15`, etc. The configuration of X.509 and TLS is not directly affected by the configuration. However, applications and middleware that rely on these configuration symbols to know which cryptographic mechanisms to support will need to migrate to `PSA_WANT_xxx` macros. For more information, consult the PSA transition guide in TF-PSA-Crypto.
## Private declarations
Since Mbed TLS 3.0, some things that are declared in a public header are not part of the stable application programming interface (API), but instead are considered private. Private elements may be removed or may have their semantics changed in a future minor release without notice.
### Understanding private declarations in public headers
In Mbed TLS 4.x, private elements in header files include:
* Anything appearing in a header file whose path contains `/private` (unless re-exported and documented in another non-private header).
* Structure and union fields declared with `MBEDTLS_PRIVATE(field_name)` in the source code, and appearing as `private_field_name` in the rendered documentation. (This was already the case since Mbed TLS 3.0.)
* Any preprocessor macro that is not documented with a Doxygen comment.
In the source code, Doxygen comments start with `/**` or `/*!`. If a macro only has a comment above that starts with `/*`, the macro is considered private.
In the rendered documentation, private macros appear with only an automatically rendered parameter list, value and location, but no custom text.
* Any declaration that is guarded by the preprocessor macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`.
### Usage of private declarations
Some private declarations are present in public headers for technical reasons, because they need to be visible to the compiler. Others are present for historical reasons and may be cleaned up in later versions of the library. We strongly recommend against relying on these declarations, since they may be removed or may have their semantics changed without notice.
Note that Mbed TLS 4.0 still relies on some private interfaces of TF-PSA-Crypto 1.0. We expect to remove this reliance gradually in future minor releases.
Sample programs have not been fully updated yet and some of them might still
use APIs that are no longer public. You can recognize them by the fact that they
define the macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` (or
`MBEDTLS_ALLOW_PRIVATE_ACCESS`) at the very top (before including headers). When
you see one of these two macros in a sample program, be aware it has not been
updated and parts of it do not demonstrate current practice.
We strongly recommend against defining `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` or
`MBEDTLS_ALLOW_PRIVATE_ACCESS` in your own application. If you do so, your code
may not compile or work with future minor releases. If there's something you
want to do that you feel can only be achieved by using one of these two macros,
please reach out on github or the mailing list.
## Error codes
### Unified error code space
The convention still applies that functions return 0 for success and a negative value between -32767 and -1 on error. PSA functions (`psa_xxx()` or `mbedtls_psa_xxx()`) still return a `PSA_ERROR_xxx` error codes. Non-PSA functions (`mbedtls_xxx()` excluding `mbedtls_psa_xxx()`) can return either `PSA_ERROR_xxx` or `MBEDTLS_ERR_xxx` error codes.
There may be cases where an `MBEDTLS_ERR_xxx` constant has the same numerical value as a `PSA_ERROR_xxx`. In such cases, they have the same meaning: they are different names for the same error condition.
### Simplified legacy error codes
All values returned by a function to indicate an error now have a defined constant named `MBEDTLS_ERR_xxx` or `PSA_ERROR_xxx`. Functions no longer return the sum of a “low-level” and a “high-level” error code.
Generally, functions that used to return the sum of two error codes now return the low-level code. However, as before, the exact error code returned in a given scenario can change without notice unless the condition is specifically described in the function's documentation and no other condition is applicable.
As a consequence, the functions `mbedtls_low_level_strerr()` and `mbedtls_high_level_strerr()` no longer exist.
### Removed error code names
Many legacy error codes have been removed in favor of PSA error codes. Generally, functions that returned a legacy error code in the table below in Mbed TLS 3.6 now return the PSA error code listed on the same row. Similarly, callbacks should apply the same changes to error code, unless there has been a relevant change to the callback's interface.
| Legacy constant (Mbed TLS 3.6) | PSA constant (Mbed TLS 4.0) |
|-----------------------------------------|---------------------------------|
| `MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED` | `PSA_ERROR_CORRUPTION_DETECTED` |
| `MBEDTLS_ERR_ERROR_GENERIC_ERROR` | `PSA_ERROR_GENERIC_ERROR` |
| `MBEDTLS_ERR_NET_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` |
| `MBEDTLS_ERR_OID_BUF_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` |
| `MBEDTLS_ERR_OID_NOT_FOUND` | `PSA_ERROR_NOT_SUPPORTED` |
| `MBEDTLS_ERR_PKCS7_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` |
| `MBEDTLS_ERR_PKCS7_BAD_INPUT_DATA` | `PSA_ERROR_INVALID_ARGUMENT` |
| `MBEDTLS_ERR_PKCS7_VERIFY_FAIL` | `PSA_ERROR_INVALID_SIGNATURE` |
| `MBEDTLS_ERR_SSL_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` |
| `MBEDTLS_ERR_SSL_BAD_INPUT_DATA` | `PSA_ERROR_INVALID_ARGUMENT` |
| `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` |
| `MBEDTLS_ERR_X509_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` |
| `MBEDTLS_ERR_X509_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` |
See also the corresponding section in the TF-PSA-Crypto migration guide, which lists error codes from cryptography modules.
## Removal of deprecated functions
### Removal of deprecated X.509 functions
The deprecated function `mbedtls_x509write_crt_set_serial()` has been removed. The function was superseded by `mbedtls_x509write_crt_set_serial_raw()`.
### Removal of deprecated SSL functions
The deprecated function `mbedtls_ssl_conf_curves()` has been removed.
The function was superseded by `mbedtls_ssl_conf_groups()`.
### Removal of `compat-2.x.h`
The header `compat-2.x.h`, containing some definitions for backward compatibility with Mbed TLS 2.x, has been removed.
## Removed features
### Removal of obsolete key exchanges methods in (D)TLS 1.2
Mbed TLS 4.0 no longer supports key exchange methods that rely on finite-field Diffie-Hellman (DHE) in TLS 1.2 and DTLS 1.2. (Only ephemeral Diffie-Hellman was ever supported, Mbed TLS 3.x already did not support static Diffie-Hellman.) Finite-field Diffie-Hellman remains supported in TLS 1.3.
Mbed TLS 4.0 no longer supports key exchange methods that rely on RSA decryption (without forward secrecy). RSA signatures remain supported. This affects TLS 1.2 and DTLS 1.2 (TLS 1.3 does not have key exchanges using RSA decryption).
That is, the following key exchange types are no longer supported:
* RSA-PSK;
* RSA (i.e. cipher suites using only RSA decryption: cipher suites using RSA signatures remain supported);
* DHE-PSK (except in TLS 1.3);
* DHE-RSA (except in TLS 1.3).
* static ECDH (ECDH-RSA and ECDH-ECDSA, as opposed to ephemeral ECDH (ECDHE) which remains supported).
The full list of removed cipher suites is:
```
TLS-DHE-PSK-WITH-AES-128-CBC-SHA
TLS-DHE-PSK-WITH-AES-128-CBC-SHA256
TLS-DHE-PSK-WITH-AES-128-CCM
TLS-DHE-PSK-WITH-AES-128-CCM-8
TLS-DHE-PSK-WITH-AES-128-GCM-SHA256
TLS-DHE-PSK-WITH-AES-256-CBC-SHA
TLS-DHE-PSK-WITH-AES-256-CBC-SHA384
TLS-DHE-PSK-WITH-AES-256-CCM
TLS-DHE-PSK-WITH-AES-256-CCM-8
TLS-DHE-PSK-WITH-AES-256-GCM-SHA384
TLS-DHE-PSK-WITH-ARIA-128-CBC-SHA256
TLS-DHE-PSK-WITH-ARIA-128-GCM-SHA256
TLS-DHE-PSK-WITH-ARIA-256-CBC-SHA384
TLS-DHE-PSK-WITH-ARIA-256-GCM-SHA384
TLS-DHE-PSK-WITH-CAMELLIA-128-CBC-SHA256
TLS-DHE-PSK-WITH-CAMELLIA-128-GCM-SHA256
TLS-DHE-PSK-WITH-CAMELLIA-256-CBC-SHA384
TLS-DHE-PSK-WITH-CAMELLIA-256-GCM-SHA384
TLS-DHE-PSK-WITH-CHACHA20-POLY1305-SHA256
TLS-DHE-PSK-WITH-NULL-SHA
TLS-DHE-PSK-WITH-NULL-SHA256
TLS-DHE-PSK-WITH-NULL-SHA384
TLS-DHE-RSA-WITH-AES-128-CBC-SHA
TLS-DHE-RSA-WITH-AES-128-CBC-SHA256
TLS-DHE-RSA-WITH-AES-128-CCM
TLS-DHE-RSA-WITH-AES-128-CCM-8
TLS-DHE-RSA-WITH-AES-128-GCM-SHA256
TLS-DHE-RSA-WITH-AES-256-CBC-SHA
TLS-DHE-RSA-WITH-AES-256-CBC-SHA256
TLS-DHE-RSA-WITH-AES-256-CCM
TLS-DHE-RSA-WITH-AES-256-CCM-8
TLS-DHE-RSA-WITH-AES-256-GCM-SHA384
TLS-DHE-RSA-WITH-ARIA-128-CBC-SHA256
TLS-DHE-RSA-WITH-ARIA-128-GCM-SHA256
TLS-DHE-RSA-WITH-ARIA-256-CBC-SHA384
TLS-DHE-RSA-WITH-ARIA-256-GCM-SHA384
TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA
TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-DHE-RSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA
TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA256
TLS-DHE-RSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-DHE-RSA-WITH-CHACHA20-POLY1305-SHA256
TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA
TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA256
TLS-ECDH-ECDSA-WITH-AES-128-GCM-SHA256
TLS-ECDH-ECDSA-WITH-AES-256-CBC-SHA
TLS-ECDH-ECDSA-WITH-AES-256-CBC-SHA384
TLS-ECDH-ECDSA-WITH-AES-256-GCM-SHA384
TLS-ECDH-ECDSA-WITH-ARIA-128-CBC-SHA256
TLS-ECDH-ECDSA-WITH-ARIA-128-GCM-SHA256
TLS-ECDH-ECDSA-WITH-ARIA-256-CBC-SHA384
TLS-ECDH-ECDSA-WITH-ARIA-256-GCM-SHA384
TLS-ECDH-ECDSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-ECDH-ECDSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-ECDH-ECDSA-WITH-CAMELLIA-256-CBC-SHA384
TLS-ECDH-ECDSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-ECDH-ECDSA-WITH-NULL-SHA
TLS-ECDH-RSA-WITH-AES-128-CBC-SHA
TLS-ECDH-RSA-WITH-AES-128-CBC-SHA256
TLS-ECDH-RSA-WITH-AES-128-GCM-SHA256
TLS-ECDH-RSA-WITH-AES-256-CBC-SHA
TLS-ECDH-RSA-WITH-AES-256-CBC-SHA384
TLS-ECDH-RSA-WITH-AES-256-GCM-SHA384
TLS-ECDH-RSA-WITH-ARIA-128-CBC-SHA256
TLS-ECDH-RSA-WITH-ARIA-128-GCM-SHA256
TLS-ECDH-RSA-WITH-ARIA-256-CBC-SHA384
TLS-ECDH-RSA-WITH-ARIA-256-GCM-SHA384
TLS-ECDH-RSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-ECDH-RSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-ECDH-RSA-WITH-CAMELLIA-256-CBC-SHA384
TLS-ECDH-RSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-ECDH-RSA-WITH-NULL-SHA
TLS-RSA-PSK-WITH-AES-128-CBC-SHA
TLS-RSA-PSK-WITH-AES-128-CBC-SHA256
TLS-RSA-PSK-WITH-AES-128-GCM-SHA256
TLS-RSA-PSK-WITH-AES-256-CBC-SHA
TLS-RSA-PSK-WITH-AES-256-CBC-SHA384
TLS-RSA-PSK-WITH-AES-256-GCM-SHA384
TLS-RSA-PSK-WITH-ARIA-128-CBC-SHA256
TLS-RSA-PSK-WITH-ARIA-128-GCM-SHA256
TLS-RSA-PSK-WITH-ARIA-256-CBC-SHA384
TLS-RSA-PSK-WITH-ARIA-256-GCM-SHA384
TLS-RSA-PSK-WITH-CAMELLIA-128-CBC-SHA256
TLS-RSA-PSK-WITH-CAMELLIA-128-GCM-SHA256
TLS-RSA-PSK-WITH-CAMELLIA-256-CBC-SHA384
TLS-RSA-PSK-WITH-CAMELLIA-256-GCM-SHA384
TLS-RSA-PSK-WITH-CHACHA20-POLY1305-SHA256
TLS-RSA-PSK-WITH-NULL-SHA
TLS-RSA-PSK-WITH-NULL-SHA256
TLS-RSA-PSK-WITH-NULL-SHA384
TLS-RSA-WITH-AES-128-CBC-SHA
TLS-RSA-WITH-AES-128-CBC-SHA256
TLS-RSA-WITH-AES-128-CCM
TLS-RSA-WITH-AES-128-CCM-8
TLS-RSA-WITH-AES-128-GCM-SHA256
TLS-RSA-WITH-AES-256-CBC-SHA
TLS-RSA-WITH-AES-256-CBC-SHA256
TLS-RSA-WITH-AES-256-CCM
TLS-RSA-WITH-AES-256-CCM-8
TLS-RSA-WITH-AES-256-GCM-SHA384
TLS-RSA-WITH-ARIA-128-CBC-SHA256
TLS-RSA-WITH-ARIA-128-GCM-SHA256
TLS-RSA-WITH-ARIA-256-CBC-SHA384
TLS-RSA-WITH-ARIA-256-GCM-SHA384
TLS-RSA-WITH-CAMELLIA-128-CBC-SHA
TLS-RSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-RSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-RSA-WITH-CAMELLIA-256-CBC-SHA
TLS-RSA-WITH-CAMELLIA-256-CBC-SHA256
TLS-RSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-RSA-WITH-NULL-MD5
TLS-RSA-WITH-NULL-SHA
TLS-RSA-WITH-NULL-SHA256
```
As a consequence of the removal of support for DHE in (D)TLS 1.2, the following functions are no longer useful and have been removed:
```
mbedtls_ssl_conf_dh_param_bin()
mbedtls_ssl_conf_dh_param_ctx()
mbedtls_ssl_conf_dhm_min_bitlen()
```
### Removal of elliptic curves
Following their removal from the crypto library, elliptic curves of less than 250 bits (secp192r1, secp192k1, secp224r1, secp224k1) are no longer supported in certificates and in TLS.
### Removal of deprecated functions
The deprecated functions `mbedtls_ssl_conf_min_version()` and `mbedtls_ssl_conf_max_version()`, and the associated constants `MBEDTLS_SSL_MAJOR_VERSION_3`, `MBEDTLS_SSL_MINOR_VERSION_3` and `MBEDTLS_SSL_MINOR_VERSION_4` have been removed. Use `mbedtls_ssl_conf_min_tls_version()` and `mbedtls_ssl_conf_max_tls_version()` with `MBEDTLS_SSL_VERSION_TLS1_2` or `MBEDTLS_SSL_VERSION_TLS1_3` instead.
The deprecated function `mbedtls_ssl_conf_sig_hashes()` has been removed. Use `mbedtls_ssl_conf_sig_algs()` instead.
## Function prototype changes
A number of existing functions now take a different list of arguments, mostly to migrate them to the PSA API.
### Public functions no longer take a RNG callback
Functions that need randomness no longer take an RNG callback in the form of `f_rng, p_rng` arguments. Instead, they use the PSA Crypto random generator (accessible as `psa_generate_random()`). All software using the X.509 or SSL modules must call `psa_crypto_init()` before calling any of the functions listed here.
### RNG removal in X.509
The following function prototypes have been changed in `mbedtls/x509_crt.h`:
```c
int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);
int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);
```
The following function prototypes have been changed in `mbedtls/x509_csr.h`:
```c
int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);
int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);
```
### RNG removal in SSL
The following function prototype has been changed in `mbedtls/ssl_cookie.h`:
```c
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx);
```
### Removal of `mbedtls_ssl_conf_rng`
`mbedtls_ssl_conf_rng()` has been removed from the library. Its sole purpose was to configure the RNG used for TLS, but now the PSA Crypto random generator is used throughout the library.
### Changes to mbedtls_ssl_ticket_setup
In the arguments of the function `mbedtls_ssl_ticket_setup()`, the `mbedtls_cipher_type_t` argument specifying the AEAD mechanism for ticket protection has been replaced by an equivalent PSA description consisting of a key type, a size and an algorithm. Also, the function no longer takes RNG arguments.
The prototype in `mbedtls/ssl_ticket.h` has changed from
```c
int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
mbedtls_f_rng_t *f_rng, void *p_rng,
mbedtls_cipher_type_t cipher,
uint32_t lifetime);
```
to
```c
int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits,
uint32_t lifetime);
```
## OID module
The compilation option `MBEDTLS_OID_C` no longer exists. OID tables are included in the build automatically as needed for parsing and writing X.509 data.
Mbed TLS no longer offers interfaces to look up values by OID or OID by enum values (`mbedtls_oid_get_<thing>()` and `mbedtls_oid_get_oid_by_<thing>()`).
The header `<mbedtls/oid.h>` now only provides functions to convert between binary and dotted string OID representations. These functions are now part of `libmbedx509` rather than the crypto library. The function `mbedtls_oid_get_numeric_string()` is guarded by `MBEDTLS_X509_USE_C`, and `mbedtls_oid_from_numeric_string()` by `MBEDTLS_X509_CREATE_C`. The header also still defines macros for OID strings that are relevant to X.509.

44
docs/4.0-migration-guide/configuration.md
View File

@@ -1,44 +0,0 @@
## Compile-time configuration
### Configuration file split
All configuration options that are relevant to TF-PSA-Crypto must now be configured in one of its configuration files, namely:
* `TF_PSA_CRYPTO_CONFIG_FILE`, if set on the preprocessor command line;
* otherwise `<psa/crypto_config.h>`;
* additionally `TF_PSA_CRYPTO_USER_CONFIG_FILE`, if set.
Configuration options that are relevant to X.509 or TLS should still be set in the Mbed TLS configuration file (`MBEDTLS_CONFIG_FILE` or `<mbedtls/mbedtls_config.h>`, plus `MBEDTLS_USER_CONFIG_FILE` if it is set). However, you can define all options in the crypto configuration, and Mbed TLS will pick them up.
Generally speaking, the options that must be configured in TF-PSA-Crypto are:
* options related to platform settings;
* options related to the choice of cryptographic mechanisms included in the build;
* options related to the inner workings of cryptographic mechanisms, such as size/memory/performance compromises;
* options related to crypto-adjacent features, such as ASN.1 and Base64.
See `include/psa/crypto_config.h` in TF-PSA-Crypto and `include/mbedtls/mbedtls_config.h` in Mbed TLS for details.
Notably, `<psa/crypto_config.h>` is no longer limited to `PSA_WANT_xxx` options.
Note that many options related to cryptography have changed; see the TF-PSA-Crypto migration guide for details.
### Split of `build_info.h` and `version.h`
The header file `<mbedtls/build_info.h>`, which includes the configuration file and provides the adjusted configuration macros, now has an similar file `<tf-psa-crypto/build_info.h>` in TF-PSA-Crypto. The Mbed TLS header includes the TF-PSA-Crypto header, so including `<mbedtls/build_info.h>` remains sufficient to obtain information about the crypto configuration.
TF-PSA-Crypto exposes its version through `<tf-psa-crypto/version.h>`, similar to `<mbedtls/version.h>` in Mbed TLS.
### Removal of `check_config.h`
The header `mbedtls/check_config.h` is no longer present. Including it from user configuration files was already obsolete in Mbed TLS 3.x, since it enforces properties the configuration as adjusted by `mbedtls/build_info.h`, not properties that the user configuration is expected to meet.
### Changes to TLS options
#### Enabling null cipher suites
The option to enable null cipher suites in TLS 1.2 has been renamed from `MBEDTLS_CIPHER_NULL_CIPHER` to `MBEDTLS_SSL_NULL_CIPHERSUITES`. It remains disabled in the default configuration.
#### Removal of backward compatibility options
The option `MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT` has been removed. Only the version standardized in RFC 9146 is supported now.

14
docs/4.0-migration-guide/deprecated-removals.md
View File

@@ -1,14 +0,0 @@
## Removal of deprecated functions
### Removal of deprecated X.509 functions
The deprecated function `mbedtls_x509write_crt_set_serial()` has been removed. The function was superseded by `mbedtls_x509write_crt_set_serial_raw()`.
### Removal of deprecated SSL functions
The deprecated function `mbedtls_ssl_conf_curves()` has been removed.
The function was superseded by `mbedtls_ssl_conf_groups()`.
### Removal of `compat-2.x.h`
The header `compat-2.x.h`, containing some definitions for backward compatibility with Mbed TLS 2.x, has been removed.

37
docs/4.0-migration-guide/error-codes.md
View File

@@ -1,37 +0,0 @@
## Error codes
### Unified error code space
The convention still applies that functions return 0 for success and a negative value between -32767 and -1 on error. PSA functions (`psa_xxx()` or `mbedtls_psa_xxx()`) still return a `PSA_ERROR_xxx` error codes. Non-PSA functions (`mbedtls_xxx()` excluding `mbedtls_psa_xxx()`) can return either `PSA_ERROR_xxx` or `MBEDTLS_ERR_xxx` error codes.
There may be cases where an `MBEDTLS_ERR_xxx` constant has the same numerical value as a `PSA_ERROR_xxx`. In such cases, they have the same meaning: they are different names for the same error condition.
### Simplified legacy error codes
All values returned by a function to indicate an error now have a defined constant named `MBEDTLS_ERR_xxx` or `PSA_ERROR_xxx`. Functions no longer return the sum of a “low-level” and a “high-level” error code.
Generally, functions that used to return the sum of two error codes now return the low-level code. However, as before, the exact error code returned in a given scenario can change without notice unless the condition is specifically described in the function's documentation and no other condition is applicable.
As a consequence, the functions `mbedtls_low_level_strerr()` and `mbedtls_high_level_strerr()` no longer exist.
### Removed error code names
Many legacy error codes have been removed in favor of PSA error codes. Generally, functions that returned a legacy error code in the table below in Mbed TLS 3.6 now return the PSA error code listed on the same row. Similarly, callbacks should apply the same changes to error code, unless there has been a relevant change to the callback's interface.
| Legacy constant (Mbed TLS 3.6) | PSA constant (Mbed TLS 4.0) |
|-----------------------------------------|---------------------------------|
| `MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED` | `PSA_ERROR_CORRUPTION_DETECTED` |
| `MBEDTLS_ERR_ERROR_GENERIC_ERROR` | `PSA_ERROR_GENERIC_ERROR` |
| `MBEDTLS_ERR_NET_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` |
| `MBEDTLS_ERR_OID_BUF_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` |
| `MBEDTLS_ERR_OID_NOT_FOUND` | `PSA_ERROR_NOT_SUPPORTED` |
| `MBEDTLS_ERR_PKCS7_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` |
| `MBEDTLS_ERR_PKCS7_BAD_INPUT_DATA` | `PSA_ERROR_INVALID_ARGUMENT` |
| `MBEDTLS_ERR_PKCS7_VERIFY_FAIL` | `PSA_ERROR_INVALID_SIGNATURE` |
| `MBEDTLS_ERR_SSL_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` |
| `MBEDTLS_ERR_SSL_BAD_INPUT_DATA` | `PSA_ERROR_INVALID_ARGUMENT` |
| `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` |
| `MBEDTLS_ERR_X509_ALLOC_FAILED` | `PSA_ERROR_INSUFFICIENT_MEMORY` |
| `MBEDTLS_ERR_X509_BUFFER_TOO_SMALL` | `PSA_ERROR_BUFFER_TOO_SMALL` |
See also the corresponding section in the TF-PSA-Crypto migration guide, which lists error codes from cryptography modules.

152
docs/4.0-migration-guide/feature-removals.md
View File

@@ -1,152 +0,0 @@
## Removed features
### Removal of obsolete key exchanges methods in (D)TLS 1.2
Mbed TLS 4.0 no longer supports key exchange methods that rely on finite-field Diffie-Hellman (DHE) in TLS 1.2 and DTLS 1.2. (Only ephemeral Diffie-Hellman was ever supported, Mbed TLS 3.x already did not support static Diffie-Hellman.) Finite-field Diffie-Hellman remains supported in TLS 1.3.
Mbed TLS 4.0 no longer supports key exchange methods that rely on RSA decryption (without forward secrecy). RSA signatures remain supported. This affects TLS 1.2 and DTLS 1.2 (TLS 1.3 does not have key exchanges using RSA decryption).
That is, the following key exchange types are no longer supported:
* RSA-PSK;
* RSA (i.e. cipher suites using only RSA decryption: cipher suites using RSA signatures remain supported);
* DHE-PSK (except in TLS 1.3);
* DHE-RSA (except in TLS 1.3).
* static ECDH (ECDH-RSA and ECDH-ECDSA, as opposed to ephemeral ECDH (ECDHE) which remains supported).
The full list of removed cipher suites is:
```
TLS-DHE-PSK-WITH-AES-128-CBC-SHA
TLS-DHE-PSK-WITH-AES-128-CBC-SHA256
TLS-DHE-PSK-WITH-AES-128-CCM
TLS-DHE-PSK-WITH-AES-128-CCM-8
TLS-DHE-PSK-WITH-AES-128-GCM-SHA256
TLS-DHE-PSK-WITH-AES-256-CBC-SHA
TLS-DHE-PSK-WITH-AES-256-CBC-SHA384
TLS-DHE-PSK-WITH-AES-256-CCM
TLS-DHE-PSK-WITH-AES-256-CCM-8
TLS-DHE-PSK-WITH-AES-256-GCM-SHA384
TLS-DHE-PSK-WITH-ARIA-128-CBC-SHA256
TLS-DHE-PSK-WITH-ARIA-128-GCM-SHA256
TLS-DHE-PSK-WITH-ARIA-256-CBC-SHA384
TLS-DHE-PSK-WITH-ARIA-256-GCM-SHA384
TLS-DHE-PSK-WITH-CAMELLIA-128-CBC-SHA256
TLS-DHE-PSK-WITH-CAMELLIA-128-GCM-SHA256
TLS-DHE-PSK-WITH-CAMELLIA-256-CBC-SHA384
TLS-DHE-PSK-WITH-CAMELLIA-256-GCM-SHA384
TLS-DHE-PSK-WITH-CHACHA20-POLY1305-SHA256
TLS-DHE-PSK-WITH-NULL-SHA
TLS-DHE-PSK-WITH-NULL-SHA256
TLS-DHE-PSK-WITH-NULL-SHA384
TLS-DHE-RSA-WITH-AES-128-CBC-SHA
TLS-DHE-RSA-WITH-AES-128-CBC-SHA256
TLS-DHE-RSA-WITH-AES-128-CCM
TLS-DHE-RSA-WITH-AES-128-CCM-8
TLS-DHE-RSA-WITH-AES-128-GCM-SHA256
TLS-DHE-RSA-WITH-AES-256-CBC-SHA
TLS-DHE-RSA-WITH-AES-256-CBC-SHA256
TLS-DHE-RSA-WITH-AES-256-CCM
TLS-DHE-RSA-WITH-AES-256-CCM-8
TLS-DHE-RSA-WITH-AES-256-GCM-SHA384
TLS-DHE-RSA-WITH-ARIA-128-CBC-SHA256
TLS-DHE-RSA-WITH-ARIA-128-GCM-SHA256
TLS-DHE-RSA-WITH-ARIA-256-CBC-SHA384
TLS-DHE-RSA-WITH-ARIA-256-GCM-SHA384
TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA
TLS-DHE-RSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-DHE-RSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA
TLS-DHE-RSA-WITH-CAMELLIA-256-CBC-SHA256
TLS-DHE-RSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-DHE-RSA-WITH-CHACHA20-POLY1305-SHA256
TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA
TLS-ECDH-ECDSA-WITH-AES-128-CBC-SHA256
TLS-ECDH-ECDSA-WITH-AES-128-GCM-SHA256
TLS-ECDH-ECDSA-WITH-AES-256-CBC-SHA
TLS-ECDH-ECDSA-WITH-AES-256-CBC-SHA384
TLS-ECDH-ECDSA-WITH-AES-256-GCM-SHA384
TLS-ECDH-ECDSA-WITH-ARIA-128-CBC-SHA256
TLS-ECDH-ECDSA-WITH-ARIA-128-GCM-SHA256
TLS-ECDH-ECDSA-WITH-ARIA-256-CBC-SHA384
TLS-ECDH-ECDSA-WITH-ARIA-256-GCM-SHA384
TLS-ECDH-ECDSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-ECDH-ECDSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-ECDH-ECDSA-WITH-CAMELLIA-256-CBC-SHA384
TLS-ECDH-ECDSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-ECDH-ECDSA-WITH-NULL-SHA
TLS-ECDH-RSA-WITH-AES-128-CBC-SHA
TLS-ECDH-RSA-WITH-AES-128-CBC-SHA256
TLS-ECDH-RSA-WITH-AES-128-GCM-SHA256
TLS-ECDH-RSA-WITH-AES-256-CBC-SHA
TLS-ECDH-RSA-WITH-AES-256-CBC-SHA384
TLS-ECDH-RSA-WITH-AES-256-GCM-SHA384
TLS-ECDH-RSA-WITH-ARIA-128-CBC-SHA256
TLS-ECDH-RSA-WITH-ARIA-128-GCM-SHA256
TLS-ECDH-RSA-WITH-ARIA-256-CBC-SHA384
TLS-ECDH-RSA-WITH-ARIA-256-GCM-SHA384
TLS-ECDH-RSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-ECDH-RSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-ECDH-RSA-WITH-CAMELLIA-256-CBC-SHA384
TLS-ECDH-RSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-ECDH-RSA-WITH-NULL-SHA
TLS-RSA-PSK-WITH-AES-128-CBC-SHA
TLS-RSA-PSK-WITH-AES-128-CBC-SHA256
TLS-RSA-PSK-WITH-AES-128-GCM-SHA256
TLS-RSA-PSK-WITH-AES-256-CBC-SHA
TLS-RSA-PSK-WITH-AES-256-CBC-SHA384
TLS-RSA-PSK-WITH-AES-256-GCM-SHA384
TLS-RSA-PSK-WITH-ARIA-128-CBC-SHA256
TLS-RSA-PSK-WITH-ARIA-128-GCM-SHA256
TLS-RSA-PSK-WITH-ARIA-256-CBC-SHA384
TLS-RSA-PSK-WITH-ARIA-256-GCM-SHA384
TLS-RSA-PSK-WITH-CAMELLIA-128-CBC-SHA256
TLS-RSA-PSK-WITH-CAMELLIA-128-GCM-SHA256
TLS-RSA-PSK-WITH-CAMELLIA-256-CBC-SHA384
TLS-RSA-PSK-WITH-CAMELLIA-256-GCM-SHA384
TLS-RSA-PSK-WITH-CHACHA20-POLY1305-SHA256
TLS-RSA-PSK-WITH-NULL-SHA
TLS-RSA-PSK-WITH-NULL-SHA256
TLS-RSA-PSK-WITH-NULL-SHA384
TLS-RSA-WITH-AES-128-CBC-SHA
TLS-RSA-WITH-AES-128-CBC-SHA256
TLS-RSA-WITH-AES-128-CCM
TLS-RSA-WITH-AES-128-CCM-8
TLS-RSA-WITH-AES-128-GCM-SHA256
TLS-RSA-WITH-AES-256-CBC-SHA
TLS-RSA-WITH-AES-256-CBC-SHA256
TLS-RSA-WITH-AES-256-CCM
TLS-RSA-WITH-AES-256-CCM-8
TLS-RSA-WITH-AES-256-GCM-SHA384
TLS-RSA-WITH-ARIA-128-CBC-SHA256
TLS-RSA-WITH-ARIA-128-GCM-SHA256
TLS-RSA-WITH-ARIA-256-CBC-SHA384
TLS-RSA-WITH-ARIA-256-GCM-SHA384
TLS-RSA-WITH-CAMELLIA-128-CBC-SHA
TLS-RSA-WITH-CAMELLIA-128-CBC-SHA256
TLS-RSA-WITH-CAMELLIA-128-GCM-SHA256
TLS-RSA-WITH-CAMELLIA-256-CBC-SHA
TLS-RSA-WITH-CAMELLIA-256-CBC-SHA256
TLS-RSA-WITH-CAMELLIA-256-GCM-SHA384
TLS-RSA-WITH-NULL-MD5
TLS-RSA-WITH-NULL-SHA
TLS-RSA-WITH-NULL-SHA256
```
As a consequence of the removal of support for DHE in (D)TLS 1.2, the following functions are no longer useful and have been removed:
```
mbedtls_ssl_conf_dh_param_bin()
mbedtls_ssl_conf_dh_param_ctx()
mbedtls_ssl_conf_dhm_min_bitlen()
```
### Removal of elliptic curves
Following their removal from the crypto library, elliptic curves of less than 250 bits (secp192r1, secp192k1, secp224r1, secp224k1) are no longer supported in certificates and in TLS.
### Removal of deprecated functions
The deprecated functions `mbedtls_ssl_conf_min_version()` and `mbedtls_ssl_conf_max_version()`, and the associated constants `MBEDTLS_SSL_MAJOR_VERSION_3`, `MBEDTLS_SSL_MINOR_VERSION_3` and `MBEDTLS_SSL_MINOR_VERSION_4` have been removed. Use `mbedtls_ssl_conf_min_tls_version()` and `mbedtls_ssl_conf_max_tls_version()` with `MBEDTLS_SSL_VERSION_TLS1_2` or `MBEDTLS_SSL_VERSION_TLS1_3` instead.
The deprecated function `mbedtls_ssl_conf_sig_hashes()` has been removed. Use `mbedtls_ssl_conf_sig_algs()` instead.

89
docs/4.0-migration-guide/function-prototype-changes.md
View File

@@ -1,89 +0,0 @@
## Function prototype changes
A number of existing functions now take a different list of arguments, mostly to migrate them to the PSA API.
### Public functions no longer take a RNG callback
Functions that need randomness no longer take an RNG callback in the form of `f_rng, p_rng` arguments. Instead, they use the PSA Crypto random generator (accessible as `psa_generate_random()`). All software using the X.509 or SSL modules must call `psa_crypto_init()` before calling any of the functions listed here.
### RNG removal in X.509
The following function prototypes have been changed in `mbedtls/x509_crt.h`:
```c
int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_x509write_crt_der(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);
int mbedtls_x509write_crt_pem(mbedtls_x509write_cert *ctx, unsigned char *buf, size_t size);
```
The following function prototypes have been changed in `mbedtls/x509_csr.h`:
```c
int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_x509write_csr_der(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);
int mbedtls_x509write_csr_pem(mbedtls_x509write_csr *ctx, unsigned char *buf, size_t size);
```
### RNG removal in SSL
The following function prototype has been changed in `mbedtls/ssl_cookie.h`:
```c
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng);
```
to
```c
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx);
```
### Removal of `mbedtls_ssl_conf_rng`
`mbedtls_ssl_conf_rng()` has been removed from the library. Its sole purpose was to configure the RNG used for TLS, but now the PSA Crypto random generator is used throughout the library.
### Changes to mbedtls_ssl_ticket_setup
In the arguments of the function `mbedtls_ssl_ticket_setup()`, the `mbedtls_cipher_type_t` argument specifying the AEAD mechanism for ticket protection has been replaced by an equivalent PSA description consisting of a key type, a size and an algorithm. Also, the function no longer takes RNG arguments.
The prototype in `mbedtls/ssl_ticket.h` has changed from
```c
int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
mbedtls_f_rng_t *f_rng, void *p_rng,
mbedtls_cipher_type_t cipher,
uint32_t lifetime);
```
to
```c
int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx,
psa_algorithm_t alg, psa_key_type_t key_type, psa_key_bits_t key_bits,
uint32_t lifetime);
```

7
docs/4.0-migration-guide/oid.md
View File

@@ -1,7 +0,0 @@
## OID module
The compilation option `MBEDTLS_OID_C` no longer exists. OID tables are included in the build automatically as needed for parsing and writing X.509 data.
Mbed TLS no longer offers interfaces to look up values by OID or OID by enum values (`mbedtls_oid_get_<thing>()` and `mbedtls_oid_get_oid_by_<thing>()`).
The header `<mbedtls/oid.h>` now only provides functions to convert between binary and dotted string OID representations. These functions are now part of `libmbedx509` rather than the crypto library. The function `mbedtls_oid_get_numeric_string()` is guarded by `MBEDTLS_X509_USE_C`, and `mbedtls_oid_from_numeric_string()` by `MBEDTLS_X509_CREATE_C`. The header also still defines macros for OID strings that are relevant to X.509.

33
docs/4.0-migration-guide/private-decls.md
View File

@@ -1,33 +0,0 @@
## Private declarations
Since Mbed TLS 3.0, some things that are declared in a public header are not part of the stable application programming interface (API), but instead are considered private. Private elements may be removed or may have their semantics changed in a future minor release without notice.
### Understanding private declarations in public headers
In Mbed TLS 4.x, private elements in header files include:
* Anything appearing in a header file whose path contains `/private` (unless re-exported and documented in another non-private header).
* Structure and union fields declared with `MBEDTLS_PRIVATE(field_name)` in the source code, and appearing as `private_field_name` in the rendered documentation. (This was already the case since Mbed TLS 3.0.)
* Any preprocessor macro that is not documented with a Doxygen comment.
In the source code, Doxygen comments start with `/**` or `/*!`. If a macro only has a comment above that starts with `/*`, the macro is considered private.
In the rendered documentation, private macros appear with only an automatically rendered parameter list, value and location, but no custom text.
* Any declaration that is guarded by the preprocessor macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`.
### Usage of private declarations
Some private declarations are present in public headers for technical reasons, because they need to be visible to the compiler. Others are present for historical reasons and may be cleaned up in later versions of the library. We strongly recommend against relying on these declarations, since they may be removed or may have their semantics changed without notice.
Note that Mbed TLS 4.0 still relies on some private interfaces of TF-PSA-Crypto 1.0. We expect to remove this reliance gradually in future minor releases.
Sample programs have not been fully updated yet and some of them might still
use APIs that are no longer public. You can recognize them by the fact that they
define the macro `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` (or
`MBEDTLS_ALLOW_PRIVATE_ACCESS`) at the very top (before including headers). When
you see one of these two macros in a sample program, be aware it has not been
updated and parts of it do not demonstrate current practice.
We strongly recommend against defining `MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS` or
`MBEDTLS_ALLOW_PRIVATE_ACCESS` in your own application. If you do so, your code
may not compile or work with future minor releases. If there's something you
want to do that you feel can only be achieved by using one of these two macros,
please reach out on github or the mailing list.

23
docs/4.0-migration-guide/psa-only.md
View File

@@ -1,23 +0,0 @@
## PSA as the only cryptography API
The PSA API is now the only API for cryptographic primitives.
### Impact on application code
The X.509, PKCS7 and SSL modules always use PSA for cryptography, with a few exceptions documented in the [PSA limitations](../architecture/psa-migration/psa-limitations.md) document. (These limitations are mostly transparent unless you want to leverage PSA accelerator drivers.) 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.
A few functions take different parameters to migrate them to the PSA API. See “[Function prototype changes](#function-prototype-changes)”.
### No random generator instantiation
Formerly, applications using TLS, asymmetric cryptography operations involving a private key, or other features needing random numbers, needed to provide a random generator, generally by instantiating an entropy context (`mbedtls_entropy_context`) and a DRBG context (`mbedtls_ctr_drbg_context` or `mbedtls_hmac_drbg_context`). This is no longer necessary, or possible. All features that require a random generator (RNG) now use the one provided by the PSA subsystem.
Instead, applications that use random generators or keys (even public keys) need to call `psa_crypto_init()` before any cryptographic operation or key management operation.
See also [function prototype changes](#function-prototype-changes), many of which are related to the move from RNG callbacks to a global RNG.
### Impact on the library configuration
Mbed TLS follows the configuration of TF-PSA-Crypto with respect to cryptographic mechanisms. They are now based on `PSA_WANT_xxx` macros instead of legacy configuration macros such as `MBEDTLS_RSA_C`, `MBEDTLS_PKCS1_V15`, etc. The configuration of X.509 and TLS is not directly affected by the configuration. However, applications and middleware that rely on these configuration symbols to know which cryptographic mechanisms to support will need to migrate to `PSA_WANT_xxx` macros. For more information, consult the PSA transition guide in TF-PSA-Crypto.

2
doxygen/input/doc_mainpage.h
View File

@@ -10,7 +10,7 @@
*/
/**
* @mainpage Mbed TLS v4.0.0-beta API Documentation
* @mainpage Mbed TLS v4.0.0 API Documentation
*
* This documentation describes the application programming interface (API)
* of Mbed TLS.

2
doxygen/mbedtls.doxyfile
View File

@@ -1,4 +1,4 @@
PROJECT_NAME = "Mbed TLS v4.0.0-beta"
PROJECT_NAME = "Mbed TLS v4.0.0"
OUTPUT_DIRECTORY = ../apidoc/
FULL_PATH_NAMES = NO
OPTIMIZE_OUTPUT_FOR_C = YES

2
framework

Submodule framework updated: d80c4f9ec3...4579964747

3
tests/scripts/components-configuration-crypto.sh
View File

@@ -831,7 +831,8 @@ common_test_psa_crypto_config_accel_ecc_some_curves () {
ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
helper_libtestdriver1_make_drivers "$loc_accel_list" "$loc_extra_list"
helper_libtestdriver1_make_main "$loc_accel_list"
# For grep to work below we need less inlining in ecp.c
ASAN_CFLAGS="$ASAN_CFLAGS -O0" helper_libtestdriver1_make_main "$loc_accel_list"
# We expect ECDH to be re-enabled for the missing curves
grep mbedtls_ecdh_ ${BUILTIN_SRC_PATH}/ecdh.o

2
tf-psa-crypto

Submodule tf-psa-crypto updated: cf4c26de94...76920edddc