Hubbry Logo
Mbed TLSMbed TLSMain
Open search
Mbed TLS
Community hub
Mbed TLS
logo
7 pages, 0 posts
0 subscribers
Be the first to start a discussion here.
Be the first to start a discussion here.
Mbed TLS
Mbed TLS
Mbed TLS
View on Wikipedia
from Wikipedia
Mbed TLS
DeveloperCollaborative project managed by TrustedFirmware (formerly by Arm)
Initial releaseJanuary 15, 2009 (2009-01-15)
Stable release4.0.0[1]Edit this on Wikidata (15 October 2025; 12 days ago (15 October 2025)) [±]
Repository
Written inC
Operating systemMulti-platform
TypeSecurity library
LicenseDual Apache-2.0 or GPL-2.0-or-later
Websitewww.trustedfirmware.org/projects/mbed-tls/

Mbed TLS (previously PolarSSL) is an implementation of the TLS and SSL protocols and the respective cryptographic algorithms and support code required. It is distributed under the Apache License version 2.0. Stated on the website is that Mbed TLS aims to be "easy to understand, use, integrate and expand".

History

[edit]

The PolarSSL SSL library is the official continuation fork of the XySSL SSL library. XySSL was created by the French "white hat hacker" Christophe Devine and was first released on November 1, 2006, under GNU GPL v2 and BSD licenses. In 2008, Christophe Devine was no longer able to support XySSL and allowed Paul Bakker to create the official fork, named PolarSSL.[2] In November 2014, PolarSSL was acquired by ARM Holdings.[3]

In 2011, the Dutch government approved an integration between OpenVPN and PolarSSL, which is named OpenVPN-NL. This version of OpenVPN has been approved for use in protecting government communications up to the level of Restricted.[4]

As of the release of version 1.3.10, PolarSSL has been rebranded to Mbed TLS to better show its fit inside the Mbed ecosystem.[5] Starting from version 2.1.0, the library was made available under both the GPL v2 and Apache License v2.0.[6]

In 2020, Mbed TLS joined the TrustedFirmware project.[7]

Library

[edit]

The core SSL library is written in the C programming language and implements the SSL module, the basic cryptographic functions and provides various utility functions. Unlike OpenSSL and other implementations of TLS, Mbed TLS is like wolfSSL in that it is designed to fit on small embedded devices, with the minimum complete TLS stack requiring under 60KB of program space and under 64 KB of RAM. It is also highly modular: each component, such as a cryptographic function, can be used independently from the rest of the framework. Versions are also available for Microsoft Windows and Linux. Because Mbed TLS is written in the C programming language, without external dependencies, it works on most operating systems and architectures.

Since version 1.3.0, it has abstraction layers for memory allocation and threading to the core "to support better integration with existing embedded operating systems".[8]

Design priorities

[edit]

The Mbed TLS library expresses a focus on readability of the code, documentation, automated regression tests, a loosely coupled design and portable code.[9]

Development documentation

[edit]

The following documentation is available for developers:

  • High Level Design:[10] a high level description of the different modules inside the library, with UML diagrams, use cases and interactions in common scenarios.
  • API documentation:[11] Doxygen-generated documentation from the header files of the library.
  • Source code documentation:[12] The source code of the library is documented to clarify structures, decisions and code constructs.

Automated testing

[edit]

The automated testing of Mbed TLS includes:

  • A test framework is included with the source code that contains over 5000 automated tests (based on the number of tests in version 1.3.2 of the library) to test for regressions and compatibility on different platforms.
  • A compatibility script (compat.sh[13]) that tests compatibility of SSL communication with OpenSSL and GnuTLS.
  • A continuous integration system based on Travis CI and Jenkins.[14]

Use

[edit]

Mbed TLS is used as the SSL component in large open source projects:

Platforms

[edit]

Mbed TLS is currently available for most Operating Systems including Linux, Microsoft Windows, OS X, OpenWrt, Android, iOS, RISC OS[15] and FreeRTOS. Chipsets supported at least include ARM, x86, PowerPC, MIPS.

Algorithms

[edit]

Mbed TLS supports a number of different cryptographic algorithms:

Cryptographic hash functions
MD2, MD4, MD5, RIPEMD160, SHA-1, SHA-2, SHA-3
MAC modes
CMAC, HMAC
Ciphers
AES, ARIA, Blowfish, Camellia, ChaCha, DES, RC4, Triple DES, XTEA
Cipher modes
ECB, CBC, CFB, CTR, OFB, XTS
Authenticated encryption modes
CCM, GCM, NIST Key Wrap,
ChaCha20-Poly1305
Key derivation
HKDF
Key stretching
PBKDF2, PKCS #5 PBE2, PKCS #12 key derivation
Public-key cryptography
RSA, Diffie–Hellman key exchange,
Elliptic curve cryptography (ECC), Elliptic curve Diffie–Hellman (ECDH), Elliptic Curve DSA (ECDSA), Elliptic curve J-PAKE

See also

[edit]

References

[edit]
[edit]
Revisions and contributorsEdit on WikipediaRead on Wikipedia

Mbed TLS

View on Grokipedia
from Grokipedia
Mbed TLS is an open-source, portable library that implements cryptographic primitives, certificate manipulation, and the TLS and DTLS protocols, with a small code footprint making it particularly suitable for resource-constrained embedded systems. Originally developed as PolarSSL by the Dutch company Offspark, the library was acquired by in February 2015 to bolster security in its mbed IoT platform, leading to its rebranding as mbed TLS and integration into mbed OS for securing communications from device edge to cloud. Distributed under a dual license of Apache 2.0 or GPL 2.0-or-later, mbed TLS emphasizes ease of understanding, integration, and extension, supporting features like configurable modules via header files and a of the PSA for hardware-accelerated cryptography. Notable for its active maintenance by the Trusted Firmware Project, it receives regular releases—every 3 to 6 months—with the latest stable version 4.0.0 issued in October 2025 introducing major consolidations and vulnerability fixes, while the 3.6 branch provides until at least March 2027. Widely adopted in secure IoT, firmware, and operating system projects such as TF-A, TF-M, and OP-TEE, mbed TLS enables developers to build robust SSL/TLS clients and servers with minimal overhead.

History

Origins and PolarSSL Era

Mbed TLS originated from XySSL, an open-source cryptographic library developed by French security researcher Christophe Devine beginning in 2006. XySSL provided implementations of core cryptographic primitives, including symmetric and asymmetric algorithms, hashing functions, and basic SSL/TLS support, all under the BSD 3-clause license, making it suitable for embedded and resource-limited environments. The library's design emphasized portability across platforms and a minimal code footprint, reflecting Devine's background in wireless security tools like . In January 2009, Paul Bakker launched PolarSSL as the direct successor to XySSL, migrating and refactoring the codebase to enhance modularity and SSL/TLS functionality. PolarSSL adopted a dual-licensing model under the GNU GPL v2 or later and a license, allowing both open-source and commercial use while maintaining a compact structure—comprising just 17 source files and around 100 KB in size. Key additions during this transition included support for ciphers like and , as well as improved certificate handling, positioning it as a lightweight alternative to heavier libraries like for IoT and embedded applications. The PolarSSL era, spanning 2009 to 2015, saw the library's growth under the stewardship of Offspark, a Dutch firm specializing in IoT . It became widely adopted for its ease of integration, readability, and focus on without unnecessary features, securing connections in numerous embedded devices and contributing to the early IoT ecosystem. Regular releases addressed evolving standards, such as enhanced DTLS support for UDP-based secure communications, while community contributions helped refine its for developer accessibility. By 2014, PolarSSL had established itself as the most pervasive embedded TLS solution in the industry, underscoring its impact on secure networking in constrained systems.

ARM Acquisition and Renaming

In February 2015, ARM announced the acquisition of Offspark, a Dutch software company specializing in Internet of Things (IoT) security solutions, including the PolarSSL cryptographic library. The deal, which integrated Offspark's technology into ARM's ecosystem, was aimed at strengthening communication security for embedded devices within the mbed platform, particularly for IoT applications such as sensor modules and smartphones. Some reports indicated that ARM had quietly acquired the PolarSSL technology as early as November 2014, with the full company acquisition following shortly thereafter. As part of the acquisition, PolarSSL was rebranded to ARM mbed TLS to align it more closely with ARM's mbed development platform for connected devices. This renaming emphasized its role in providing lightweight, open-source Transport Layer Security (TLS) and Datagram TLS (DTLS) implementations optimized for resource-constrained environments. The library, previously available under the GPL, transitioned to the Apache 2.0 license with the release of version 1.3.10, enabling broader commercial and embedded use while maintaining its open-source status. ARM planned to incorporate mbed TLS into the upcoming mbed OS, scheduled for release later that year, to facilitate secure data transmission in IoT ecosystems. Over time, the branding simplified from "ARM mbed TLS" to simply "mbed TLS," reflecting its evolution as a standalone, portable cryptographic library while retaining its foundational ties to 's mbed initiatives. This shift supported ongoing development focused on enhancing security features for emerging standards like TLS 1.3, without altering the library's core architecture derived from PolarSSL.

Major Releases Post-2015

Following the acquisition in , Mbed TLS continued development under the 2.x series, with several minor versions introducing enhancements and optimizations while maintaining where possible. The 2.16.0 release in December 2018 marked the first (LTS) branch in the series, supported until the end of 2021 with bug fixes and updates but no new features; it added optional validation via the MBEDTLS_CHECK_PARAMS configuration option and extended the ECDH interface for custom implementations. Subsequent updates in the 2.x line, such as 2.28.0 in December 2021, established another LTS branch (supported until at least March 2025), focusing on stability and addressing vulnerabilities like timing attacks in ECDSA and RSA operations. The transition to the 3.x series began with version 3.0.0, released on July 7, 2021, representing a significant architectural shift as the first major release under the TrustedFirmware.org governance following the project's migration in 2020. This version made the PSA Cryptography API the default cryptographic backend, introducing API-breaking changes to deprecate legacy modules and improve modularity, while adding support for hybrid key exchanges and enhanced parsing capabilities. Version 3.1.0, released on December 17, 2021, built on this foundation by providing initial experimental support for TLS 1.3, including draft implementations of key derivation and record protection, alongside fixes for multipart AEAD operations in PSA Crypto. Later 3.x releases emphasized and . The 3.6.0 version, released on March 27, 2024, launched the current LTS branch (supported until at least March 2027) and fully stabilized TLS 1.3 support, incorporating RFC 8446-compliant features like improved session ticket handling and post-handshake authentication, while adding PSA static key slots for secure in resource-constrained environments. This branch has seen ongoing patches, such as 3.6.5 in October 2025, addressing timing side-channel vulnerabilities in padding oracles and constant-time operations. In October 2025, Mbed TLS 4.0.0 introduced a major codebase restructuring, splitting the PSA Cryptography implementation into a separate repository (TF-PSA-Crypto) to allow independent development and reduce the core library footprint. This release removed deprecated legacy APIs, aligned with updated PSA specifications for algorithms like AES-GCM-SIV (RFC 8452), and enforced stricter default configurations for TLS clients, such as requiring hostname verification to mitigate man-in-the-middle risks. These changes aim to enhance maintainability and integration with the Platform Security Architecture (PSA) ecosystem.

Overview

Purpose and Capabilities

Mbed TLS serves as a lightweight, open-source cryptographic library primarily designed to enable secure data transmission in resource-constrained environments, such as embedded systems, (IoT) devices, and mobile applications. By implementing the Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) protocols alongside essential , it allows developers to integrate robust security features without excessive overhead, making it suitable for platforms with limited memory and processing power. The library's emphasis on portability ensures compatibility across various operating systems and hardware architectures, from microcontrollers to desktops. Key capabilities include full support for TLS 1.2 and TLS 1.3 protocols, which provide , , and for reliable network connections, as well as DTLS 1.2 for securing unreliable datagram-based communications like UDP. It handles the complete TLS/DTLS process, including negotiation, key exchange mechanisms (such as ECDHE and DHE), and session resumption to optimize performance. certificate manipulation is a core feature, enabling parsing, validation, and generation of digital certificates to establish trust in connections. The library offers a comprehensive suite of cryptographic algorithms, including symmetric ciphers like AES (in modes such as GCM and CBC) and ARIA, asymmetric via RSA and elliptic curve methods (e.g., ECDSA and ECDH), and hash functions such as SHA-256, , and . It also serves as a of the Arm Platform Security Architecture (PSA) Cryptography API, facilitating secure key storage, , and integration with modules or accelerators. Configuration options allow selective enabling of features to reduce the binary size to as little as 50 KB in minimal setups, balancing security and efficiency.

Key Design Goals

Mbed TLS is engineered with a focus on simplicity and efficiency, prioritizing ease of integration into resource-constrained environments such as embedded systems. Its adopts a "lean-and-mean" approach to , emphasizing readability, documentation, rigorous testing, of components, and broad portability to ensure developers can quickly understand, modify, and deploy the library without unnecessary complexity. A primary goal is portability across diverse platforms, achieved through adherence to the ISO standard, which allows the library to compile and run on most systems with minimal adjustments. This design enables seamless operation in both embedded devices and larger applications, with embedded portability integrated directly into modules rather than as separate layers. Additionally, the library's small footprint—typically under 100 KB for basic TLS configurations—makes it particularly suitable for IoT and microcontroller-based projects where memory and processing resources are limited. Modularity forms another key pillar, with independent modules that permit selective inclusion of features; for instance, developers can implement only AES encryption by linking solely to aes.c and aes.h, reducing binary size and dependencies. This supports flexible configuration via a single header file (mbedtls_config.h), allowing customization of algorithms, protocols, and optimizations at to balance , , and resource usage. The also serves as a for the PSA , promoting standardized, secure cryptographic interfaces that separate application memory from internal operations for enhanced safety. Security and reliability are embedded in the design through extensive validation mechanisms, including over 6,000 unit tests, 200 functional tests, and 2,000 interoperability tests that cover edge cases and ensure compliance with standards like TLS 1.3 and from NIST and IETF. Comprehensive documentation, including full references and example code, further aids secure usage by clarifying details and best practices. Distributed under a dual license of Apache 2.0 or GPL 2.0-or-later, Mbed TLS encourages community contributions while maintaining a focus on verifiable correctness, as demonstrated in formal verifications of components like HMAC-DRBG.

Architecture and Components

Core Modules

Mbed TLS employs a modular architecture designed for flexibility and minimal resource usage, particularly in embedded environments. The library is structured around three primary components: the cryptography primitives (via the TF-PSA-Crypto library, also known as libmbedcrypto), certificate handling (libmbedx509), and the SSL/TLS protocol implementation (libmbedtls). As of version 4.0.0, the PSA Cryptography functionality resides in its own repository, TF-PSA-Crypto, while maintaining integration with the other modules. These modules can be built independently or combined, allowing developers to include only necessary functionality to reduce code footprint and optimize performance. The core module, TF-PSA-Crypto (libtfpsacrypto or libmbedcrypto), provides a of the Platform Security Architecture (PSA) API, offering low-level primitives for symmetric and asymmetric , hashing, message authentication, key derivation, and . It supports algorithms such as AES, , RSA, ECC (including ), and , with hooks for optimized performance on supported platforms. This module ensures compliance with PSA specifications, enabling secure and isolation in trusted execution environments. The module (libmbedx509) handles certificate parsing, validation, and generation, supporting the full v3 standard for (PKI) operations. It includes functions for certificate revocation lists (CRLs), certificate signing requests (CSRs), and private key extraction, integrating seamlessly with the cryptography module for signature verification using algorithms like RSA and ECDSA. This component is essential for in TLS handshakes and is designed to process DER/PEM-encoded certificates efficiently. The SSL/TLS module (libmbedtls) implements the TLS 1.2, TLS 1.3, and DTLS 1.2 protocols, providing a complete stack. It manages connection setup, handshake negotiation, record layer encryption, and session resumption, configurable via ciphersuites like TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384. Built atop the and modules, it supports client and server roles, with options for custom I/O layers to abstract network transport. The module emphasizes configurability through preprocessor directives in mbedtls_config.h, allowing selective enabling of features to meet compliance or other standards.

Integration with PSA Cryptography

Mbed TLS integrates the Platform Security Architecture (PSA) Cryptography API as a core component, providing a standardized, portable interface for that enhances security in embedded and IoT applications. This integration allows developers to leverage PSA-managed keys and operations directly within Mbed TLS's TLS/DTLS protocols and certificate handling, promoting hardware-accelerated cryptography where available and ensuring compliance with Arm's PSA specifications. The PSA Crypto API in Mbed TLS serves as a , supporting key lifecycle management (generation, import, export, and destruction), symmetric and asymmetric encryption/decryption, signing/verification, hashing, key derivation, and with associated data (AEAD). For instance, it handles algorithms such as AES-128 in CBC mode without padding, RSA-1024 for signing, ECDSA on secp256r1 curves, SHA-256 hashing, for key derivation, and AES-128-GCM for AEAD operations. Operations typically begin with psa_crypto_init() to initialize the library, followed by key setup using attributes like psa_key_attributes_t to specify type, size, usage flags, and algorithms, and proceed through multi-part contexts (e.g., psa_cipher_operation_t) for setup, update, and finish phases. Cleanup is managed via psa_*_abort() for operations and psa_destroy_key() for keys, with mbedtls_psa_crypto_free() to release the library. Since Mbed TLS version 3.1, PSA Crypto support is mandatory when building with TLS, , or public-key (PK) modules, eliminating the option to disable it and ensuring all cryptographic operations route through the PSA interface for improved isolation and security. This shift aligns Mbed TLS with PSA's design goals of opaque key handling and driver extensibility, where the implementation includes a wrapper layer for compatibility and a driver layer to interface with hardware accelerators via the PSA Driver Interface. In Mbed OS environments, PSA-enabled Mbed TLS is the default, allowing seamless use of platform-specific secure elements. For TLS-specific integration, Mbed TLS exposes APIs to incorporate PSA keys as opaque handles, enhancing protection against key extraction. Examples include mbedtls_pk_setup_opaque() for ECDSA private keys in TLS client authentication or (CSR) generation, and mbedtls_ssl_conf_psk_opaque() for (PSK) ciphersuites in TLS sessions. Configuration requires enabling MBEDTLS_USE_PSA_CRYPTO in the library's config.h file during build, with PSA and non-PSA variants maintaining API compatibility but requiring recompilation for ABI changes. This setup supports partial hardware offloading, such as key pair generation and signature operations on secure elements, while fallback to software implementations ensures portability.

Development and Maintenance

Documentation and APIs

Mbed TLS provides comprehensive documentation hosted primarily on Read the Docs, including user guides, articles, and an reference generated from the source code. The main documentation portal at mbed-tls.readthedocs.io offers sections on getting started, configuration options, and best practices for integration, emphasizing the library's portability and modularity for embedded and general-purpose applications. Developers are encouraged to generate customized local documentation using from the source repository, producing HTML outputs that detail the full tailored to specific builds. The API reference, automatically derived from specially formatted comments in the C source code, organizes functionality into distinct modules for ease of use and selective inclusion. Key modules include those for SSL/TLS communication, which provide functions such as mbedtls_ssl_init(), mbedtls_ssl_handshake(), and mbedtls_ssl_read()/write() to manage secure sessions over TCP/IP transports like mbedtls_net_connect() and mbedtls_net_accept(). The module handles certificate parsing, validation, and generation with APIs like mbedtls_x509_crt_parse() for loading certificates and mbedtls_x509_crt_verify() for chain validation against trusted roots. are exposed through dedicated modules, such as AES ciphers via mbedtls_aes_init() and SHA hashes with mbedtls_sha256(), enabling developers to build custom security layers without full TLS overhead. Additionally, Mbed TLS serves as a of the Platform Security Architecture (PSA) Cryptography , offering a standardized interface like psa_crypto_init() for and psa_cipher_encrypt() for operations, which abstracts underlying hardware accelerators where available. This PSA layer promotes interoperability and simplifies migration across platforms. Documentation includes practical examples, such as the for implementing a basic TLS client and server using mbedtls_ssl_config_defaults() to set up contexts with default secure parameters. Configuration is managed via the mbedtls_config.h header, allowing compile-time documented in the build guides to optimize footprint and performance.

Testing and Security Audits

Mbed TLS employs a comprehensive automated testing framework to ensure reliability and correctness across its codebase. The library's , located in the tests/ directory, covers , corner cases, and with other implementations such as and . These tests are executed via make check and support various build configurations, including specific TLS versions and cipher suites, to verify functionality under diverse conditions. Additionally, memory-related checks using tools like , AddressSanitizer (), MemorySanitizer (MSan), and UndefinedBehaviorSanitizer (UBSan) detect leaks, overflows, and integrity issues. Compilation testing occurs on multiple platforms, including various systems (such as distributions and ), Windows (via and MS Visual Studio), and embedded targets, using compilers such as GCC, , Arm Compiler 6, and Microsoft Visual Studio. Code coverage analysis ensures thorough testing of and protocols. is performed using professional fuzzing tools, targeting (D)TLS handshakes and parsing to identify edge-case vulnerabilities. Static analysis is conducted using tools such as to scan the codebase for potential defects. Security audits of Mbed TLS have been conducted periodically to identify proactively. In 2025, a collaborative audit by Calif and the Security Team examined version 3.6.2, uncovering five issues: one high-severity and four medium-severity ones, all related to potential disclosure or denial-of-service in cryptographic operations. These findings were disclosed to the Mbed TLS maintainers in April 2025 and addressed in subsequent releases, with users recommended to upgrade to version 3.6.4 or later. Formal verification efforts complement empirical testing. A 2017 study formally verified the HMAC-DRBG component in Mbed TLS against NIST SP 800-90A specifications using the Coq proof assistant, proving both the functional correctness of the C implementation and its cryptographic security via game-based proofs. This end-to-end verification, including composition with C compiler correctness, confirms the generator produces pseudorandom outputs resistant to attacker predictions. Such modular proofs provide high-assurance guarantees for critical components, enhancing overall library security.

Usage

Configuration and Build Options

Mbed TLS configuration is managed through a dedicated header file, mbedtls_config.h, which allows users to enable or disable features at to optimize for specific platforms, security requirements, or resource constraints. The default configuration file, located in the include/mbedtls/ directory, is fully documented and serves as a starting point for customization. This file organizes options into categories such as system support (e.g., enabling inline assembly or ), feature support (e.g., TLS protocol versions and mechanisms), module selection (e.g., disabling RSA or to reduce footprint), and module-specific settings (e.g., adjusting multi-precision integer size or I/O buffer sizes). To customize the configuration, users can edit mbedtls_config.h directly or use the provided Python script scripts/config.py, which supports commands like set to enable an option or unset to disable it, with the -f flag for specifying a custom file path. Alternatively, the MBEDTLS_CONFIG_FILE macro can be defined at to point to a user-provided header, allowing seamless integration without modifying the source. Pre-configured examples in the configs/ directory, such as those for NSA Suite B TLS compliance, demonstrate tailored setups for particular use cases like high-security environments. Building Mbed TLS incorporates these configurations via standard tools like GNU Make or CMake, requiring a C99-compliant toolchain, Python 3.6 or later, and optionally Perl for testing. With Make, the process is initiated by running make in the library root, with options to specify the compiler (e.g., make CC=arm-linux-gnueabi-gcc) or adjust flags via environment variables like CFLAGS and LDFLAGS for non-GCC environments. Testing can follow with make check. For CMake, users run cmake . followed by make, with key options including -DUSE_SHARED_MBEDTLS_LIBRARY=On for shared libraries, -DCMAKE_BUILD_TYPE=Debug for debugging builds, and -DENABLE_TESTING=Off to skip tests. Additional modes like Coverage, AddressSanitizer (ASan), or MemorySanitizer (MemSan) are available via specific CMake presets, and the full list of options can be viewed with cmake -LH. On Windows, Visual Studio projects are provided for versions 2013 and later, enabling configuration through the IDE.

Example Integrations

Mbed TLS is integrated into Mbed OS, Arm's open-source platform for IoT devices, where it serves as the primary library for implementing SSL/TLS and DTLS protocols, enabling over networks with minimal resource overhead. In Mbed OS, developers configure Mbed TLS through TLSSocket APIs, which abstract the underlying cryptographic operations, allowing seamless handling of certificate validation and key exchanges in resource-constrained environments. This integration supports features like and readiness, making it suitable for connected devices in industrial and consumer applications. Zephyr RTOS, a scalable for embedded systems, incorporates Mbed TLS as the backend for its PSA Crypto implementation, providing a standardized interface for and secure transport layers. The integration allows Zephyr applications to leverage Mbed TLS for TLS/DTLS handshakes in protocols like CoAP and , with configuration options to optimize for hardware accelerators or software-only execution on microcontrollers such as those from . This setup ensures interoperability with the Platform Security Architecture, facilitating secure boot and updates in IoT ecosystems. Contiki-NG, an open-source operating system targeting low-power IoT devices, uses Mbed TLS to enable DTLS in its CoAP and LwM2M stacks, supporting certificate-based authentication and for constrained networks. The library is configured via custom platform headers to align with Contiki-NG's , allowing integration into 6LoWPAN-based deployments where it handles session resumption and replay protection without exceeding kilobyte-scale footprints. Recent releases have enhanced this integration for broader compliance in smart metering and sensor networks. RIOT OS, designed for applications, includes Mbed TLS as a configurable package that extends its networking capabilities with flexible TLS support, permitting developers to select modules for specific use cases like symmetric ciphers or parsing. Through RIOT's build system, Mbed TLS can be ported to various hardware platforms, integrating with the OS's event-driven kernel to support secure over-the-air updates and protocol wrappers for UDP-based transports. This modular approach aids in deploying secure mesh networks on devices with limited RAM and flash. Linphone, an open-source VoIP and video , employs Mbed TLS for handling secure SIP signaling and media transport encryption, replacing earlier dependencies like PolarSSL to support modern TLS versions and . The integration occurs via the linphone-sdk build system, where Mbed TLS provides the cryptographic backend for SRTP and protocols, ensuring end-to-end security in communications over public networks. This has enabled Linphone to maintain compatibility with enterprise-grade security requirements while keeping the library footprint lightweight for desktop and mobile builds.

Platform Support

Operating Systems

Mbed TLS exhibits high portability across operating systems due to its implementation in standard C, which minimizes reliance on platform-specific code and enables execution on diverse environments ranging from desktops to embedded devices. The library provides abstraction layers for key functions such as networking, timing, and entropy gathering, allowing adaptation to different OS APIs without extensive modifications. On desktop and server platforms, Mbed TLS natively supports Windows, as well as systems including distributions, BSD variants, and macOS (previously OS X). These systems leverage standard features like the BSD sockets API for network I/O and /dev/urandom or equivalent for sources, enabling seamless integration for applications requiring TLS/DTLS protocols. For instance, the timing module is optimized for Windows via its high-resolution performance counters and for Unix platforms using gettimeofday() or similar calls. In embedded contexts, Mbed TLS is deeply integrated with real-time operating systems (RTOS) tailored for resource-constrained devices. It serves as the primary cryptographic and TLS stack in Mbed OS, Arm's open-source RTOS for IoT (end-of-life scheduled for July 2026), where it handles alongside the OS's CMSIS-RTOS kernel for multithreaded execution. Compatibility extends to other RTOS environments, such as , through standardized interfaces like CMSIS-RTOS adaptations provided in development kits, facilitating secure networking in microcontroller-based systems. For bare-metal deployments without an underlying OS, Mbed TLS supports customization by disabling dependent modules—such as networking—and implementing platform-specific callbacks for , threading, and hardware entropy sources. This approach is common in ultralow-power microcontrollers, where the library's allows footprint reduction to under 100 KB while maintaining full cryptographic capabilities.

Hardware and Embedded Systems

Mbed TLS is designed as a lightweight, portable library that implements and TLS/DTLS protocols, making it particularly suitable for resource-constrained embedded systems with limited memory and processing power. Its modular architecture allows developers to enable only necessary features, resulting in a minimal footprint—typically around 50-100 KB for a basic TLS configuration—ideal for microcontrollers like those in the series used in IoT devices. This portability enables deployment on bare-metal environments or real-time operating systems such as without requiring an underlying OS kernel. The library supports through platform-specific "alternative engines" that offload cryptographic operations to dedicated hardware peripherals, improving performance and energy efficiency on embedded hardware. For instance, developers can replace software implementations of algorithms like AES or SHA with hardware-accelerated versions by defining custom functions in the mbedtls_config.h, which integrates seamlessly with the library's . This approach is outlined in the Mbed TLS development guidelines for hardware acceleration, emphasizing initial platform setup such as enabling caches or clocks before utilization. Integration with the Platform Security Architecture (PSA) Cryptography API further enhances hardware support, allowing Mbed TLS to interface with secure elements or hardware accelerators via driver plugins. The PSA in Mbed TLS enables abstraction of hardware crypto providers, such as trusted execution environments in TrustZone-M, facilitating secure key storage and operations on devices like microcontrollers. Representative examples include acceleration of AES encryption on STM32F7's CRYP peripherals and elliptic curve cryptography on ESP32's hardware engine, which can significantly reduce computation time compared to software-only execution in embedded benchmarks. Mbed TLS is widely adopted in embedded security frameworks, including Trusted Firmware-M (TF-M) for Armv8-M processors, where it provides TLS connectivity in secure partitions for IoT and industrial applications. This support extends to hardware like ' EFR32 series, where plugins accelerate AES and SHA operations using on-chip CRYPTO modules, and Infineon's PSoC 6, demonstrating up to 4x faster boot times with hardware-accelerated cryptography in secure boot scenarios. Overall, these capabilities position Mbed TLS as a key enabler for efficient, in power-sensitive embedded ecosystems.

Cryptographic Algorithms

Symmetric and AEAD Ciphers

Mbed TLS offers a flexible symmetric cryptography module that implements a variety of block and stream ciphers, along with multiple operating modes, to support secure data encryption and decryption in resource-constrained environments. The library's generic cipher interface, defined in cipher.h, allows developers to abstract operations across different algorithms while providing low-level control over keys, initialization vectors, and padding. This module is integral to higher-level protocols like TLS/DTLS, but can also be used standalone for custom applications. Support for these primitives is configurable at build time to balance security, performance, and footprint. The primary block ciphers include AES (with 128-, 192-, and 256-bit keys), (128-, 192-, and 256-bit), and (128-, 192-, and 256-bit). AES serves as the cornerstone, offering high security and hardware acceleration on many platforms, while Camellia and ARIA provide alternatives approved in various international standards. As of Mbed TLS 4.0.0 (released October 2025), support for legacy DES and Triple-DES (3DES) has been removed due to vulnerabilities like Sweet32. Block cipher modes of operation in Mbed TLS encompass ECB, CBC (with padding by default), CFB128, OFB, CTR, XTS (for scenarios), KW (key wrapping per NIST SP 800-38F), and KWP (key wrapping with padding). CTR mode, for instance, enables efficient stream-like encryption without padding, making it suitable for real-time data streams, while XTS provides tweakable encryption for sector-based storage. These modes are implemented to ensure constant-time operations where possible, reducing side-channel risks. Stream ciphers are represented by ChaCha20, a high-speed, secure primitive resistant to timing attacks. AEAD ciphers in Mbed TLS combine and authenticity in a single primitive, essential for protocols like TLS 1.3. Supported AEAD algorithms include AES-GCM, AES-CCM, AES-CCM* (CCM without authentication for specific use cases), Camellia-GCM, Camellia-CCM, Camellia-CCM*, ARIA-GCM, ARIA-CCM, ARIA-CCM*, and . GCM, defined in NIST SP 800-38D, uses GHASH for authentication and is widely adopted for its efficiency and parallelizability. CCM, per NIST SP 800-38C, offers with a built-in MAC, while (RFC 7539) pairs the stream cipher with Poly1305 for a lightweight, nonce-misuse-resistant option ideal for mobile and IoT devices. All AEAD modes support associated data for header protection without encryption.
CipherKey Sizes (bits)Supported ModesAEAD Variants
AES128, 192, 256ECB, CBC, CFB128, CTR, OFB, XTS, KW, KWP, GCM, CCM, CCM*AES-GCM, AES-CCM, AES-CCM*
128, 192, 256ECB, CBC, CFB128, CTR, GCM, CCM, CCM*Camellia-GCM, Camellia-CCM, Camellia-CCM*
ARIA128, 192, 256ECB, CBC, CFB128, CTR, GCM, CCM, CCM*ARIA-GCM, ARIA-CCM, ARIA-CCM*
ChaCha20256Stream
Configuration is managed via mbedtls_config.h, where macros like MBEDTLS_AES_C (enabled by default), MBEDTLS_CAMELLIA_C, MBEDTLS_ARIA_C, MBEDTLS_CHACHA20_C, MBEDTLS_CIPHER_MODE_CBC, MBEDTLS_GCM_C, and MBEDTLS_CCM_C control inclusion. Disabling unused ciphers reduces code size significantly—for example, excluding legacy options saves space in embedded builds—while ensuring compliance with standards like requires specific subsets. The PSA Crypto API wrapper provides an alternative, vendor-agnostic interface for these operations in Mbed TLS 3.x and later.

Hash and MAC Functions

Mbed TLS implements a range of standard cryptographic hash functions via its dedicated hashing module, enabling applications to compute message digests for integrity verification, digital signatures, and key derivation. The core supported algorithms include , a 128-bit one-way designed by for efficient computation on limited resources; , a 160-bit hash developed by NIST and NSA, though now considered deprecated for new security applications due to collision vulnerabilities; and the SHA-2 family, comprising (256-bit output), SHA-384 (384-bit), and SHA-512 (512-bit), which provide stronger security margins against collision attacks. Additionally, , standardized in FIPS 202, offers sponge-based hashing with variable output lengths and resistance to length-extension attacks inherent in Merkle-Damgård constructions like SHA-2. These implementations are accessible through a generic message digest (MD) interface, allowing seamless switching between algorithms at runtime, and are configurable via the library's build options in mbedtls_config.h to enable or disable specific hashes for footprint optimization in embedded environments. For message authentication, Mbed TLS provides HMAC (Hash-based Message Authentication Code) as a keyed hash construction, applicable to any supported hash function to ensure both data integrity and authenticity against an adversary without the secret key. Defined in RFC 2104 and updated in RFC 6234, HMAC operates by applying the hash function twice—first on the key padded with the message and then on the result with an inner hash—yielding outputs matching the underlying hash size, such as 256 bits for HMAC-SHA-256. This makes it suitable for protocols like TLS handshake integrity and secure channel establishment. The library's MD module handles HMAC computations generically, supporting multipart operations for streaming data and integration with PSA Cryptography API for modern applications. Complementing HMAC, Mbed TLS includes CMAC (Cipher-based Message Authentication Code), a mode for block ciphers that generates fixed-length tags using a symmetric key, primarily for AES as specified in RFC 4493 and SP 800-38B. CMAC processes input in block-sized chunks with CBC-like chaining and a final subkey-derived authentication, producing tags up to the block size (e.g., 128 bits for AES). It is preferred over older CBC-MAC for variable-length messages due to its security against length-extension exploits and is used in scenarios requiring lightweight authentication without public-key overhead, such as IoT device communications. The implementation supports single-part and multi-part operations, with hardware acceleration possible on supported platforms. Both hash and MAC functions in Mbed TLS emphasize portability and security, with constant-time implementations to mitigate timing attacks where feasible, and extensive testing against NIST vectors. While legacy algorithms like and remain for compatibility, the library encourages migration to or for new deployments to align with current standards like FIPS 140-3.

Public-Key and Key Exchange Algorithms

Mbed TLS provides robust support for and key exchange mechanisms through its modular design, enabling secure key establishment in protocols like TLS/DTLS. The library's public-key (PK) module serves as an for common operations such as encryption, decryption, signing, and verification, primarily focusing on RSA and (ECC) to balance security and performance on embedded systems. These algorithms are integral to certificate-based and session key derivation in secure communications. RSA support in Mbed TLS encompasses both encryption and digital signatures, adhering to standards. For encryption, the library implements (OAEP) with hash functions to ensure IND-CCA2 security, supporting key lengths from 1024 to 4096 bits, with 2048 bits or larger recommended for current threat models. Signature generation and verification support both v1.5 padding for and the more secure Probabilistic Signature Scheme (PSS), which resists existential forgery attacks when paired with strong hashes like SHA-256. These features allow RSA to be used for server authentication in TLS via certificate signatures or direct key transport in legacy ciphersuites. Elliptic curve algorithms are implemented for efficient public-key operations, particularly suited for resource-limited devices. The ECDSA module enables digital signatures over , following ANSI X9.62 and NIST FIPS 186-4 standards, with support for deterministic variants to avoid randomness issues. For key agreement, the ECDH module facilitates ephemeral key exchanges, deriving shared secrets via scalar multiplication on the curve. Supported curves include the NIST prime-field curves secp192r1, secp224r1, secp256r1, secp384r1, and secp521r1, which provide security levels equivalent to 96 to 256 bits of symmetric encryption. Brainpool curves (bp256r1, bp384r1, bp512r1) are also available for enhanced resistance to certain implementation attacks. and are supported for high-speed Diffie-Hellman-like exchanges in specific modes. These ECC primitives underpin ECDHE key exchanges in modern TLS ciphersuites, offering strong with smaller key sizes than RSA. The Diffie-Hellman Modular (DHM) module implements the classic Diffie-Hellman key agreement protocol over finite fields, enabling ephemeral (DHE) exchanges for in TLS. It supports customizable prime moduli and generators, with built-in handling for safe primes to prevent small-subgroup confinement attacks, and group sizes up to 8192 bits for high-security applications. Standard groups from RFC 3526 and RFC 7919 are configurable, allowing integration with ciphersuites like TLS_DHE_RSA_WITH_AES_256_GCM_SHA384. In the context of TLS key exchanges, Mbed TLS integrates these primitives into a flexible framework supporting multiple methods across TLS 1.2 and TLS 1.3. Static RSA key exchange encrypts the premaster secret with the server's public key, though it lacks and is discouraged in favor of ephemeral methods. DHE and ECDHE provide perfect by generating temporary parameters per session, with ECDHE preferred for its computational efficiency—offering up to 10x faster handshakes than DHE on typical hardware. (PSK) modes support symmetric authentication without public-key infrastructure, ideal for IoT, with optional ECDHE for added secrecy. ECJPAKE enables password-based authenticated key exchange resistant to offline dictionary attacks, compliant with RFC 8236. For TLS 1.3, only (EC)DHE and PSK-based exchanges are permitted, ensuring mandatory as per RFC 8446, with the library providing hybrid PSK-(EC)DHE for enhanced security. Ciphersuite selection is configurable via the SSL module, allowing prioritization of algorithms based on policy.
Key Exchange MethodPublic-Key AlgorithmForward SecrecyTypical Use CaseExample Ciphersuite (TLS 1.2)
Static RSARSANoLegacy systemsTLS_RSA_WITH_AES_128_GCM_SHA256
DHEDHM (Diffie-Hellman)High-security serversTLS_DHE_RSA_WITH_AES_256_GCM_SHA384
ECDHEECC (ECDH)Embedded/mobileTLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
PSKNone (symmetric)No (configurable with ECDHE)IoT networksTLS_PSK_WITH_AES_128_CCM_8
ECJPAKEECC (ECDH variant)Password authTLS_ECJPAKE_WITH_AES_128_CCM_8
This table illustrates representative methods; full support depends on build-time configuration options like MBEDTLS_KEY_EXCHANGE_RSA_ENABLED or MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED.

References

  1. https://github.com/Mbed-TLS/mbedtls
  2. https://www.arm.com/company/news/2015/02/arm-buys-leading-iot-security-company-offspark-as-it-expands-its-mbed-platform
  3. https://mbed-tls.readthedocs.io/en/latest/
  4. https://github.com/Mbed-TLS/mbedtls/releases
  5. https://lists.trustedfirmware.org/archives/list/mbed-tls%40lists.trustedfirmware.org/thread/MY6Y3UHDLZJY3HOWQE32VNGCEMJ7DQ3F/
  6. https://www.trustedfirmware.org/projects/mbed-tls/
  7. https://subreption.com/security-advisories/mbed-tls-weak-diffie-hellman/
  8. https://archive.conference.hitb.org/hitbsecconf2010ams/index.html_page_id=868.html
  9. https://brainspark.nl/downloads/2012-02-05-fosdem-polarssl.pdf
  10. https://wikileaks.org/vault8/document/repo_hive/server/polarssl-1_3_4/ChangeLog/
  11. https://www.securityweek.com/polarssl-rebranded-arm-mbed-tls-after-acquisition/
  12. https://www.pcmag.com/news/arm-acquires-iot-security-firm-offspark
  13. https://github.com/Mbed-TLS/mbedtls/releases/tag/mbedtls-2.16.0
  14. https://www.trustedfirmware.org/blog/mbed-tls-30/
  15. https://github.com/Mbed-TLS/mbedtls/releases/tag/mbedtls-3.6.0
  16. https://github.com/Mbed-TLS/mbedtls/releases/tag/mbedtls-4.0.0
  17. https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/protocols/mbedtls.html
  18. https://mbed-tls.readthedocs.io/en/latest/kb/how-to/dtls-tutorial/
  19. https://mbed-tls.readthedocs.io/en/latest/kb/compiling-and-building/how-do-i-configure-mbedtls/
  20. https://mbed-tls.readthedocs.io/en/latest/kb/generic/mbedtls-philosophy/
  21. https://github.com/Mbed-TLS/TF-PSA-Crypto
  22. https://www.cs.princeton.edu/~appel/papers/verified-hmac-drbg.pdf
  23. https://products.psacertified.org/products/mbed-tls
  24. https://mbed-tls.readthedocs.io/en/latest/getting_started/psa/
  25. https://arm-software.github.io/psa-api/crypto/
  26. https://lists.trustedfirmware.org/archives/list/[email protected]/thread/ABCILQL52V72MG2AJHT2ATLXMNCAHGND/
  27. https://os.mbed.com/docs/mbed-os/v6.16/porting/using-psa-enabled-mbed-tls.html
  28. https://armmbed.github.io/mbed-crypto/psa/se/
  29. https://mbed-tls.readthedocs.io/projects/api/en/latest/
  30. https://mbed-tls.readthedocs.io/projects/api/en/v3.4.1/
  31. https://mbed-tls.readthedocs.io/en/latest/kb/how-to/mbedtls-tutorial/
  32. https://github.com/Mbed-TLS/mbedtls-test
  33. https://scan.coverity.com/projects/armmbed-mbedtls
  34. https://blog.calif.io/p/partnering-with-google-to-strengthen
  35. https://dl.acm.org/doi/10.1145/3133956.3133974
  36. https://mbed-tls.readthedocs.io/en/latest/getting_started/building/
  37. https://os.mbed.com/docs/mbed-os/v6.16/apis/tls.html
  38. https://docs.zephyrproject.org/latest/services/crypto/psa_crypto.html
  39. https://docs.contiki-ng.org/en/develop/_api/mbedtls-support_8h.html
  40. https://doc.riot-os.org/group__pkg__mbedtls.html
  41. https://wiki.linphone.org/xwiki/wiki/public/view/Linphone/Third%20party%20components%20/
  42. https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS/
  43. https://os.mbed.com/blog/entry/Important-Update-on-Mbed/
  44. https://www.keil.arm.com/packs/mdk-middleware-keil/
  45. https://mbed-tls.readthedocs.io/en/latest/kb/development/hw_acc_guidelines/
  46. https://os.mbed.com/docs/mbed-os/v6.16/porting/hardware-accelerated-crypto.html
  47. https://www.trustedfirmware.org/projects/tf-m/
  48. https://siliconlabs.github.io/Gecko_SDK_Doc/mbedtls/html/group__sl__crypto.html
  49. https://github.com/Infineon/cy-mbedtls-acceleration
  50. https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/cipher_8h/
  51. https://github.com/Mbed-TLS/mbedtls/issues/7024
  52. https://lists.trustedfirmware.org/archives/list/[email protected]/thread/ITQQTLJPZSJNZHB5JSAIGXGPXBLMJYDY/
  53. https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/mbedtls__config_8h/
  54. https://arm-software.github.io/CMSIS-mbedTLS/latest/group__hashing__module.html
  55. https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/sha3_8h/
  56. https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/md_8h/
  57. https://arm-software.github.io/CMSIS-mbedTLS/latest/cmac_8h.html
  58. https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/pk_8h/
  59. https://mbed-tls.readthedocs.io/en/latest/kb/how-to/encrypt-and-decrypt-with-rsa/
  60. https://mbed-tls.readthedocs.io/en/latest/kb/generic/rsassa-pss/
  61. https://mbed-tls.readthedocs.io/en/latest/kb/cryptography/elliptic-curve-performance-nist-vs-brainpool/
  62. https://github.com/Mbed-TLS/mbedtls/tree/development/library
  63. https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/ssl__ciphersuites_8h/
Add your contribution
Related Hubs
User Avatar
No comments yet.