DOCSEARCHbyAlgolia
Submit Docs

Mbed TLS Documentation

repository·development·Indexed 27 days ago

https://github.com/mbed-tls/mbedtls

A lightweight C library providing X.509 certificate manipulation and TLS/DTLS protocols, optimized for embedded systems. It includes the PSA Cryptography API via the TF-PSA-Crypto component. The documentation covers building with CMake, configuration via header files or Python, API/ABI compatibility, and the use of sample applications for SSL/TLS and X.509 certificate management.

Tokens
11.6K
Snippets
19
Records
61
Agent score
90%

What's inside Mbed TLS

  1. Understand the Mbed TLS configuration split

    development

    Mbed TLS uses a split configuration model to separate TLS/X.509 logic from cryptographic logic. This allows the cryptography component to be managed via the tf-psa-crypto repository.

    • mbedtls_config.h: Configures TLS and X.509 features.
    • tf_psa_crypto_config.h: Configures the cryptography interface (PSA API) and cryptographic mechanisms.

    Options relevant to both (such as platform or system settings) are located in tf_psa_crypto_config.h to avoid duplication.

  2. Understand PSA Crypto API limitations for TLS and X.509

    development

    The PSA Crypto API (as of version 1.1) has several limitations that affect its use in TLS and X.509, specifically regarding performing crypto operations (G1) and isolating long-term secrets (G2). Key areas of limitation include:

    • Interruptible ECC operations: While ECDSA sign/verify support was added in Mbed TLS 3.4, interruptible ECDH is not yet supported. This can cause issues in TLS 1.2 clients using ECDHE-ECDSA when MBEDTLS_ECP_RESTARTABLE is enabled.
    • FFDH Support: The PSA API for Finite Field Diffie-Hellman (FFDH) is not yet implemented in Mbed TLS. Additionally, the PSA API currently only supports a limited set of well-known FFDH parameters, which conflicts with TLS 1.2's ability to use arbitrary parameters.
    • RSA-PSS Parameters: There are discrepancies in how salt length and hash algorithms are handled between the legacy Mbed TLS APIs and the PSA API, which impacts X.509 and TLS 1.3 compatibility.

  3. Migrate from Mbed TLS 3.x to 4.0

    development

    Mbed TLS 4.0 introduces breaking changes that require code updates for users, integrators, and package maintainers.

    Key Changes:

    • Product Split: The library is now split into two products: TF-PSA-Crypto (for cryptography) and Mbed TLS (for X.509 and (D)TLS).
    • Build System: CMake is now the only supported build system. GNU Make and Microsoft Visual Studio project-based builds are no longer supported.
    • Cryptography API: Most legacy cryptography APIs have been removed in favor of the PSA API. This affects X.509 and TLS APIs because the library now uses the PSA random generator.
    • Functionality: Various deprecated or minor functionalities have been removed.

    Action Required: If your project relies on cryptography functions, consult the TF-PSA-Crypto migration guide for specific details.

  4. Generate corpus for network traffic fuzz targets

    development

    Network traffic targets (client, server, dtls_client, and dtls_server) use network traffic as inputs and utilize the last bytes of the input as configuration options. To generate a corpus:

    1. Build the ssl_server2 and ssl_client2 programs.
    2. Run them against each other with the reproducible option enabled, capturing the traffic into a .pcap file.
    3. Extract TCP payloads using a tool like tshark: tshark -Tfields -e tcp.dstport -e tcp.payload -r test.pcap > test.txt
    4. Process the extracted payloads into a corpus file (e.g., test.cor) using a script.
    5. Append configuration options as the last bytes to the resulting corpus file.

  6. Migrate to PSA as the only cryptography API in Mbed TLS 4.0

    development

    In Mbed TLS 4.0, the PSA API is the exclusive API for cryptographic primitives. The MBEDTLS_USE_PSA_CRYPTO configuration is now always enabled.

    Key Changes:

    • Initialization: You must call psa_crypto_init() before performing any cryptographic operation, including parsing keys/certificates or starting a TLS handshake.
    • Random Number Generation (RNG): Applications no longer need to manually instantiate entropy (mbedtls_entropy_context) or DRBG contexts (mbedtls_ctr_drbg_context or mbedtls_hmac_drbg_context). All features requiring an RNG now use the global PSA subsystem.
    • Configuration: Cryptographic mechanisms are now configured using PSA_WANT_xxx macros instead of legacy macros like MBEDTLS_RSA_C or MBEDTLS_PKCS1_V15. Applications or middleware relying on legacy symbols for feature detection must migrate to the PSA_WANT_xxx macros.

  7. RSA-PSS compatibility in X.509 and TLS

    development

    X.509 Usage

    In Mbed TLS, X.509 parsing enforces specific RSA-PSS properties:

    • The trailer field must be the default value.
    • The mask generation function (MGF) must be MGF1.
    • The encoding hash must equal the message hashing algorithm.

    Cryptographic operations in X.509 (verifying certificate signatures or CRL signatures) are performed using mbedtls_pk_verify_ext().

    TLS Usage

    • TLS 1.2: RSA-PSS is not used directly in the protocol, only via X.509.
    • TLS 1.3: RSA-PSS is used directly. The protocol requires:
      • MGF1 as the mask generation function.
      • All three hashes (message, encoding, and MGF1) to be equal.
      • The salt length to be equal to the length of the digest algorithm.

    PSA Crypto is compatible with TLS 1.3 requirements, as it picks the required salt length during signing and enforces it during verification.

  8. Update CMake targets for Mbed TLS 4.0

    development

    The base name for the cryptography library target has changed from mbedcrypto to tfpsacrypto. If your CMake scripts reference the cryptography library target, you must update the name.

    As a CMake subproject: Change mbedcrypto to tfpsacrypto in target_link_libraries.

    As a CMake package: Use MbedTLS::tfpsacrypto instead of MbedTLS::mbedcrypto.

    # If using as a subproject
target_link_libraries(mytarget PRIVATE tfpsacrypto)

# If using find_package(MbedTLS)
find_package(MbedTLS REQUIRED)
target_link_libraries(myapp PRIVATE MbedTLS::tfpsacrypto)

  9. Select a maintained Mbed TLS branch

    development

    Mbed TLS provides several branch types depending on your need for the latest features or long-term stability:

    • main: Contains the latest release and all current security fixes.
    • development: Used for preparing the next minor version of Mbed TLS 4.x. Includes new features, bug fixes, and security fixes.
    • Long-Term Support (LTS) branches: Receive only bug fixes and security fixes.
      • mbedtls-3.6: Supported until March 2027.
      • mbedtls-4.1: Supported until March 2029.
    • archive/ branches: Historical branches (e.g., archive/mbedtls-2.7) that do not receive updates.

    Recommendation: Users should always use the latest version of a maintained branch.

  10. Explore Mbed TLS SSL/TLS sample applications

    development

    Mbed TLS provides several sample applications to demonstrate SSL/TLS implementation. Use these as starting points for your own applications, but note that they are not guaranteed to be production-ready or secure without separate auditing.

    Common Client/Server Examples:

    • ssl/ssl_client1.c: A simple HTTPS client that sends a fixed request and displays the response. Recommended as a base for typical TLS clients.
    • ssl/ssl_server.c: A simple HTTPS server that serves a single client at a time with a fixed response.
    • ssl/dtls_client.c & ssl/dtls_server.c: Simple DTLS (Datagram TLS) client and server programs for datagram-based communication.
    • ssl/ssl_mail_client.c: An SMTP-over-TLS or SMTP-STARTTLS client for sending email.

    Concurrency Models:

    • ssl/ssl_fork_server.c: An HTTPS server using one process per client (requires Unix/POSIX fork).
    • ssl/ssl_pthread_server.c: An HTTPS server using one thread per client (requires pthread library).

  12. Run fuzz targets without OSS-Fuzz

    development

    To run fuzz targets locally, you must install a fuzzing engine (e.g., libFuzzer) and compile the code using the compiler flags for your chosen sanitizer. You can use the address sanitizer or undefined sanitizer.

    perl scripts/config.py set MBEDTLS_PLATFORM_TIME_ALT
mkdir build
cd build
cmake ..
make
# Run the target
./test/fuzz/fuzz_client