[gg582]

Phase 4 of the bare-metal STM32 epic (#447): HTTPS on the lwIP adapter.

Why not lwIP's altcp_tls

lwIP's altcp_tls_mbedtls includes mbedTLS 2.x-only headers (mbedtls/certs.h, mbedtls/ssl_internal.h). That holds in 2.2.1 and on current master, so it cannot use the vendored mbedTLS 3.6 LTS (lib/mbedtls). The adapter therefore drives mbedTLS 3.6 itself over the pcb, using mbedtls_ssl_set_bio.

API (include/cwist/sys/port/lwip.h)

cwist_lwip_tls *tls = cwist_lwip_tls_create(cert, sizeof cert, key, sizeof key); /* PEM: NUL counted */
cwist_lwip_config cfg;
cwist_lwip_config_init(&cfg);
cfg.port = 443;
cfg.tls = tls;                       /* NULL (default) = plaintext */
cwist_lwip_server *srv = cwist_lwip_listen(app, &cfg);
...
cwist_lwip_close(srv);
cwist_lwip_tls_destroy(tls);

• Build: TLS code compiles only with -DCWIST_LWIP_TLS and mbedTLS 3.6 linked: a TLS 1.2 server, X.509, PK parse, and CTR_DRBG.
• Without CWIST_LWIP_TLS: cwist_lwip_tls_create() returns NULL, and cwist_lwip_listen() with cfg.tls set fails instead of serving plaintext.
• Entropy: the DRBG is seeded only from cwist_port_entropy(). A failing hook makes create fail. A failing reseed later fails the handshake, so nothing runs on a guessable seed.
• Validation in create: the certificate and key are parsed and checked to be a pair with mbedtls_pk_check_pair.

How it works

• Receive: ciphertext from tcp_recv goes into a bounded per-connection queue (one full record plus slack). When the queue is full it is refused back to lwIP, so the TCP window throttles the peer. A pump runs the handshake, then decrypts into the same rx buffer and framing path the plaintext server uses. All request limits, 400/413/431/501 handling, keep-alive and pipelining behave the same.
• Send: responses go through mbedtls_ssl_write. Its records are copied into lwIP (TCP_WRITE_FLAG_COPY), so the serialized response is freed as soon as mbedTLS has taken all of it. WANT_WRITE is retried from tcp_sent and tcp_poll.
• Pipelining: the next request is picked up from tcp_sent, as on the plaintext path, never recursively. That keeps stack use flat however many requests are queued.
• 100 Continue: goes through the record layer.
• Closing: Connection: close sends close_notify before the TCP close. A failed handshake (not TLS, no shared suite, alert) aborts the connection.
• Unchanged: the plaintext path behaves exactly as before. Every TLS addition sits behind #ifdef CWIST_LWIP_TLS.

Tests

tests/lwip/cwist_test_mbedtls_config.h is a small TLS 1.2 server profile:

• ECDHE-ECDSA on P-256, AES-128-GCM, SHA-256
• 16 KB in / 4 KB out record buffers
• no filesystem, sockets, or platform entropy

tests/lwip/tls_client.{c,h} is an mbedTLS client over a loopback pcb. It verifies the server against the test CA for localhost. tests/lwip/test_tls_cert.h holds test-only self-signed P-256 credentials.

test_lwip_tls (in make test, host):

• context creation failures: bad PEM, mismatched key, failing entropy hook
• verified handshake with the expected cipher suite
• keep-alive, and two pipelined requests in one session
• Expect: 100-continue with the body split across records
• a 40 KB response, many 4 KB records through a 2-segment window, byte-exact
• a 413 over TLS that closes the connection
• Connection: close → close_notify → FIN
• a plaintext client on the TLS port: nothing is served in the clear

I confirmed the assertions are live by changing one expectation and watching it fail. The test is also clean under ASan/UBSan/LSan.

Under CWIST_TLS=mbedtls, libcwist already links the vendored mbedTLS, so the test reuses that copy (default config) instead of linking a second one.

hello-tls joins make baremetal-smoke and the size gate: the same stack on Cortex-M7 under qemu-arm. It passes with gcc 13.2 / newlib 4.4 / qemu 8.2 (the CI toolchain) and with gcc 14.2 / qemu 10.

hello-tls (Cortex-M7, -Os)	measured	budget
flash (CWIST + adapter + lwIP + mbedTLS + test client)	137,052	151,552
static RAM (mostly the test lwipopts.h pools and test buffers)	75,520	83,968
heap high-water (server and client sessions together)	106,640	118,784
stack high-water	8,344	9,216

After the handshake, server and client sessions together hold 49,980 bytes of heap. Both use the same record buffers (16 KB + 4 KB each), which puts a server-side TLS connection at about 25 KB. MBEDTLS_SSL_IN_CONTENT_LEN stays at 16 KB because clients may send full-size records: browsers do not negotiate max_fragment_length.

Local verification

• Tests: test_lwip_tls, test_lwip_adapter and test_baremetal_port pass.
• Bare-metal smoke and size gate: make baremetal-smoke and make baremetal-size-gate pass, with both toolchains.
• Adapter warnings: host and Cortex-M builds, each with and without CWIST_LWIP_TLS, under -Wall -Wextra: no warnings.
• Repo gates:
  • check_api_baseline: 2 functions and 1 type added
  • check_api_test_coverage, check_test_wiring, check_env_knobs, check_inline_exports, malloc_lint.sh: OK
  • cppcheck 2.13: no findings
• Full native make -k test: still running locally at the time of opening; result will follow in a comment.

Not in this PR

• TLS 1.3: mbedTLS 3.6 requires PSA crypto and an external RNG for it. Follow-up.
• Hardware crypto acceleration (CRYP/HASH/PKA): this is a firmware-side MBEDTLS_*_ALT choice. To be documented in Phase 6.
• Session resumption and tickets.
• Real hardware.

Refs #447

[gg582]

Full native make -k test on 153159db0 (default BoringSSL build): all targets pass, exit 0, including test_lwip_tls and test_lwip_adapter.