Add the WolfCertTransport to extend the portability on embedded platforms

.github/workflows/nightly.yml

@@ -46,6 +46,8 @@ jobs:
           - { name: cmake-mldsa-44off,     os: ubuntu-latest, build: cmake,    wolfssl: mldsa-44off }
           - { name: cmake-mldsa-65off,     os: ubuntu-latest, build: cmake,    wolfssl: mldsa-65off }
           - { name: cmake-mldsa-87off,     os: ubuntu-latest, build: cmake,    wolfssl: mldsa-87off }
+          # ---- Platform pieces compiled out (transport/store gates) ----
+          - { name: cmake-no-builtin-transport, os: ubuntu-latest, build: cmake, wolfssl: full, cmake_extra: "-DWOLFCERT_ENABLE_BUILTIN_TRANSPORT=OFF -DWOLFCERT_ENABLE_POSIX_STORE=OFF -DWOLFCERT_ENABLE_CLI=OFF -DWOLFCERT_ENABLE_SERVER=OFF" }
           # ---- Constrained builds (unit tests only: single-thread / no-malloc) ----
           - { name: cmake-static-mem,      os: ubuntu-latest, build: cmake,    wolfssl: static-mem, cmake_extra: -DWOLFCERT_ENABLE_SERVER=OFF, ctest_exclude: "http|tls|roundtrip" }
           - { name: cmake-no-malloc,       os: ubuntu-latest, build: cmake,    wolfssl: no-malloc,  ctest_exclude: "http|tls|roundtrip|est" }

.github/workflows/pr.yml

@@ -103,6 +103,19 @@ jobs:
             os: ubuntu-latest
             build: cmake
             wolfssl: mldsa-87off
+          # ---- Platform pieces compiled out (the transport/store gates) ----
+          - name: cmake-no-builtin-transport
+            os: ubuntu-latest
+            build: cmake
+            wolfssl: full
+            # Neither the CLI nor the test server can supply a transport, so
+            # both build systems reject them here. The socket-driven tests
+            # exit 77 (skipped) on their own; nothing needs excluding.
+            cmake_extra: >-
+              -DWOLFCERT_ENABLE_BUILTIN_TRANSPORT=OFF
+              -DWOLFCERT_ENABLE_POSIX_STORE=OFF
+              -DWOLFCERT_ENABLE_CLI=OFF
+              -DWOLFCERT_ENABLE_SERVER=OFF
           # ---- Constrained builds (unit tests only: single-thread / no-malloc) --
           - name: cmake-static-mem
             os: ubuntu-latest
@@ -224,6 +237,27 @@ jobs:
           cmake --build build -j "$(nproc)"
           ctest --test-dir build -j "$(nproc)" --output-on-failure
 
+  no-posix-arm:
+    name: freestanding ARM compile (no POSIX)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install the bare-metal ARM toolchain
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-arm-none-eabi
+      # Headers only: nothing is compiled from wolfSSL and nothing is linked,
+      # so this needs no wolfSSL build and no prefix cache.
+      - name: Check out wolfSSL headers
+        run: |
+          git clone --depth 1 --branch "$WOLFSSL_REF" \
+            https://github.com/wolfSSL/wolfssl "$RUNNER_TEMP/wolfssl"
+      - name: Compile every portable source for Cortex-M4
+        run: |
+          scripts/ci/compile-freestanding.sh \
+            --wolfssl-src "$RUNNER_TEMP/wolfssl"
+
   negative-config:
     name: negative-config (fail-fast gates)
     runs-on: ubuntu-latest

CLAUDE.md

@@ -67,7 +67,7 @@ wolfSSL configure:
     --enable-certext --enable-keygen --enable-ecc --enable-cryptocb \
     --enable-base64encode --enable-ed25519 --enable-ed448 \
     --enable-mldsa --enable-postauth --enable-opensslextra \
-    --enable-ip-alt-name --enable-des3 \
+    --enable-ip-alt-name --enable-des3 --enable-sni \
     CPPFLAGS="-DWOLFSSL_ALT_NAMES -DWOLFSSL_CERT_NAME_ALL"
 ```
 

CMakeLists.txt

@@ -38,6 +38,9 @@ option(WOLFCERT_ENABLE_SERVER  "Build the minimal EST/SCEP test server" ON)
 option(WOLFCERT_ENABLE_CLI     "Build wolfcert-client / wolfcert-server" ON)
 option(WOLFCERT_ENABLE_TESTS   "Build unit and integration tests"       OFF)
 option(WOLFCERT_ENABLE_EXAMPLES "Build example programs"                OFF)
+option(WOLFCERT_ENABLE_POSIX_STORE "Build the POSIX file storage backend" ON)
+option(WOLFCERT_ENABLE_BUILTIN_TRANSPORT
+    "Build the built-in POSIX socket transport" ON)
 option(WOLFCERT_WERROR         "Treat warnings as errors"               OFF)
 # Header-based configuration (the user_settings.h analogue of wolfSSL's
 # WOLFSSL_USER_SETTINGS). When ON, wolfCert does not generate or install
@@ -49,6 +52,19 @@ option(WOLFCERT_WERROR         "Treat warnings as errors"               OFF)
 option(WOLFCERT_USER_SETTINGS  "Take feature config from a user-supplied user_settings.h instead of the generated options.h" OFF)
 set(WOLFCERT_USER_SETTINGS_DIR "" CACHE PATH
     "Directory containing user_settings.h (used when WOLFCERT_USER_SETTINGS=ON)")
+
+if(NOT WOLFCERT_ENABLE_BUILTIN_TRANSPORT)
+    if(WOLFCERT_ENABLE_CLI)
+        message(FATAL_ERROR "WOLFCERT_ENABLE_CLI needs "
+            "WOLFCERT_ENABLE_BUILTIN_TRANSPORT: the CLI cannot supply a "
+            "custom transport")
+    endif()
+    if(WOLFCERT_ENABLE_SERVER)
+        message(FATAL_ERROR "WOLFCERT_ENABLE_SERVER needs "
+            "WOLFCERT_ENABLE_BUILTIN_TRANSPORT: its round-trip tests drive "
+            "the client over real sockets")
+    endif()
+endif()
 # ----- wolfSSL ---------------------------------------------------------------
 # Optional convenience: -DWITH_WOLFSSL=PATH points at a wolfSSL install
 # prefix. Adds it to CMAKE_PREFIX_PATH (for find_package CONFIG mode) and
@@ -249,6 +265,11 @@ if(NOT WOLFCERT_USER_SETTINGS)
     _wc_opt(WOLFCERT_OPT_EST     "${WOLFCERT_ENABLE_EST}"    WOLFCERT_HAVE_EST)
     _wc_opt(WOLFCERT_OPT_SCEP    "${WOLFCERT_ENABLE_SCEP}"   WOLFCERT_HAVE_SCEP)
     _wc_opt(WOLFCERT_OPT_SERVER  "${WOLFCERT_ENABLE_SERVER}" WOLFCERT_HAVE_SERVER)
+    _wc_opt(WOLFCERT_OPT_POSIX_STORE "${WOLFCERT_ENABLE_POSIX_STORE}"
+            WOLFCERT_HAVE_POSIX_STORE)
+    _wc_opt(WOLFCERT_OPT_BUILTIN_TRANSPORT
+            "${WOLFCERT_ENABLE_BUILTIN_TRANSPORT}"
+            WOLFCERT_HAVE_BUILTIN_TRANSPORT)
     _wc_opt(WOLFCERT_OPT_RSA     "${WOLFCERT_HAVE_RSA}"      WOLFCERT_HAVE_RSA)
     _wc_opt(WOLFCERT_OPT_ECC     "${WOLFCERT_HAVE_ECC}"      WOLFCERT_HAVE_ECC)
     _wc_opt(WOLFCERT_OPT_ED25519 "${WOLFCERT_HAVE_ED25519}"  WOLFCERT_HAVE_ED25519)
@@ -269,9 +290,12 @@ set(WOLFCERT_SOURCES
     src/csr.c
     src/store.c
     src/http.c
-    src/net_posix.c
     src/client.c)
 
+if(WOLFCERT_ENABLE_BUILTIN_TRANSPORT)
+    list(APPEND WOLFCERT_SOURCES src/net_posix.c)
+endif()
+
 if(WOLFCERT_ENABLE_EST OR WOLFCERT_ENABLE_SCEP)
     list(APPEND WOLFCERT_SOURCES src/pkcs7_util.c)
 endif()
@@ -410,4 +434,6 @@ install(FILES "${CMAKE_CURRENT_BINARY_DIR}/wolfcert.pc"
 
 message(STATUS "wolfCert ${PROJECT_VERSION}: EST=${WOLFCERT_ENABLE_EST}, "
     "SCEP=${WOLFCERT_ENABLE_SCEP}, server=${WOLFCERT_ENABLE_SERVER}, "
-    "cli=${WOLFCERT_ENABLE_CLI}, user_settings=${WOLFCERT_USER_SETTINGS}")
+    "cli=${WOLFCERT_ENABLE_CLI}, posix_store=${WOLFCERT_ENABLE_POSIX_STORE}, "
+    "builtin_transport=${WOLFCERT_ENABLE_BUILTIN_TRANSPORT}, "
+    "user_settings=${WOLFCERT_USER_SETTINGS}")

Makefile.am

@@ -25,9 +25,12 @@ libwolfcert_la_SOURCES = \
     src/csr.c \
     src/store.c \
     src/http.c \
-    src/net_posix.c \
     src/client.c
 
+if WOLFCERT_HAVE_BUILTIN_TRANSPORT
+libwolfcert_la_SOURCES += src/net_posix.c
+endif
+
 if WOLFCERT_BUILD_TESTS
 AM_CPPFLAGS += -DWOLFCERT_BUILD_TESTING=1
 endif
@@ -111,7 +114,7 @@ endif
 
 if WOLFCERT_BUILD_TESTS
 check_PROGRAMS = \
-    test_smoke test_keygen test_csr test_store test_net test_http \
+    test_smoke test_keygen test_csr test_store test_http test_transport \
     test_parse_negative test_tls_http
 
 test_smoke_SOURCES  = tests/unit/test_smoke.c
@@ -122,6 +125,12 @@ test_csr_SOURCES    = tests/unit/test_csr.c
 test_csr_LDADD      = libwolfcert.la $(WOLFSSL_LIBS)
 test_store_SOURCES  = tests/unit/test_store.c
 test_store_LDADD    = libwolfcert.la $(WOLFSSL_LIBS)
+if WOLFCERT_HAVE_BUILTIN_TRANSPORT
+check_PROGRAMS     += test_net
+endif
+test_transport_SOURCES = tests/unit/test_transport.c
+test_transport_LDADD   = libwolfcert.la $(WOLFSSL_LIBS)
+
 test_net_SOURCES    = tests/unit/test_net.c
 test_net_LDADD      = libwolfcert.la $(WOLFSSL_LIBS)
 test_http_SOURCES   = tests/unit/test_http.c

README.md

@@ -68,7 +68,7 @@ optional key types wolfCert picks up when available:
     --enable-keygen --enable-ecc --enable-cryptocb --enable-base64encode \
     --enable-ed25519 --enable-ed448 --enable-mldsa \
     --enable-postauth --enable-opensslextra --enable-ip-alt-name \
-    --enable-des3 \
+    --enable-des3 --enable-sni \
     CPPFLAGS="-DWOLFSSL_ALT_NAMES -DWOLFSSL_CERT_NAME_ALL"
 ```
 
@@ -155,7 +155,11 @@ All `WolfCertBuffer` outputs remember which heap they came from, so the same
   `RenewalReq`, plus `pkiStatus=PENDING` + `GetCertInitial` polling.
 - **Transport:** HTTP/1.1 over wolfSSL TLS 1.3/1.2 (trust anchors, SNI,
   mutual TLS), keep-alive sessions, TLS 1.3 post-handshake auth, and an
-  optional non-blocking mode for `poll`/`epoll`/`kqueue` event loops.
+  optional non-blocking mode for `poll`/`epoll`/`kqueue` event loops. Every
+  byte goes through the `WolfCertTransport` vtable, TLS records included, so
+  a non-BSD-sockets stack (FreeRTOS+TCP, NetX, lwIP, wolfIP) needs one small
+  glue file and no wolfCert change; the POSIX transport is the default
+  instance and can be compiled out.
 - **Storage:** file-based cert/key store with atomic writes and 0600 key-file
   mode; pluggable via the `WolfCertStoreOps` vtable.
 - **Test servers + CLIs** for Linux/macOS (`wolfcert-server`,

cli/wolfcert_client.c

@@ -633,8 +633,7 @@ static int cmd_getcacerts(int argc, char** argv)
     if (ret == 0 && check_proto_only_opts(&opts, p) != 0)
         ret = 1;
 
-    WolfCertServerCfg srv = { .protocol = p, .server_url = opts.url,
-                              .connect_cb = wolfcert_posix_connect };
+    WolfCertServerCfg srv = { .protocol = p, .server_url = opts.url };
 
     if (ret == 0) {
         fill_trust(&opts, &srv, &trust_hold);
@@ -712,8 +711,7 @@ static int cmd_enroll(int argc, char** argv)
     /* Build the server cfg first - needed by --csrattrs-auto before we
      * pick a key type. The key cfg + meta are populated below, then
      * optionally overlaid with /csrattrs hints, then used to generate. */
-    WolfCertServerCfg srv = { .protocol = p, .server_url = opts.url,
-                              .connect_cb = wolfcert_posix_connect };
+    WolfCertServerCfg srv = { .protocol = p, .server_url = opts.url };
     WolfCertCertMeta meta = { .subject_dn = opts.subject,
                               .san_dns = opts.san_dns, .san_dns_len = opts.san_dns_len,
                               .san_ip = opts.san_ip, .san_ip_len = opts.san_ip_len,
@@ -1049,8 +1047,7 @@ static int cmd_reenroll(int argc, char** argv)
         }
     }
 
-    WolfCertServerCfg srv = { .protocol = p, .server_url = opts.url,
-                              .connect_cb = wolfcert_posix_connect };
+    WolfCertServerCfg srv = { .protocol = p, .server_url = opts.url };
 
     if (ret == 0) {
         fill_trust(&opts, &srv, &trust_hold);
@@ -1132,8 +1129,7 @@ static int cmd_getnextca(int argc, char** argv)
         ret = 1;
     }
 
-    WolfCertServerCfg srv = { .protocol = p, .server_url = opts.url,
-                              .connect_cb = wolfcert_posix_connect };
+    WolfCertServerCfg srv = { .protocol = p, .server_url = opts.url };
 
     if (ret == 0) {
         fill_trust(&opts, &srv, &trust_hold);

configure.ac

@@ -79,6 +79,29 @@ AC_ARG_ENABLE([cli],
     [enable_cli=$enableval], [enable_cli=yes])
 AM_CONDITIONAL([WOLFCERT_BUILD_CLI], [test "x$enable_cli" = "xyes"])
 
+AC_ARG_ENABLE([builtin-transport],
+    [AS_HELP_STRING([--disable-builtin-transport],
+        [do not build the built-in POSIX socket transport])],
+    [enable_builtin_transport=$enableval], [enable_builtin_transport=yes])
+AM_CONDITIONAL([WOLFCERT_HAVE_BUILTIN_TRANSPORT],
+    [test "x$enable_builtin_transport" = "xyes"])
+
+AS_IF([test "x$enable_builtin_transport" != "xyes"], [
+  AS_IF([test "x$enable_cli" = "xyes"],
+    [AC_MSG_ERROR([--enable-cli needs the built-in transport: the CLI
+cannot supply a custom one])])
+  AS_IF([test "x$enable_server" = "xyes"],
+    [AC_MSG_ERROR([--enable-server needs the built-in transport: its
+round-trip tests drive the client over real sockets])])
+])
+
+# store.c is always compiled; only its POSIX file backend is gated, so this
+# needs no AM_CONDITIONAL.
+AC_ARG_ENABLE([posix-store],
+    [AS_HELP_STRING([--disable-posix-store],
+        [do not build the POSIX file storage backend])],
+    [enable_posix_store=$enableval], [enable_posix_store=yes])
+
 AC_ARG_ENABLE([tests],
     [AS_HELP_STRING([--enable-tests], [build unit and integration tests])],
     [enable_tests=$enableval], [enable_tests=no])
@@ -261,6 +284,10 @@ AS_IF([test "x$have_rsa" = "xno" && test "x$have_ecc" = "xno" \
 WOLFCERT_OPT([WOLFCERT_OPT_EST],     [$enable_est],    [WOLFCERT_HAVE_EST])
 WOLFCERT_OPT([WOLFCERT_OPT_SCEP],    [$enable_scep],   [WOLFCERT_HAVE_SCEP])
 WOLFCERT_OPT([WOLFCERT_OPT_SERVER],  [$enable_server], [WOLFCERT_HAVE_SERVER])
+WOLFCERT_OPT([WOLFCERT_OPT_POSIX_STORE], [$enable_posix_store],
+             [WOLFCERT_HAVE_POSIX_STORE])
+WOLFCERT_OPT([WOLFCERT_OPT_BUILTIN_TRANSPORT], [$enable_builtin_transport],
+             [WOLFCERT_HAVE_BUILTIN_TRANSPORT])
 WOLFCERT_OPT([WOLFCERT_OPT_RSA],     [$have_rsa],      [WOLFCERT_HAVE_RSA])
 WOLFCERT_OPT([WOLFCERT_OPT_ECC],     [$have_ecc],      [WOLFCERT_HAVE_ECC])
 WOLFCERT_OPT([WOLFCERT_OPT_ED25519], [$have_ed25519],  [WOLFCERT_HAVE_ED25519])
@@ -312,6 +339,8 @@ AC_MSG_NOTICE([
                     Ed448=$have_ed448 ML-DSA=$have_mldsa
     TLS 1.2/1.3   : $have_tls12 / $have_tls13
     Test server   : $enable_server
+    POSIX store   : $enable_posix_store
+    Builtin transp: $enable_builtin_transport
     User settings : $enable_user_settings
     CLI tools     : $enable_cli
     Tests         : $enable_tests

docs/ARCHITECTURE.md

@@ -343,6 +343,10 @@ Key points:
 - **DNS and the initial TCP connect stay synchronous.** Only socket operations
   *after* the session is open are non-blocking; if you can't afford a blocking
   connect, resolve and connect the socket yourself.
+- **The descriptor comes from the built-in transport.** `*_session_fd()`
+  returns `-1` on a caller-supplied `WolfCertTransport`, which has no
+  descriptor to hand out; drive the loop from whatever readiness signal your
+  stack offers instead. See [section 4.6](#46-pluggable-transport).
 - **Re-invoke with identical arguments after a WANT-\*.** The session remembers
   its in-flight state; don't mutate the request/response between calls.
 - **One in-flight request per session** — pipelining is not supported.
@@ -398,7 +402,77 @@ if (rc != WOLFCERT_OK) {
 
 The message string is valid until the next wolfCert call on the same thread.
 
-### 4.6 Putting it together
+### 4.6 Pluggable transport
+
+wolfCert owns no socket. Every byte on the wire - TLS records and plain HTTP
+alike - moves through a `WolfCertTransport`, so a target with no BSD sockets
+needs one small glue file in *its own* tree and no change to wolfCert:
+
+```c
+typedef struct WolfCertTransport {
+    int  (*connect)(void* ctx, const char* host, int port,
+                    int timeout_ms, void** conn);
+    int  (*read)(void* ctx, void* conn, uint8_t* buf, size_t len,
+                 int timeout_ms);
+    int  (*write)(void* ctx, void* conn, const uint8_t* buf, size_t len,
+                  int timeout_ms);
+    int  (*disconnect)(void* ctx, void* conn);
+    void* ctx;
+} WolfCertTransport;
+```
+
+Set it on `WolfCertServerCfg.transport` (or `WolfCertHttpRequest` /
+`WolfCertHttpSessionCfg`). Leaving it `NULL` selects the built-in POSIX
+instance in `src/net_posix.c`, which is an ordinary implementation of this
+same vtable rather than a privileged path.
+
+The contract:
+
+- **The handle is opaque.** `connect` writes it to `*conn`; wolfCert never
+  dereferences, compares or NULL-tests it, so `0` is a perfectly valid handle
+  (a wolfIP descriptor starts there). It is passed back verbatim.
+- **`read` / `write` return a positive byte count**, or a negative
+  `WOLFCERT_ERR_*`. Never `0`: an orderly peer close is
+  `WOLFCERT_ERR_CONN_CLOSED`, which is what terminates a response body that
+  has neither `Content-Length` nor chunking.
+- **`connect`'s `timeout_ms` is the caller's**, passed through from
+  `WolfCertServerCfg.timeout_ms` / `WolfCertHttpRequest.timeout_ms`. A value
+  above zero bounds the whole connect attempt. Zero or less imposes no limit
+  of wolfCert's, leaving the stack's own default.
+- **`read` / `write`'s `timeout_ms` carries the blocking mode**, and means
+  something different from `connect`'s. wolfCert passes only two values.
+  `0` asks the call never to block: return `WOLFCERT_ERR_WANT_READ` or
+  `WOLFCERT_ERR_WANT_WRITE` rather than wait. `-1` asks it to block until
+  bytes move. If your stack has its own receive or send timeout, implement
+  `-1` with a call that lets it apply, rather than an unbounded wait around a
+  non-blocking transfer: the second shape silently discards whatever the
+  application configured.
+- **`disconnect` runs exactly once per successful `connect`**, on every error
+  path included. A failed `connect` is never paired with one.
+- **`ctx` is transport-wide** (the stack instance, say), distinct from the
+  per-connection handle. The transport struct must outlive its connections.
+- **All four callbacks are required.** An incomplete vtable is rejected with
+  `WOLFCERT_ERR_BAD_ARG` before anything is dialled.
+
+TLS needs no extra work from the transport. wolfCert registers its own
+wolfSSL CBIO pair against the open connection, so records flow through the
+same `read`/`write` as plain HTTP:
+
+```
+wolfSSL_read/write -> wolfcert_cbio_recv/send -> t->read / t->write -> your stack
+```
+
+`WolfCertServerCfg.connect_cb` is the deprecated predecessor: it yields a
+socket descriptor rather than an opaque handle, which is exactly what a
+non-socket stack cannot supply. It still works, adapted internally onto the
+POSIX byte path, but setting both it and `transport` is `WOLFCERT_ERR_BAD_ARG`.
+
+Building with `WOLFCERT_ENABLE_BUILTIN_TRANSPORT=OFF` (CMake) or
+`--disable-builtin-transport` (autoconf) drops `src/net_posix.c` from the
+library entirely, so a target with no sockets links no socket code. A config
+that then leaves `transport` NULL fails with `WOLFCERT_ERR_BAD_ARG`.
+
+### 4.7 Putting it together
 
 ```c
 /* 1. Startup */
@@ -449,7 +523,7 @@ wolfcert_cleanup();
 
 ## 5. Extension points
 
-Three small vtables carry all of wolfCert's pluggability. Each is a "fill in a
+Four small vtables carry all of wolfCert's pluggability. Each is a "fill in a
 struct, no library changes" extension:
 
 - **`WolfCertKeyAlg`** (`src/key_algs.c`) — algorithm dispatch. Adding a key
@@ -461,6 +535,11 @@ struct, no library changes" extension:
   `read` / `write` / `remove` callbacks and a private `ctx`; keys are opaque
   strings. Shipped backends: POSIX files (atomic write, 0600 key mode) and
   in-memory. See [section 4.4](#44-pluggable-storage-for-flash--nvm).
+- **`WolfCertTransport`** (`wolfcert/types.h`) — the bytes on the wire. Supply
+  `connect` / `read` / `write` / `disconnect` and a private `ctx` to run
+  wolfCert on a non-BSD-sockets stack; TLS rides the same callbacks through an
+  internal CBIO bridge. The built-in POSIX transport is one instance of it.
+  See [section 4.6](#46-pluggable-transport).
 - **`WolfCertServerOps`** (`src/internal.h`) — test-server protocol dispatch.
   The EST and SCEP handlers are exposed through
   `wolfcert_est_server_ops()` / `wolfcert_scep_server_ops()` factories; a third