4.0 Migration Guide
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 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: provides TLS and X.509 functionality.
- 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.
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.
- 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.
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 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 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 for updated paths.
- See Impact on 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).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 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 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”.
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, 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 (orMBEDTLS_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 orMBEDTLS_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:
/ Detailed source-code truncated for AI context efficiency. /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:
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
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:
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
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:
int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx,
int (f_rng)(void , unsigned char *, size_t),
void *p_rng);to
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
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
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.
---
Index
.. Mbed TLS Versioned documentation master file, created by
sphinx-quickstart on Thu Feb 23 18:13:44 2023.
You can adapt this file completely to your liking, but it should at least
contain the root toctree directive.
Mbed TLS API documentation
==========================
.. doxygenpage:: index
:project: mbedtls-versioned
.. toctree::
:caption: Contents
:maxdepth: 1
Home <self>
api/grouplist.rst
api/filelist.rst
api/structlist.rst
api/unionlist.rst
---
Tls13 Early Data
Writing early data
------------------
An application function to write and send a buffer of data to a server through
TLS may plausibly look like:
int write_data(mbedtls_ssl_context *ssl,
const unsigned char *data_to_write,
size_t data_to_write_len,
size_t *data_written)
{
int ret;
*data_written = 0; while (*data_written < data_to_write_len) {
ret = mbedtls_ssl_write(ssl, data_to_write + *data_written,
data_to_write_len - *data_written);
if (ret < 0 &&
ret != MBEDTLS_ERR_SSL_WANT_READ &&
ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
return ret;
}
*data_written += ret;
}
return 0;
}
where ssl is the SSL context to use, data_to_write the address of the data
buffer and data_to_write_len the number of data bytes. The handshake may
not be completed, not even started for the SSL context ssl when the function is
called and in that case the mbedtls_ssl_write() API takes care transparently of
completing the handshake before to write and send data to the server. The
mbedtls_ssl_write() may not be able to write and send all data in one go thus
the need for a loop calling it as long as there are still data to write and
send.
An application function to write and send early data and only early data,
data sent during the first flight of client messages while the handshake is in
its initial phase, would look completely similar but the call to
mbedtls_ssl_write_early_data() instead of mbedtls_ssl_write().
int write_early_data(mbedtls_ssl_context *ssl,
const unsigned char *data_to_write,
size_t data_to_write_len,
size_t *data_written)
{
int ret;
*data_written = 0; while (*data_written < data_to_write_len) {
ret = mbedtls_ssl_write_early_data(ssl, data_to_write + *data_written,
data_to_write_len - *data_written);
if (ret < 0 &&
ret != MBEDTLS_ERR_SSL_WANT_READ &&
ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
return ret;
}
*data_written += ret;
}
return 0;
}
Note that compared to write_data(), write_early_data() can also return
MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA and that should be handled
specifically by the user of write_early_data(). A fresh SSL context (typically
just after a call to mbedtls_ssl_setup() or mbedtls_ssl_session_reset()) would
be expected when calling
write_early_data.All together, code to write and send a buffer of data as long as possible as
early data and then as standard post-handshake application data could
plausibly look like:
ret = write_early_data(ssl,
data_to_write,
data_to_write_len,
&early_data_written);
if (ret < 0 &&
ret != MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA) {
goto error;
}ret = write_data(ssl,
data_to_write + early_data_written,
data_to_write_len - early_data_written,
&data_written);
if (ret < 0) {
goto error;
}
data_written += early_data_written;
Finally, taking into account that the server may reject early data, application
code to write and send a buffer of data could plausibly look like:
ret = write_early_data(ssl,
data_to_write,
data_to_write_len,
&early_data_written);
if (ret < 0 &&
ret != MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA) {
goto error;
}/*
* Make sure the handshake is completed as it is a requisite of
* mbedtls_ssl_get_early_data_status().
*/
while (!mbedtls_ssl_is_handshake_over(ssl)) {
ret = mbedtls_ssl_handshake(ssl);
if (ret < 0 &&
ret != MBEDTLS_ERR_SSL_WANT_READ &&
ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
goto error;
}
}
ret = mbedtls_ssl_get_early_data_status(ssl);
if (ret < 0) {
goto error;
}
if (ret == MBEDTLS_SSL_EARLY_DATA_STATUS_REJECTED) {
early_data_written = 0;
}
ret = write_data(ssl,
data_to_write + early_data_written,
data_to_write_len - early_data_written,
&data_written);
if (ret < 0) {
goto error;
}
data_written += early_data_written;
Reading early data
------------------
Mbed TLS provides the mbedtls_ssl_read_early_data() API to read the early data
that a TLS 1.3 server might receive during the TLS 1.3 handshake.
While establishing a TLS 1.3 connection with a client using a combination
of the mbedtls_ssl_handshake(), mbedtls_ssl_read() and mbedtls_ssl_write() APIs,
the reception of early data is signaled by an API returning the
MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA error code. Early data can then be read
with the mbedtls_ssl_read_early_data() API.
For example, a typical code to establish a TLS connection, where ssl is the SSL
context to use:
while ((int ret = mbedtls_ssl_handshake(&ssl)) != 0) { if (ret < 0 &&
ret != MBEDTLS_ERR_SSL_WANT_READ &&
ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
break;
}
}
could be adapted to handle early data in the following way:
size_t data_read_len = 0;
while ((ret = mbedtls_ssl_handshake(&ssl)) != 0) { if (ret == MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA) {
ret = mbedtls_ssl_read_early_data(&ssl,
buffer + data_read_len,
sizeof(buffer) - data_read_len);
if (ret < 0) {
break;
}
data_read_len += ret;
continue;
}
if (ret < 0 &&
ret != MBEDTLS_ERR_SSL_WANT_READ &&
ret != MBEDTLS_ERR_SSL_WANT_WRITE) {
break;
}
}
---
CONTRIBUTING
Contributing
============
We gratefully accept bug reports and contributions from the community. All PRs are reviewed by the project team / community, and may need some modifications to
be accepted.
Quick Checklist for PR contributors
-----------------------------------
More details on all of these points may be found in the sections below.
- Sign-off: all commits must be signed off.
- Tests: please ensure the PR includes adequate tests.
- Changelog: if needed, please provide a changelog entry.
- Backports: provide a backport if needed (it's fine to wait until the main PR is accepted).
Coding Standards
----------------
- Contributions should include tests, as mentioned in the Tests and Continuous Integration sections. Please check that your contribution passes basic tests before submission, and check the CI results after making a pull request.
- The code should be written in a clean and readable style, and must follow our coding standards.
- The code should be written in a portable generic way, that will benefit the whole community, and not only your own needs.
- The code should be secure, and will be reviewed from a security point of view as well.
Making a Contribution
---------------------
1. Check for open issues or start a discussion around a feature idea or a bug.
1. Fork the Mbed TLS repository on GitHub to start making your changes. As a general rule, you should use the "development" branch as a basis.
1. Write a test which shows that the bug was fixed or that the feature works as expected.
1. Send a pull request (PR) and work with us until it gets merged and published. Contributions may need some modifications, so a few rounds of review and fixing may be necessary. See our review process guidelines.
1. For quick merging, the contribution should be short, and concentrated on a single feature or topic. The larger the contribution is, the longer it would take to review it and merge it.
Backwards Compatibility
-----------------------
The project aims to minimise the impact on users upgrading to newer versions of the library and it should not be necessary for a user to make any changes to their own code to work with a newer version of the library. Unless the user has made an active decision to use newer features, a newer generation of the library or a change has been necessary due to a security issue or other significant software defect, no modifications to their own code should be necessary. To achieve this, API compatibility is maintained between different versions of Mbed TLS on the main development branch and in LTS (Long Term Support) branches, as described in BRANCHES.md.
To minimise such disruption to users, where a change to the interface is required, all changes to the ABI or API, even on the main development branch where new features are added, need to be justifiable by either being a significant enhancement, new feature or bug fix which is best resolved by an interface change. If there is an API change, the contribution, if accepted, will be merged only when there is a major release.
No changes are permitted to the definition of functions in the public interface which will change the API. Instead the interface can only be changed by its extension. Where changes to an existing interface are necessary, functions in the public interface which need to be changed are marked as 'deprecated'. If there is a strong reason to replace an existing function with one that has a slightly different interface (different prototype, or different documented behavior), create a new function with a new name with the desired interface. Keep the old function, but mark it as deprecated.
Periodically, the library will remove deprecated functions from the library which will be a breaking change in the API, but such changes will be made only in a planned, structured way that gives sufficient notice to users of the library.
Long Term Support Branches
--------------------------
Mbed TLS maintains several LTS (Long Term Support) branches, which are maintained continuously for a given period. The LTS branches are provided to allow users of the library to have a maintained, stable version of the library which contains only security fixes and fixes for other defects, without encountering additional features or API extensions which may introduce issues or change the code size or RAM usage, which can be significant considerations on some platforms. To allow users to take advantage of the LTS branches, these branches maintain backwards compatibility for both the public API and ABI.
When backporting to these branches please observe the following rules:
1. Any change to the library which changes the API or ABI cannot be backported.
1. All bug fixes that correct a defect that is also present in an LTS branch must be backported to that LTS branch. If a bug fix introduces a change to the API such as a new function, the fix should be reworked to avoid the API change. API changes without very strong justification are unlikely to be accepted.
1. If a contribution is a new feature or enhancement, no backporting is required. Exceptions to this may be additional test cases or quality improvements such as changes to build or test scripts.
It would be highly appreciated if contributions are backported to LTS branches in addition to the development branch by contributors.
The list of maintained branches can be found in the Current Branches section
of BRANCHES.md.
Tests
-----
As mentioned, tests that show the correctness of the feature or bug fix should be added to the pull request, if no such tests exist.
Mbed TLS includes a comprehensive set of test suites in the tests/ directory that are dynamically generated to produce the actual test source 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.
A Knowledge Base article describing how to add additional tests is available on the Mbed TLS website.
A test script tests/scripts/basic-build-test.sh is available to show test coverage of the library. New code contributions should provide a similar level of code coverage to that which already exists for the library.
Sample applications, if needed, should be modified as well.
Continuous Integration Tests
----------------------------
Once a PR has been made, the Continuous Integration (CI) tests are triggered and run. You should follow the result of the CI tests, and fix failures.
It is advised to enable the githooks scripts prior to pushing your changes, for catching some of the issues as early as possible.
Documentation
-------------
Mbed TLS is well documented, but if you think documentation is needed, speak out!
1. All interfaces should be documented through Doxygen. New APIs should introduce Doxygen documentation.
1. Complex parts in the code should include comments.
1. If needed, a Readme file is advised.
1. If a Knowledge Base (KB) article should be added, write this as a comment in the PR description.
1. A ChangeLog entry should be added for this contribution.
License and Copyright
---------------------
Unless specifically indicated otherwise in a file, Mbed TLS files are provided under a dual Apache-2.0 OR GPL-2.0-or-later license. See the LICENSE file for the full text of these licenses. This means that users may choose which of these licenses they take the code under.
Contributors must accept that their contributions are made under both the Apache-2.0 AND GPL-2.0-or-later licenses.
All new files should include the standard SPDX license identifier where possible, i.e. "SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later".
The copyright on contributions is retained by the original authors of the code. Where possible for new files, this should be noted in a comment at the top of the file in the form: "Copyright The Mbed TLS Contributors".
When contributing code to us, the committer and all authors are required to make the submission under the terms of the Developer Certificate of Origin, confirming that the code submitted can (legally) become part of the project, and is submitted under both the Apache-2.0 AND GPL-2.0-or-later licenses.
This is done by including the standard Git Signed-off-by: line in every commit message. If more than one person contributed to the commit, they should also add their own Signed-off-by: line.
---
SECURITY
Reporting Vulnerabilities
If you think you have found an Mbed TLS security vulnerability, then please
send an email to the security team at
<[email protected]>.
Security Incident Handling Process
Our security process is detailed in our
security
center.
Its primary goal is to ensure fixes are ready to be deployed when the issue
goes public.
Maintained branches
Only the maintained branches, as listed in BRANCHES.md,
get security fixes.
Users are urged to always use the latest version of a maintained branch.
Use of TF-PSA-Crypto
Note that Mbed TLS uses the cryptography API provided by TF-PSA-Crypto.
Its
threat model
applies to all cryptographic operations performed by Mbed TLS. In particular,
users of Mbed TLS should note the considerations around
block ciphers
since they apply to the block ciphers used in TLS.
Threat model
We classify attacks based on the capabilities of the attacker.
Remote attacks
In this section, we consider an attacker who can observe and modify data sent
over the network. This includes observing the content and timing of individual
packets, as well as suppressing or delaying legitimate messages, and injecting
messages.
Mbed TLS aims to fully protect against remote attacks and to enable the user
application in providing full protection against remote attacks. Said
protection is limited to providing security guarantees offered by the protocol
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.)
Local attacks
In this section, we consider an attacker who can run software on the same
machine. The attacker has insufficient privileges to directly access Mbed TLS
assets such as memory and files.
#### Timing attacks
The attacker is able to observe the timing of instructions executed by Mbed TLS
by leveraging shared hardware that both Mbed TLS and the attacker have access
to. Typical attack vectors include cache timings, memory bus contention and
branch prediction.
Mbed TLS provides limited protection against timing attacks. The cost of
protecting against timing attacks widely varies depending on the granularity of
the measurements and the noise present. Therefore the protection in Mbed TLS is
limited. We are only aiming to provide protection against publicly
documented attack techniques.
As attacks keep improving, so does Mbed TLS's protection. Mbed TLS is moving
towards a model of fully timing-invariant code, but has not reached this point
yet.
Remark: Timing information can be observed over the network or through
physical side channels as well. Remote and physical timing attacks are covered
in the Remote attacks and Physical
attacks sections respectively.
#### Local non-timing side channels
The attacker code running on the platform has access to some sensor capable of
picking up information on the physical state of the hardware while Mbed TLS is
running. This could for example be an analogue-to-digital converter on the
platform that is located unfortunately enough to pick up the CPU noise.
Mbed TLS doesn't make any security guarantees against local non-timing-based
side channel attacks. If local non-timing attacks are present in a use case or
a user application's threat model, they need to be mitigated by the platform.
#### Local fault injection attacks
Software running on the same hardware can affect the physical state of the
device and introduce faults.
Mbed TLS doesn't make any security guarantees against local fault injection
attacks. If local fault injection attacks are present in a use case or a user
application's threat model, they need to be mitigated by the platform.
Physical attacks
In this section, we consider an attacker who has access to physical information
about the hardware Mbed TLS is running on and/or can alter the physical state
of the hardware (e.g. power analysis, radio emissions or fault injection).
Mbed TLS doesn't make any security guarantees against physical attacks. If
physical attacks are present in a use case or a user application's threat
model, they need to be mitigated by physical countermeasures.
Caveats
#### Out-of-scope countermeasures
Mbed TLS has evolved organically and a well defined threat model hasn't always
been present. Therefore, Mbed TLS might have countermeasures against attacks
outside the above defined threat model.
The presence of such countermeasures don't mean that Mbed TLS provides
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.
#### Formatting of X509 data
This section discusses limitations in how X.509 objects are processed. This
applies to certificates, certificate signing requests (CSRs) and certificate
revocation lists (CRLs).
Mbed TLS does not check that they are strictly compliant with X.509 and other
relevant standards. In the case of signed certificates and signed CRLs, the
signing party is assumed to have performed this validation (and the certificate
or CRL is trusted to be correctly formatted as long as the signature is
correct). Similarly, CSRs are implicitly trusted by Mbed TLS to be
standards-compliant.
Warning! Mbed TLS must not be used to sign untrusted CSRs or CRLs unless
extra validation is performed separately to ensure that they are compliant to
the relevant specifications. This makes Mbed TLS on its own unsuitable for use
in a Certificate Authority (CA).
However, Mbed TLS aims to protect against memory corruption and other
undefined behavior when parsing certificates, CSRs and CRLs. If a CSR or signed
certificate causes undefined behavior when it is parsed by Mbed TLS, that
is considered a security vulnerability.
---