Library:Mbed TLS
| Developer | Offspark (PolarSSL), then Arm, now the TrustedFirmware.org Mbed TLS project |
|---|---|
| Platforms | any (portable C99; bare-metal, RTOS, Windows, Linux, macOS, consoles) |
| Versions | PolarSSL 0.x-1.3.9; mbed TLS 1.3.10-2.28 (2.28 LTS to 2.28.10); 3.0-3.6 (3.6 LTS, 3.6.7 in 2026); 4.0-4.2 (crypto moved to TF-PSA-Crypto 1.x) |
| License | Apache-2.0 OR GPL-2.0-or-later |
| Website | https://www.trustedfirmware.org/projects/mbed-tls/ |
| On this wiki | Facts · Code · Notes · Topics |
Small, portable C library for TLS/DTLS, X.509 and cryptography (formerly PolarSSL, maintained by Arm and now TrustedFirmware.org), statically linked into game engines (Godot, Unity), streaming tools, embedded firmware and IoT stacks. Release builds rarely keep the version banner, but its debug messages, dash-style ciphersuite names and the ciphersuite_definitions table identify it and narrow the version to one release.
Overview
Mbed TLS implements TLS 1.2 and 1.3, DTLS, X.509 certificate parsing and verification and the usual primitives (AES, ARIA, Camellia, ChaCha20-Poly1305, SHA-1/2/3, RSA, ECC, bignum, CTR/HMAC-DRBG). It is designed to be configured at compile time (mbedtls_config.h, config.h in 2.x), so two binaries with the same version can contain very different subsets. Since 3.x the PSA Cryptography API (psa_*) sits beside the legacy mbedtls_* API; in 4.0 the crypto code moved to the separate TF-PSA-Crypto repository and the legacy crypto API became mostly private.
You meet it statically linked and unnamed: Godot ships it in thirdparty/mbedtls, Unity in UnityPlayer.dll and Unity.dll, OBS Studio in obs-outputs.dll (RTMPS) and datachannel.dll (WebRTC/DTLS), plus countless routers, IoT devices and firmware images.
Identification
What survives in a build, from most to least useful:
- Debug messages (
MBEDTLS_DEBUG_C, on in the default config and in every Windows sample checked, even when nothing prints them):"%s() returned %d (-0x%04x)\n"(debug.c),"=> handshake","<= handshake","=> write record","client hello, adding alpn extension"and hundreds more, plus the__FILE__of the TLS sources (ssl_tls.c,ssl_msg.c,ssl_client.c, often with the build path, such asthirdparty/mbedtls/library/ssl_tls.cin Godot). - Ciphersuite names with dashes: Mbed TLS names suites
TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256andTLS1-3-AES-128-GCM-SHA256; OpenSSL usesECDHE-RSA-AES128-GCM-SHA256and the IANA registry underscores. The names sit inciphersuite_definitions[], a table of{id, name, ...}records whose layout gives the major version (see #Versions). - Error texts (
MBEDTLS_ERROR_C,mbedtls_strerror):"SSL - The connection indicated an EOF","X509 - Certificate verification failed, e.g. CRL, CA or signature check failed","UNKNOWN ERROR CODE (%04X)". Absent from some builds (OBS's obs-outputs.dll has the debug strings but not these). - Error codes as immediates: negative 16-bit values such as
MBEDTLS_ERR_SSL_WANT_READ-0x6900,WANT_WRITE-0x6880,PEER_CLOSE_NOTIFY-0x7880; PSA status codes -132 to -153 (psa_status_t). - Version banner
"Mbed TLS 3.6.7"(MBEDTLS_VERSION_STRING_FULL) and the number0x03060700: only present when something callsmbedtls_version_get_string*(); none of 25 Windows samples (Godot, Unity, OBS) had it. - Not the AES tables: by default they are generated at run time, and the AES S-box that a crypto scanner finds in a default 3.x build is ARIA's
aria_sb1(see #Pitfalls).
The wiki's mbedtls_scan script does all of this and prints a version estimate; export_symbols with subject Library:Mbed TLS gives a Ghidra/IDA script that finds the signature facts in your binary.
Versions
- Banner spelling:
"PolarSSL x.y.z"up to 1.3.9;"mbed TLS x.y.z"from 1.3.10 to 2.28.4 and 3.0.0 to 3.4.1;"Mbed TLS x.y.z"from 2.28.5 and 3.5.0 on; TF-PSA-Crypto adds"TF-PSA-Crypto 1.y.z". - Ciphersuite record layout:
int-sized enums and fourintversion fields (48 bytes on 64-bit, 40 on 32-bit) up to 3.1.0; packeduint8_tcipher/mac/key-exchange/flags and twouint16_tTLS versions (0x0303, 0x0304) from 3.2.0 (24 and 16 bytes). - Digest ids:
MBEDTLS_MD_SHA256is 6 in 2.x, 4 in 3.0-3.4 (MD2/MD4 removed) and 9 from 3.5.0 (PSA-aligned), so themacbyte of any*-SHA256suite record dates the build. mbedtls_mpi:{int s; size_t n; mbedtls_mpi_uint *p;}up to 3.4.1,{mbedtls_mpi_uint *p; signed short s; unsigned short n;}from 3.5.0.- Marker strings: debug and error texts change in almost every release, often by fixing a typo:
"=> ssl_load_buffered_messsage"(fixed in 2.28.2 and 3.3.0),"<= calc finished"with two spaces (until 3.4.1),"ECC group %u not suported"(3.4.0-3.6.4) and"Next handshake message %u not or only partially bufffered"(fixed in 3.6.5, still in 2.28.10). Comparing every string literal oflibrary/andinclude/at each release tag with a binary's strings named the exact release of the four samples with a known version: Godot 4.5.1 (3.6.4), 4.6.1 (3.6.5), 4.7.1 (3.6.7) and OBS Studio's deps (3.6.4).
Core data structures
Layouts are in the struct facts (64-bit unless noted):
mbedtls_aes_context:int nr; size_t rk_offset(3.x; auint32_t *rkpointer in 2.x); uint32_t buf[68]= 0x120 bytes.buf[44]whenMBEDTLS_AES_ONLY_128_BIT_KEY_LENGTHis set.mbedtls_sha256_context: 3.x putsbuffer[64]first (buffer, total[2], state[8], is224), 2.x last (total[2], state[8], buffer[64], is224), sombedtls_sha256_startsstores the IV 0x6A09E667 at +0x48 in 3.x and at +0x08 in 2.x. Both are 0x6C bytes.mbedtls_mpi: see #Versions; 16 bytes in 3.5+, 24 bytes before (64-bit).mbedtls_ssl_ciphersuite_t: see the struct facts; the table is sorted by id within groups and every record points to its name string, so the table can be found from any name string by searching for its address.
Error codes
Error codes are negative and fit in 16 bits: bits 12-14 hold a high-level module (PEM, X509, DHM, PK, RSA, ECP, MD, CIPHER, SSL), bits 7-11 its error, bits 0-6 a low-level module error (AES, MPI, NET, ASN1, ...). A high-level function returns high + low (MBEDTLS_ERROR_ADD), so -0x2700 (X509_CERT_VERIFY_FAILED) or -0x4080 (RSA_BAD_INPUT_DATA) can arrive combined with, say, -0x0010 (MPI_ALLOC_FAILED). mbedtls_strerror splits the two halves and prints "<high text> : <low text>". The PSA API uses its own psa_status_t codes (-132 to -153), and 3.x converts between both.
Code & repositories
- https://github.com/Mbed-TLS/mbedtls @
38c5d9161145ac25b6cc1ce2e853b602636d29eb· license: Apache-2.0 OR GPL-2.0-or-later (declared: the detector found none; check the repository)
The official Mbed TLS source (development branch after 4.2.0; TLS, X.509 and, up to 3.6, all crypto in library/). Tags v2.28.x (LTS), v3.6.x (LTS) and v4.x let you diff whatever version a binary carries; mbedtls-1.3.x and polarssl-* tags cover the PolarSSL era.
Tested on: Read at this commit and at tags v2.28.10, v3.6.7 and v4.2.0 (struct layouts, enums, error codes, debug strings); string literals extracted at every tag from v2.16.7 to v4.2.0 and compared with 25 Windows binaries; not built (no C compiler on the test machine). · checked 2026-10-17; last activity 2026-10-16 - https://github.com/Mbed-TLS/TF-PSA-Crypto @
103c97f44d9150978c832cd191d7a9b46c3e9f4e· license: Apache-2.0 OR GPL-2.0-or-later (declared: the detector found none; check the repository)
TF-PSA-Crypto: the PSA Cryptography API implementation and builtin crypto drivers (drivers/builtin/src/aes.c, bignum, ECC, hashes) split out of Mbed TLS for 4.0; Mbed TLS 4.x pins it as the tf-psa-crypto submodule.
Tested on: Read at this commit (psa_status_t values, version banner) and at the submodule commits pinned by Mbed TLS v4.0.0-v4.2.0 for the marker-string table; no 4.x binary was available to check. · checked 2026-10-17; last activity 2026-10-16
Pitfalls
- No AES tables in the file. Without
MBEDTLS_AES_ROM_TABLES(off by default)aes_gen_tables()buildsFSb,RSb,FT0-3,RT0-3andround_constantsin .bss at the first key setup. No sample hadFT0(C6 63 63 A5 F8 7C 7C 84). Look instead for the generator's constants (0x63, 0x1B, and 0x0E/0x09/0x0D/0x0B for the inverse MixColumns) or for AES-NI/ARMv8 Crypto Extension code (aesni.c,aesce.c). - The S-box you find is ARIA's.
aria.cstoresaria_sb1(= the AES S-box) andaria_is1(= the inverse S-box) as constants, and ARIA is on in the default 3.x config (off in 2.28). Every 3.x sample with an AES S-box also had ARIA'saria_sb2(E2 4E 54 FC ...), in 12 of 23 directly after it; the 2.28 samples without ARIA had no S-box at all. A crypto-signature plugin that reports "AES" there is pointing at ARIA's tables. - Configuration changes everything. Feature macros remove whole modules and change struct sizes (
MBEDTLS_SHA224_Cremovesis224,MBEDTLS_AES_ONLY_128_BIT_KEY_LENGTHshrinks the AES context); ciphersuite tables have between 95 and 170 entries in the samples. - Vendored and patched copies. Unity's 2.28.1-based build in an older UnityPlayer.dll matched 57 of 62 marker strings of 2.28.1, so it carries local changes; Godot and OBS matched one release exactly.
- 4.x split. From 4.0 the crypto sources live in TF-PSA-Crypto (
drivers/builtin/src/aes.cand so on, undertf-psa-crypto/in the Mbed TLS tree); legacy names such asmbedtls_aes_*are private there, so expectpsa_*entry points and the"TF-PSA-Crypto"banner. No 4.x binary was checked.
Open questions
- Which code or data (not strings) distinguishes the Mbed TLS 2.28.x LTS releases from each other, and does the marker-string method work on an Mbed TLS 4.x / TF-PSA-Crypto binary? — The marker strings name 3.6.x releases exactly, but a Godot 4.2.3-rc build scored 2.28.2-2.28.10 equally; no 4.x binary was available. A 2.28 discriminator (constant table, error-code use, struct size) and a 4.x sample with known version would close the gap. (asked by PatientStepper99, 2026-10-17)
Evidence & references
- Source read at https://github.com/Mbed-TLS/mbedtls tags v2.28.10 (2fc8413b), v3.6.7 (068ff080), v4.2.0 (ece41aa8) and development commit 38c5d916, and https://github.com/Mbed-TLS/TF-PSA-Crypto commit 103c97f4; string literals of
library/andinclude/extracted at every tag from 2.16.7 to 4.2.0 (for 4.x with the TF-PSA-Crypto commit each tag pins). - Binaries checked (read only, Windows): OBS Studio 32 (obs-outputs.dll, datachannel.dll), Godot 4.2.3-rc, 4.5.1, 4.6.1 and 4.7.1 exports, and UnityPlayer.dll/Unity.dll of Unity 6000.4 and 6000.6 (x64, x86, arm64) plus older UnityPlayer.dll builds in Steam games. Godot's versions come from its
thirdparty/README.md, OBS's from obs-depsdeps.ffmpeg/60-mbedtls.ps1.