[Frauschi]

Description

New manual for teams moving products from Mbed TLS 3.6 or 4.x to wolfSSL. The Mbed TLS team announced in October 2026 that its TLS and X.509 maintainers step down in April 2027, and 3.6 LTS ends in March 2027, so this guide gives those users one place to start. It follows the layout of the Bouncy Castle migration guide.

Chapters:

1. Introduction, with an Mbed TLS support-status table (as of October 2026)
2. Design differences (contexts, RNG, memory, licensing)
3. Porting a TLS client, side by side
4. Common pitfalls
5. Hardware and platforms (crypto callbacks, Zephyr, ESP-IDF)
6. Features beyond Mbed TLS (DTLS 1.3, PQC, FIPS 140-3, wolfPSA)
7. Getting started and interop testing
8. API mapping
9. Configuration equivalents (./configure and user_settings.h)
10. Support

Build changes:

• make mbedtls-migration target in the root Makefile (also added to all) and a README entry.
• header.txt allows line breaks after underscores and turns off hyphenation in the monospace font, and the tables set explicit column widths. Without this, long identifiers in the API tables overlap the next column in the PDF, or print hyphenated (WOLF-SSL_...).

Testing

• make mbedtls-migration builds the PDF and HTML with no mkdocs warnings; make test (markdownlint and link check) passes.
• The wolfSSL code samples compile with -Wall -Wextra -Werror against wolfSSL master. The TLS client returns 0 against examples/server, -322 for a wrong host and -188 for a wrong CA.
• The interop commands in chapter 7 were run against Mbed TLS 4.1.1 ssl_client2 / ssl_server2, including the TLS 1.3 session-ticket behaviour described in chapter 9.
• The user_settings.h recipes in chapter 9 were compiled: the TLS 1.3 template plus the named defines builds and negotiates an ML-KEM hybrid group, and the DTLS 1.3 template builds cleanly with -Werror.

Notes

• Two notes are temporary and should come out once the fixes are in a wolfSSL release: the --enable-ticket-nonce-malloc note in the session-ticket row of chapter 9 (Keep TLS 1.3 connections working when the ticket nonce is longer than 8 bytes wolfssl#11745), and the ML-KEM decapsulation note for device-held keys in chapter 5 (Let an ML-KEM key named by id decapsulate on a device wolfssl#11773, merged after 5.9.4).
• A short blog post announcing the guide links to https://www.wolfssl.com/documentation/manuals/mbedtls-migration/. Please publish the manual under that path, or tell me the final URL so the post can be updated.

[Copilot]

🟡 Changes recommended

The guidance needs corrections to preserve negotiated-group restrictions and enable DTLS ClientHello fragmentation at runtime.

2 open issues

• Key-share selection bypasses configured TLS group restrictions · New
• DTLS fragmented ClientHello support also requires runtime enablement · New

What changed in this PR

Adds an Mbed TLS 3.6/4.x migration guide to the wolfSSL documentation suite.

Changes:

• Adds ten chapters covering migration, API mappings, configuration, and interoperability.
• Integrates PDF and HTML builds with the root Makefile.
• Adds navigation, validation settings, and PDF identifier wrapping.

File	Description
README.md	Lists the new build target.
MbedTLS-Migration/​test/​lintcheck.json	Configures Markdown linting.
MbedTLS-Migration/​test/​linkcheck.json	Configures link checking.
MbedTLS-Migration/​src/​chapter10.md	Lists support resources.
MbedTLS-Migration/​src/​chapter09.md	Maps configuration options.
MbedTLS-Migration/​src/​chapter08.md	Maps migration APIs.
MbedTLS-Migration/​src/​chapter07.md	Provides interoperability commands.
MbedTLS-Migration/​src/​chapter06.md	Compares additional capabilities.
MbedTLS-Migration/​src/​chapter05.md	Covers hardware and platforms.
MbedTLS-Migration/​src/​chapter04.md	Explains migration pitfalls.
MbedTLS-Migration/​src/​chapter03.md	Provides paired TLS client examples.
MbedTLS-Migration/​src/​chapter02.md	Explains architectural differences.
MbedTLS-Migration/​src/​chapter01.md	Introduces scope and support status.
MbedTLS-Migration/​mkdocs.yml	Configures HTML navigation and theme.
MbedTLS-Migration/​Makefile	Defines manual build sources.
MbedTLS-Migration/​header.txt	Configures PDF formatting and wrapping.
Makefile	Adds the standalone and aggregate build target.

_{Review effort: Balanced}