Skip to content

Add Mbed TLS 4.x TLS, net and PEM API - #54

Merged
Frauschi merged 5 commits into
wolfSSL:masterfrom
padelsbach:mbedtls-tls
Nov 16, 2026
Merged

Frauschi merged 5 commits into
wolfSSL:masterfrom
padelsbach:mbedtls-tls

Conversation

@padelsbach

Copy link
Copy Markdown
Contributor

Follow up to #53 and builds upon it. Adds networking API and PEM decode

Copilot AI balanced review requested due to automatic review settings November 13, 2026 00:41

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Session resumption on supported wolfSSL 5.9.4 can bypass required client-certificate authentication, leaving a critical security issue unresolved.

3 open issues
What changed in this PR

Extends wolfPSA’s Mbed TLS 4.x compatibility layer beyond the X.509 work in #53, adding wolfSSL-backed TLS, socket networking, and PEM decoding.

Changes:

  • Adds compatibility APIs, headers, and shared-library exports.
  • Integrates TLS sources and feature detection into the optional MBEDTLS_COMPAT=1 build.
  • Adds parsing, TLS, memory-tracking, and interoperability tests, with CI and usage documentation.
File Description
wolfpsa/​mbedtls_compat/​mbedtls/​x509.h Defines X.509 types, flags, and errors.
wolfpsa/​mbedtls_compat/​mbedtls/​x509_crt.h Declares certificate parsing APIs and profiles.
wolfpsa/​mbedtls_compat/​mbedtls/​version.h Exposes compatibility version macros.
wolfpsa/​mbedtls_compat/​mbedtls/​timing.h Adds a placeholder timing header.
wolfpsa/​mbedtls_compat/​mbedtls/​ssl.h Declares TLS configuration, connection, and session APIs.
wolfpsa/​mbedtls_compat/​mbedtls/​ssl_ciphersuites.h Defines cipher suite identifiers.
wolfpsa/​mbedtls_compat/​mbedtls/​psa_util.h Adds a PSA utility compatibility header.
wolfpsa/​mbedtls_compat/​mbedtls/​pem.h Declares PEM decoding APIs.
wolfpsa/​mbedtls_compat/​mbedtls/​net_sockets.h Declares socket networking APIs.
wolfpsa/​mbedtls_compat/​mbedtls/​error.h Adds a placeholder error header.
wolfpsa/​mbedtls_compat/​mbedtls/​debug.h Exposes the TLS debug configuration declaration.
wolfpsa/​mbedtls_compat/​mbedtls/​build_info.h Defines API version and feature information.
wolfpsa/​mbedtls_compat/​mbedtls/​asn1.h Defines the ASN.1 buffer type.
wolfpsa.map Exports compatibility API symbols.
user_settings.h Enables wolfSSL TLS settings for compatibility builds.
tools/​psa_want_probe.c Detects supported compatibility features.
tools/​gen-crypto-config.py Updates comments to mention Mbed TLS options.
test/​psa_server/​psa_track_memory_test.c Tests compatibility allocation and initialization behavior.
test/​mbedtls_compat/​x509_crt_test.c Tests certificate parsing and failure cases.
test/​mbedtls_compat/​ssl_test.c Tests TLS verification, I/O, configuration, and sessions.
test/​mbedtls_compat/​programs.sh Runs client/server interoperability scenarios.
test/​mbedtls_compat/​pk_test.c Tests private-key parsing compatibility.
test/​mbedtls_compat/​pem_test.c Tests PEM decoding and invalid input.
test/​mbedtls_compat/​Makefile Builds compatibility tests and external sample programs.
test/​mbedtls_compat/​client-tls-mbedtls.c Adds a migration-guide client with nonblocking mode.
test/​Makefile Enables compatibility APIs in memory-tracking tests.
src/​psa_tf_psa.c Shares error mapping and file-loading helpers.
src/​psa_tf_psa_internal.h Declares shared internal helpers.
src/​mbedtls/​x509.c Implements certificate parsing through wolfCrypt.
src/​mbedtls/​ssl.c Implements TLS APIs through wolfSSL.
src/​mbedtls/​pem.c Implements unencrypted PEM decoding.
src/​mbedtls/​net.c Implements socket networking wrappers.
src/​mbedtls/​mbedtls_compat_internal.h Declares shared I/O conversion helpers.
README.md Documents setup, supported APIs, limitations, and tests.
Makefile Integrates compatibility sources and test targets.
.github/​workflows/​mbedtls-compat.yml Adds compatibility and build-variant CI coverage.

Review effort: Balanced

Comment thread src/mbedtls/ssl.c Resolved
Comment thread src/mbedtls/ssl.c Resolved

@Frauschi Frauschi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A failed mbedtls_ssl_set_hostname currently lets the handshake skip the host-name check; the rest are smaller.

Comment thread src/mbedtls/ssl.c
}
wolfSSL_SESSION_free(session);
if (ret == 0) {
ssl->conf_changes = ssl->conf->changes;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If MbedSslNew() fails after wolfSSL_new(), the half-built WOLFSSL stays with conf_changes still current, so after setup mbedtls_ssl_set_hostname(&ssl, "router") fails but the next handshake succeeds with no host-name check. Free ssl->ssl and set it to NULL on any failure here.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

Comment thread src/mbedtls/ssl.c Outdated
#include "mbedtls_compat_internal.h"
#include "psa_tf_psa_internal.h"

#if LIBWOLFSSL_VERSION_HEX < 0x05009004

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wolfSSL master and v5.9.4-stable both report 0x05009004, so this lets 5.9.4 through, and the test-psa-api (v5.9.4-stable) job already builds this layer for psa_track_memory_test. 5.9.4 lacks wolfSSL 7460ecc (client auth on resumed sessions), so this needs a check only master passes.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the check. Newest wolfPSA requires newest wolfSSL for now. Updated test-psa-api to run with MBEDTLS_COMPAT=0

Comment thread src/mbedtls/ssl.c
conf->min_tls_version = MBEDTLS_SSL_VERSION_TLS1_2;
conf->max_tls_version = MBEDTLS_SSL_VERSION_TLS1_3;
conf->ciphersuites = NULL;
conf->ctx = wolfSSL_CTX_new(methods[i].method());

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wolfSSL_CTX_new() calls wolfSSL_Init() on first use, which takes a second wolfCrypt_Init() reference that nothing releases, so mbedtls_psa_crypto_free() no longer cleans up wolfCrypt. Pair it with wolfSSL_Cleanup() in wolfPSA_CryptoCleanup() when the TLS layer is built.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed for both MBEDTLS_SSL_TLS_C defined and not

Comment thread src/mbedtls/ssl.c Outdated
if (ssl == NULL || ssl->ssl == NULL) {
return NULL;
}
return wolfSSL_get_cipher(ssl->ssl);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This returns the IANA name, so mbedtls_ssl_get_ciphersuite_id(mbedtls_ssl_get_ciphersuite(&ssl)) is 0, where Mbed TLS returns its own name. Return mbedtls_ssl_get_ciphersuite_name(wolfSSL_get_current_cipher_suite(ssl->ssl)) instead.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed as suggested

Comment thread src/mbedtls/ssl.c
MBEDTLS_ERR_SSL_BAD_INPUT_DATA);
XFREE(chain, NULL, DYNAMIC_TYPE_TMP_BUFFER);
if (ret == 0) {
ret = MbedRet(wolfSSL_CTX_use_PrivateKey_buffer(conf->ctx,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this key load fails, the CTX keeps the new chain with the old key, where Mbed TLS leaves the config unchanged; validate the key before replacing the chain. Server setup without an own cert also reports ALLOC_FAILED from the NULL wolfSSL_new(), which hides the real cause.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

Comment thread src/mbedtls/ssl.c Outdated
if (hostname == NULL) {
return 0;
}
ret = MbedRet(wolfSSL_UseSNI(ssl, WOLFSSL_SNI_HOST_NAME, hostname,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RFC 6066 does not allow an IP literal in server_name, and some servers reject such a ClientHello, even though Mbed TLS sends it too. Skip wolfSSL_UseSNI() when MbedIpText() matches and keep the IP SAN check.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

Comment thread src/mbedtls/ssl.c
static void MbedConfCAs(mbedtls_ssl_config* conf)
{
const mbedtls_x509_crt* crt;
int ret = (conf->ca_crl == NULL) ? 0 : MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

conf->err is cleared only by config_defaults, so after conf_ca_chain(conf, ca, crl) a corrective conf_ca_chain(conf, ca, NULL) still fails every later setup and handshake. Clear the CRL error when the CA chain is set again.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

int ok = Connect(MBEDTLS_SSL_VERIFY_NONE) == 0;

for (i = 0; ok && i < sizeof(lens) / sizeof(lens[0]); i++) {
ok = mbedtls_ssl_write(&cli.ssl, buf, lens[i]) == RECORD_SZ &&

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

buf has RECORD_SZ bytes but write and read get lengths up to UINT_MAX + 6, so this stays in bounds only because each call moves one record. Name that assumption in a comment so a later change does not read an ASan report here as a library bug.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added comment

Comment thread src/mbedtls/ssl.c
if (ssl == NULL) {
return MBEDTLS_ERR_SSL_BAD_INPUT_DATA;
}
ret = wolfSSL_shutdown(ssl->ssl);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With ssl->ssl == NULL (setup never run or failed) this returns MBEDTLS_ERR_SSL_INTERNAL_ERROR from wolfSSL_shutdown(NULL); return MBEDTLS_ERR_SSL_BAD_INPUT_DATA as the other entry points do.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to return BAD_INPUT_DATA

Comment thread src/mbedtls/ssl.c Outdated
return 0;
}
/* wolfSSL cannot remove a name check, so a new name needs a new WOLFSSL */
return MbedSslNew(ssl);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Setup followed by set_hostname, the usual order, runs wolfSSL_new() and its RNG seeding twice per connection. Validate the name here and defer the rebuild to MbedSslStart(), as conf changes already are.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed with new flag hostname_changed

Comment thread src/mbedtls/ssl.c
{
int ret = 0;

if (ssl == NULL || ssl->conf == NULL || ssl->ssl == NULL) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After a handshake fails on a conf error, MbedSslNew() leaves ssl->ssl NULL, so fixing the conf and calling the handshake again returns BAD_INPUT_DATA until mbedtls_ssl_session_reset(). Either rebuild in MbedSslStart() when ssl->ssl is NULL or say in the README that a reset is needed.

@Frauschi
Frauschi merged commit 62d743d into wolfSSL:master Nov 16, 2026
98 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants