SSL/TLS Implementation for ESPAsyncWebServer

[dimecho]

No description provided.

[mathieucarbou]

Thanks! We’ll have a look as soon as we can!

[me-no-dev]

Since this is the AsyncTCP repo and not the WebServer one, please make the example use only AsyncTCP. WebServer example should be submitted to the WebServer repo, along with the changes necessary there.

Another thing for the example is to add a file called build_opt.h with one line inside -DASYNC_TCP_SSL_ENABLED=1 in order to turn on SSL. Same should be done for the WebServer example in the WebServer repo.

There are slight changes in mbedtls in the upcoming Arduino for ESP32 v4. They come from the updated mbedtls in ESP-IDF v6. Changes here should be compatible with both current Arduino (v3) and the upcoming one (v4).

Would be great if the example uses an actual certificate and key that can be used to directly build and test it (by CI and users)

[Copilot]

Pull request overview

Adds optional mbedTLS-based client/server TLS support to AsyncTCP for ESPAsyncWebServer HTTPS usage.

Changes:

• Adds TLS contexts, handshakes, encrypted I/O, and certificate handling.
• Exposes secure AsyncClient/AsyncServer APIs.
• Adds an HTTPS example and bumps the header version.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
src/AsyncTCPVersion.h	Updates the reported minor version.
src/AsyncTCPTLS.h	Declares the TLS context API.
src/AsyncTCPTLS.cpp	Implements mbedTLS over lwIP.
src/AsyncTCP.h	Exposes secure client/server interfaces.
src/AsyncTCP.cpp	Integrates TLS into connection and I/O flows.
examples/AsyncWebServerSSL/AsyncWebServerSSL.ino	Demonstrates an HTTPS web server.

Suppressed comments (2)

src/AsyncTCP.cpp:1190

• Returning ERR_ABRT does not abort anything here: _connected() is invoked by handle_async_event() and its return value is discarded at AsyncTCP.cpp:324. This and the two setup-failure returns above can leave a live PCB/failing TLS context after callbacks run. Explicitly call abort() or _close() on every failure path and avoid manually firing the disconnect callback twice.

        }
        if (_discard_cb) {
          _discard_cb(_discard_cb_arg, this);
        }
        return ERR_ABRT;

src/AsyncTCP.cpp:1279

• A handshake error received through this path only invokes callbacks and then returns ERR_OK; it never closes or aborts the still-live connection. Clients without a disconnect callback remain stuck and subsequent polls retry the failed TLS state. Match the poll failure path by closing the client (letting _close() issue the disconnect callback).

      async_tcp_log_e("SSL handshake failed in _recv: %d", ret);
      if (_error_cb) {
        _error_cb(_error_cb_arg, this, -60);
      }
      if (_discard_cb) {

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mathieucarbou]

Thanks a lof for having started this effort!

This is something that a few users were asking for, even if for a webserver on a MCU, support for SSL is quite a niche since any self-signed cert will cause issues on most clients / OS now. So this reduces valid use cases to ssl com with client cert, or use cases where the MCU would be exposed with a cert that is signed from a valid authority (internal company CA or valid internet authority).

So I am sure a lot of people will find it useful.

[dimecho]

Thanks a lof for having started this effort!

This is something that a few users were asking for, even if for a webserver on a MCU, support for SSL is quite a niche since any self-signed cert will cause issues on most clients / OS now. So this reduces valid use cases to ssl com with client cert, or use cases where the MCU would be exposed with a cert that is signed from a valid authority (internal company CA or valid internet authority).

So I am sure a lot of people will find it useful.

There are use cases for https (oauth2, MFA/Passkeys ...etc) work arounds TLS trust can be with domain to local pointers - example https://192.168.4.1.sslip.io