transport: finalise the vtable API

- net_posix.c calls recv and send directly rather than wolfIO_Recv and
  wolfIO_Send, which link only under USE_WOLFSSL_IO.
- WolfCertConnectFn and the connect_cb / connect_ctx fields are gone;
  dial() takes only the transport.
- The three config structs hold a WolfCertTransport by value, copied
  when the connection opens, and wolfcert_transport_fd() replaces
  wolfcert_transport_is_fd_backed().
- read and write take two timeout_ms modes, 0 and negative. ARCHITECTURE
  4.6 also states that honouring len is the transport's responsibility,
  and that wolfcert_http_session_fd() returns an O_NONBLOCK descriptor.
- Makefile.am keeps the conditional test_net entry with check_PROGRAMS.

Author: yosuke-wolfssl

Makefile.am

@@ -116,6 +116,9 @@ if WOLFCERT_BUILD_TESTS
 check_PROGRAMS = \
     test_smoke test_keygen test_csr test_store test_http test_transport \
     test_parse_negative test_tls_http
+if WOLFCERT_HAVE_BUILTIN_TRANSPORT
+check_PROGRAMS     += test_net
+endif
 
 test_smoke_SOURCES  = tests/unit/test_smoke.c
 test_smoke_LDADD    = libwolfcert.la $(WOLFSSL_LIBS)
@@ -125,9 +128,6 @@ 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)
 

docs/ARCHITECTURE.md

@@ -422,7 +422,7 @@ typedef struct WolfCertTransport {
 ```
 
 Set it on `WolfCertServerCfg.transport` (or `WolfCertHttpRequest` /
-`WolfCertHttpSessionCfg`). Leaving it `NULL` selects the built-in POSIX
+`WolfCertHttpSessionCfg`). Leaving it zeroed 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.
 
@@ -440,16 +440,27 @@ The contract:
   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.
+  something different from `connect`'s. It takes two values and no others.
   `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.
+  `WOLFCERT_ERR_WANT_WRITE` rather than wait. A negative value asks it to
+  block until bytes move. If your stack has its own receive or send timeout,
+  implement the negative case 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.
+- **Never write more than `len` bytes.** wolfCert rejects a count larger than
+  it asked for, but that only keeps the overrun out of its own buffers - the
+  write into yours has already happened, so honouring `len` is the transport's
+  responsibility and exceeding it is undefined.
 - **`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.
+  per-connection handle. Whatever it points at must outlive the connection.
+- **The struct itself need not.** Opening a connection copies it, so the config
+  may be a temporary — and a later change to your copy has no effect on a
+  connection already open.
 - **All four callbacks are required.** An incomplete vtable is rejected with
-  `WOLFCERT_ERR_BAD_ARG` before anything is dialled.
+  `WOLFCERT_ERR_BAD_ARG` before anything is dialled, and so is a half-filled
+  one: only a wholly zeroed `transport` asks for the built-in instance.
 
 TLS needs no extra work from the transport. wolfCert registers its own
 wolfSSL CBIO pair against the open connection, so records flow through the
@@ -459,15 +470,10 @@ 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`.
+that then leaves `transport` zeroed fails with `WOLFCERT_ERR_BAD_ARG`.
 
 ### 4.7 Putting it together
 

src/est/est_client.c

@@ -64,8 +64,6 @@ static void fill_common(const WolfCertServerCfg* srv, WolfCertHttpRequest* req)
     req->client_cert_len   = srv->client_cert_len;
     req->client_key        = srv->client_key;
     req->client_key_len    = srv->client_key_len;
-    req->connect_cb        = srv->connect_cb;
-    req->connect_ctx       = srv->connect_ctx;
     req->transport         = srv->transport;
 }
 
@@ -494,8 +492,6 @@ static int est_session_open_common(const WolfCertServerCfg* srv, int nonblocking
         .client_key_len            = srv->client_key_len,
         .allow_post_handshake_auth = srv->proto_opts.est.allow_post_handshake_auth,
         .nonblocking               = nonblocking,
-        .connect_cb                = srv->connect_cb,
-        .connect_ctx               = srv->connect_ctx,
         .transport                 = srv->transport,
         .heap                      = heap,
     };

src/http.c

@@ -314,58 +314,45 @@ static int basic_auth_header(const char* user, const char* pass,
 /* ---- TCP + TLS I/O ------------------------------------------------------ */
 
 typedef struct {
-    const WolfCertTransport* t;
+    WolfCertTransport t;
     void*        handle;
     WOLFSSL*     ssl;
     int          io_timeout_ms;   /* 0 nonblocking, < 0 unbounded */
     unsigned int connected : 1;
 } WolfCertConn;
 
-/* Open a connection and attach the transport that owns it. An explicit
- * transport wins; a legacy connect_cb is dialled here and adapted, since it
- * yields a descriptor rather than opening through a vtable. */
+/* Open a connection and take a copy of the transport that owns it. */
 static int dial(WolfCertConn* c, const char* host, int port, int timeout_ms,
-                const WolfCertTransport* transport,
-                WolfCertConnectFn connect_cb, void* connect_ctx)
+                const WolfCertTransport* transport)
 {
-    const WolfCertTransport* t = transport;
+    int cbs;
     int rc;
 
-#ifndef WOLFCERT_HAVE_BUILTIN_TRANSPORT
-    (void)connect_cb;
-    (void)connect_ctx;
+    cbs = (transport->connect != NULL) + (transport->read != NULL) +
+          (transport->write != NULL) + (transport->disconnect != NULL);
 
-    if (t == NULL)
+    if (cbs == 4) {
+        c->t = *transport;
+    }
+    else if (cbs != 0 || transport->ctx != NULL) {
         return WOLFCERT_ERR(WOLFCERT_ERR_BAD_ARG, "http",
-            "this build has no built-in transport");
-#else
-    if (t == NULL && connect_cb != NULL) {
-        rc = wolfcert_legacy_connect(connect_cb, connect_ctx, host, port,
-                                     timeout_ms, &c->handle);
-        if (rc != WOLFCERT_OK)
-            return rc;
-
-        c->t         = &wolfcert_legacy_transport;
-        c->connected = 1;
-        return WOLFCERT_OK;
+            "transport must set all four callbacks, or nothing at all to take "
+            "the built-in one");
     }
-
-    if (t == NULL)
-        t = &wolfcert_posix_transport;
-#endif
-
-    /* Validate the whole vtable */
-    if (t->connect == NULL || t->read == NULL || t->write == NULL ||
-        t->disconnect == NULL)
+    else {
+#ifdef WOLFCERT_HAVE_BUILTIN_TRANSPORT
+        c->t = wolfcert_posix_transport;
+#else
         return WOLFCERT_ERR(WOLFCERT_ERR_BAD_ARG, "http",
-            "transport must supply connect, read, write and disconnect");
+            "this build has no built-in transport");
+#endif
+    }
 
-    rc = t->connect(t->ctx, host, port, timeout_ms, &c->handle);
+    rc = c->t.connect(c->t.ctx, host, port, timeout_ms, &c->handle);
     if (rc != WOLFCERT_OK)
         return rc < 0 ? rc : WOLFCERT_ERR(WOLFCERT_ERR_IO, "http",
             "transport connect returned %d, not 0 or a WOLFCERT_ERR_*", rc);
 
-    c->t         = t;
     c->connected = 1;
     return WOLFCERT_OK;
 }
@@ -374,7 +361,7 @@ static int dial(WolfCertConn* c, const char* host, int port, int timeout_ms,
 static void conn_close(WolfCertConn* c)
 {
     if (c->connected) {
-        (void)c->t->disconnect(c->t->ctx, c->handle);
+        (void)c->t.disconnect(c->t.ctx, c->handle);
         c->connected = 0;
     }
 }
@@ -440,8 +427,8 @@ static int conn_write(WolfCertConn* c, const void* buf, size_t len)
             w = wolfSSL_write(c->ssl, p + n, (int)(len - n));
         }
         else {
-            w = c->t->write(c->t->ctx, c->handle, p + n, len - n,
-                            c->io_timeout_ms);
+            w = c->t.write(c->t.ctx, c->handle, p + n, len - n,
+                           c->io_timeout_ms);
             if (w > 0 && (size_t)w > len - n)
                 return WOLFCERT_ERR_IO;
         }
@@ -467,8 +454,8 @@ static int wolfcert_cbio_recv(WOLFSSL* ssl, char* buf, int sz, void* ctx)
     if (c == NULL || sz <= 0)
         return WOLFSSL_CBIO_ERR_GENERAL;
 
-    r = c->t->read(c->t->ctx, c->handle, (uint8_t*)buf, (size_t)sz,
-                   c->io_timeout_ms);
+    r = c->t.read(c->t.ctx, c->handle, (uint8_t*)buf, (size_t)sz,
+                  c->io_timeout_ms);
     if (r > sz)
         return WOLFSSL_CBIO_ERR_GENERAL;
     if (r > 0)
@@ -499,8 +486,8 @@ static int wolfcert_cbio_send(WOLFSSL* ssl, char* buf, int sz, void* ctx)
     if (c == NULL || sz <= 0)
         return WOLFSSL_CBIO_ERR_GENERAL;
 
-    r = c->t->write(c->t->ctx, c->handle, (const uint8_t*)buf, (size_t)sz,
-                    c->io_timeout_ms);
+    r = c->t.write(c->t.ctx, c->handle, (const uint8_t*)buf, (size_t)sz,
+                   c->io_timeout_ms);
     if (r > sz)
         return WOLFSSL_CBIO_ERR_GENERAL;
     if (r > 0)
@@ -524,10 +511,9 @@ static int conn_read(WolfCertConn* c, void* buf, size_t len)
     int r;
 
     if (c->ssl == NULL) {
-        r = c->t->read(c->t->ctx, c->handle, (uint8_t*)buf, len,
-                       c->io_timeout_ms);
-        /* A 0 spins the read-until-close loop; a count above len means the
-         * transport already overran the buffer. Neither is passed on. */
+        r = c->t.read(c->t.ctx, c->handle, (uint8_t*)buf, len,
+                      c->io_timeout_ms);
+        /* Turn a 0 into a close, and refuse a count larger than len. */
         if (r == 0)
             return WOLFCERT_ERR_CONN_CLOSED;
         if (r > 0 && (size_t)r > len)
@@ -1167,10 +1153,6 @@ int wolfcert_http_request(const WolfCertHttpRequest* req, WolfCertHttpResponse*
     if (req == NULL || resp == NULL || req->url == NULL || req->method == NULL)
         return WOLFCERT_ERR_BAD_ARG;
 
-    if (req->connect_cb != NULL && req->transport != NULL)
-        return WOLFCERT_ERR(WOLFCERT_ERR_BAD_ARG, "http",
-            "set either connect_cb or transport, not both");
-
     memset(resp, 0, sizeof(*resp));
     void* heap = req->heap ? req->heap : wolfcert_default_heap();
     resp->heap = heap;
@@ -1182,12 +1164,12 @@ int wolfcert_http_request(const WolfCertHttpRequest* req, WolfCertHttpResponse*
     if (rc != WOLFCERT_OK)
         return rc;
 
-    WolfCertConn c = { 0 };
+    WolfCertConn c;
     WOLFSSL_CTX* ctx = NULL;
 
+    memset(&c, 0, sizeof(c));
     c.io_timeout_ms = -1;
-    rc = dial(&c, u.host, u.port, req->timeout_ms, req->transport,
-              req->connect_cb, req->connect_ctx);
+    rc = dial(&c, u.host, u.port, req->timeout_ms, &req->transport);
     if (rc != WOLFCERT_OK) {
         wolfcert_http_url_free(&u);
         return rc;
@@ -1243,10 +1225,6 @@ int wolfcert_http_session_open(const WolfCertHttpSessionCfg* cfg,
     if (cfg == NULL || cfg->base_url == NULL || out == NULL)
         return WOLFCERT_ERR_BAD_ARG;
 
-    if (cfg->connect_cb != NULL && cfg->transport != NULL)
-        return WOLFCERT_ERR(WOLFCERT_ERR_BAD_ARG, "http",
-            "set either connect_cb or transport, not both");
-
     void* heap = cfg->heap ? cfg->heap : wolfcert_default_heap();
 
     WolfCertHttpSession* s = (WolfCertHttpSession*)WOLFCERT_XMALLOC(sizeof(*s), heap);
@@ -1266,7 +1244,7 @@ int wolfcert_http_session_open(const WolfCertHttpSessionCfg* cfg,
 
     s->conn.io_timeout_ms = cfg->nonblocking ? 0 : -1;
     rc = dial(&s->conn, s->base.host, s->base.port, cfg->timeout_ms,
-              cfg->transport, cfg->connect_cb, cfg->connect_ctx);
+              &cfg->transport);
     if (rc != WOLFCERT_OK) {
         wolfcert_http_session_close(s);
         return rc;
@@ -1320,12 +1298,10 @@ int wolfcert_http_session_fd(const WolfCertHttpSession* s)
 #ifdef WOLFCERT_HAVE_BUILTIN_TRANSPORT
     if (s == NULL || !s->conn.connected)
         return -1;
-    if (!wolfcert_transport_is_fd_backed(s->conn.t))
-        return -1;
 
-    return (int)(intptr_t)s->conn.handle;
+    return wolfcert_transport_fd(&s->conn.t, s->conn.handle);
 #else
-    (void)s;   /* no fd-backed transport exists in this build */
+    (void)s;   /* no descriptor-backed transport exists in this build */
     return -1;
 #endif
 }
@@ -1457,8 +1433,8 @@ static int nb_write(WolfCertConn* c, const uint8_t* buf, size_t len, size_t* off
             return WOLFCERT_ERR_IO;
         }
 
-        int r = c->t->write(c->t->ctx, c->handle, buf + *off, len - *off,
-                            c->io_timeout_ms);
+        int r = c->t.write(c->t.ctx, c->handle, buf + *off, len - *off,
+                           c->io_timeout_ms);
         if (r > 0 && (size_t)r > len - *off)
             return WOLFCERT_ERR_IO;
         if (r > 0) {
@@ -1539,9 +1515,9 @@ static int nb_read_some(WolfCertHttpSession* s, int* ended)
         return WOLFCERT_ERR_IO;
     }
 
-    int r = s->conn.t->read(s->conn.t->ctx, s->conn.handle,
-                            s->sm_rx + s->sm_rx_len,
-                            WOLFCERT_HTTP_READ_CHUNK, s->conn.io_timeout_ms);
+    int r = s->conn.t.read(s->conn.t.ctx, s->conn.handle,
+                           s->sm_rx + s->sm_rx_len,
+                           WOLFCERT_HTTP_READ_CHUNK, s->conn.io_timeout_ms);
     if (r > 0) {
         if ((size_t)r > WOLFCERT_HTTP_READ_CHUNK)
             return WOLFCERT_ERR_IO;

src/internal.h

@@ -311,14 +311,11 @@ WOLFCERT_TEST_VIS void wolfcert_hex_encode(const uint8_t* in, size_t in_len,
 WOLFCERT_TEST_VIS int wolfcert_parse_ip(const char* s, uint8_t out[16],
                                         size_t* out_len);
 
-/* Built-in POSIX transport, and the adapter used when a config still sets the
- * deprecated connect_cb. Both are fd-backed, which session_fd() relies on. */
+/* Built-in POSIX transport. */
 extern const WolfCertTransport wolfcert_posix_transport;
-extern const WolfCertTransport wolfcert_legacy_transport;
-int  wolfcert_transport_is_fd_backed(const WolfCertTransport* t);
-int  wolfcert_legacy_connect(WolfCertConnectFn cb, void* cb_ctx,
-                             const char* host, int port, int timeout_ms,
-                             void** conn);
+/* The descriptor behind a wolfcert_posix_transport connection; -1 for a
+ * handle any other transport minted. */
+int  wolfcert_transport_fd(const WolfCertTransport* t, void* conn);
 
 int  wolfcert_pem_cert_to_der(const uint8_t* pem, size_t pem_len,
                               WolfCertBuffer* out_der, void* heap);