coaps_server.cpp

Go to the documentation of this file.

// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file coaps_server.cpp
 * @brief CoAP-over-DTLS server front-end - implementation. See coaps_server.h.
 */
 
#include "services/iot/coap/coaps_server.h"
 
#if PC_ENABLE_DTLS && PC_ENABLE_COAP
 
#include "network_drivers/presentation/security/dtls/dtls_conn.h"
#include "services/iot/coap/coaps.h" // pc_coaps_process()
#include "services/system/clock.h"   // pc_millis() - idle-reap clock (the DTLS PTO uses it internally too)
#include "shared_primitives/ring.h"  // pc_atomic (SPSC ingest-ring cursors)
#include <string.h>
 
#if defined(ARDUINO)
#include "network_drivers/transport/udp.h"
#endif
 
namespace
{
// Largest inbound datagram buffered: a ClientHello, a client Finished, or one CoAP application record
// (CoAP messages fit a single datagram, RFC 7252 §4.6). The server's outbound flight is larger but is
// sent straight out, never buffered here.
#ifndef PC_COAPS_MAX_DATAGRAM
#define PC_COAPS_MAX_DATAGRAM 1500
#endif
// Scratch for one poll's outbound datagram: a full server flight (ServerHello..Finished) or a sealed
// CoAP response. The Certificate-dominated flight is the largest thing written here.
#define PC_COAPS_OUT_CAP 2048
// The HelloRetryRequest cookie binds the peer's IPv4 address (4) + port (2); the transport is IPv4.
#define PC_COAPS_PEER_SER 6
 
// One buffered inbound datagram (payload + the peer it arrived from).
struct CoapsIngest
{
    uint8_t data[PC_COAPS_MAX_DATAGRAM];
    uint16_t len;
    char ip[16];
    uint16_t port;
};
 
// One pool slot: a DTLS connection plus the per-connection key material its config points at (so the
// config's pointers outlive the DtlsConn) and the peer to reply to.
struct CoapsSlot
{
    bool used;
    DtlsConn conn;
    DtlsServerConfig cfg; ///< per-slot config; its ephemeral/random pointers reference the buffers below
    uint8_t eph[32];      ///< fresh X25519 ephemeral private key for this handshake
    uint8_t srand[32];    ///< fresh ServerHello random for this handshake
    char peer_ip[16];
    uint16_t peer_port;
    uint32_t last_ms; ///< pc_millis() of the last inbound datagram (idle-reaping clock)
};
 
// The DtlsConn pool + the ingest ring, owned by one instance (internal linkage). Kept separate from
// the DRAM control state below so the large buffers group together (and could move to PSRAM like the
// HTTP/3 pool if a large pool were ever wanted). One named owner, unreachable cross-TU.
struct CoapsServerPoolCtx
{
    CoapsSlot pool[PC_COAPS_MAX_CONNS];
    CoapsIngest ring[PC_COAPS_INGEST_RING];
};
CoapsServerPoolCtx s_cpool;
 
// All CoAPs-server control state, owned by one instance (internal linkage): the ingest-ring cursors,
// the server identity + randomness source, the bound port / running flag, and (host) the outbound
// sink. One named owner, unreachable cross-TU.
struct CoapsServerCtx
{
    pc_atomic<size_t> ring_head; ///< producer (udp / ingest) advances
    pc_atomic<size_t> ring_tail; ///< consumer (poll) advances
    const uint8_t *cert_der = nullptr;
    size_t cert_len = 0;
    uint8_t ed25519_seed[32];
    uint8_t cookie_key[32];
    void (*rng)(uint8_t *out, size_t len) = nullptr;
    uint16_t port = 0;
    bool running = false;
#if !defined(ARDUINO)
    CoapsServerOutFn out_sink = nullptr;
    void *out_ctx = nullptr;
#endif
};
CoapsServerCtx s_coaps;
 
void copy_str(char *dst, size_t cap, const char *src)
{
    size_t n = 0;
    if (src)
    {
        while (src[n] && n + 1 < cap)
        {
            dst[n] = src[n];
            n++;
        }
    }
    dst[n] = 0;
}
 
// Serialize an IPv4 dotted-quad @p ip + @p port into the address the HelloRetryRequest cookie binds, so
// a cookie minted for one peer is worthless to another (RFC 9147 §5.1). Returns false on a malformed
// address (then no address is bound and the peer simply cannot take the HRR path).
bool serialize_peer(const char *ip, uint16_t port, uint8_t out[PC_COAPS_PEER_SER])
{
    uint32_t oct = 0;
    int octets = 0;
    int ndig = 0;
    int idx = 0;
    for (const char *p = ip;; p++)
    {
        if (*p >= '0' && *p <= '9')
        {
            oct = oct * 10 + (uint32_t)(*p - '0');
            ndig++;
            if (oct > 255 || ndig > 3)
            {
                return false;
            }
        }
        else if (*p == '.' || *p == 0)
        {
            if (ndig == 0)
            {
                return false;
            }
            out[idx++] = (uint8_t)oct;
            octets++;
            oct = 0;
            ndig = 0;
            if (*p == 0)
            {
                break;
            }
        }
        else
        {
            return false;
        }
    }
    if (octets != 4)
    {
        return false;
    }
    out[4] = (uint8_t)(port >> 8);
    out[5] = (uint8_t)(port & 0xFF);
    return true;
}
 
void server_send(const char *ip, uint16_t port, const uint8_t *data, size_t len)
{
#if defined(ARDUINO)
    pc_udp_listener_sendto(s_coaps.port, ip, port, data, len);
#else
    if (s_coaps.out_sink)
    {
        s_coaps.out_sink(s_coaps.out_ctx, data, len, ip, port);
    }
#endif
}
 
// --- ingest ring (SPSC: one producer fills, pc_coaps_server_poll consumes) ------------------------
bool ring_push(const uint8_t *dg, size_t len, const char *ip, uint16_t port)
{
    if (len == 0 || len > PC_COAPS_MAX_DATAGRAM)
    {
        return false;
    }
    size_t head = s_coaps.ring_head;
    size_t next = (head + 1) % PC_COAPS_INGEST_RING;
    if (next == (size_t)s_coaps.ring_tail)
    {
        return false; // ring full: drop (DTLS recovers via retransmission)
    }
    CoapsIngest *e = &s_cpool.ring[head];
    memcpy(e->data, dg, len);
    e->len = (uint16_t)len;
    copy_str(e->ip, sizeof e->ip, ip);
    e->port = port;
    s_coaps.ring_head = next; // publish after the record is fully written
    return true;
}
 
bool ring_pop(CoapsIngest *out)
{
    size_t tail = s_coaps.ring_tail;
    if (tail == (size_t)s_coaps.ring_head)
    {
        return false;
    }
    *out = s_cpool.ring[tail];
    s_coaps.ring_tail = (tail + 1) % PC_COAPS_INGEST_RING;
    return true;
}
 
// --- slot pool (keyed by peer address, or by connection id once one is negotiated) -------------
CoapsSlot *slot_by_peer(const char *ip, uint16_t port)
{
    for (uint8_t i = 0; i < PC_COAPS_MAX_CONNS; i++)
    {
        CoapsSlot *s = &s_cpool.pool[i];
        if (s->used && s->peer_port == port && strcmp(s->peer_ip, ip) == 0)
        {
            return s;
        }
    }
    return nullptr;
}
 
// Find the connection whose negotiated connection id (RFC 9146 / RFC 9147 §9) matches the id carried in
// an inbound CID record, so a peer that has roamed to a new address is still routed to its connection.
// @p cid points just past the record's first byte; @p avail is the bytes available there.
CoapsSlot *slot_by_cid(const uint8_t *cid, size_t avail)
{
    uint8_t sc[PC_DTLS_CID_MAX];
    for (uint8_t i = 0; i < PC_COAPS_MAX_CONNS; i++)
    {
        CoapsSlot *s = &s_cpool.pool[i];
        if (!s->used)
        {
            continue;
        }
        size_t sl = pc_dtls_conn_local_cid(&s->conn, sc);
        if (sl && sl <= avail && memcmp(cid, sc, sl) == 0)
        {
            return s;
        }
    }
    return nullptr;
}
 
CoapsSlot *alloc_slot()
{
    for (uint8_t i = 0; i < PC_COAPS_MAX_CONNS; i++)
    {
        if (!s_cpool.pool[i].used)
        {
            CoapsSlot *s = &s_cpool.pool[i];
            memset(s, 0, sizeof *s);
            s->used = true;
            return s;
        }
    }
    return nullptr;
}
 
// Open a connection for a datagram from a peer with no existing slot.
CoapsSlot *open_conn(const char *ip, uint16_t port)
{
    CoapsSlot *s = alloc_slot();
    if (!s)
    {
        return nullptr;
    }
    s_coaps.rng(s->eph, sizeof s->eph);     // fresh X25519 ephemeral private key
    s_coaps.rng(s->srand, sizeof s->srand); // fresh ServerHello random
    s->cfg.cert_der = s_coaps.cert_der;
    s->cfg.cert_len = s_coaps.cert_len;
    s->cfg.ed25519_seed = s_coaps.ed25519_seed;
    s->cfg.ephemeral_priv = s->eph;
    s->cfg.server_random = s->srand;
    s->cfg.cookie_key = s_coaps.cookie_key;
    uint8_t paddr[PC_COAPS_PEER_SER];
    bool ok = serialize_peer(ip, port, paddr);
    pc_dtls_conn_init(&s->conn, &s->cfg, ok ? paddr : nullptr, ok ? sizeof paddr : 0);
    copy_str(s->peer_ip, sizeof s->peer_ip, ip);
    s->peer_port = port;
    return s;
}
 
#if defined(ARDUINO)
void udp_ingest_cb(const uint8_t *data, size_t len, const pc_udp_peer *peer, void * /*ctx*/)
{
    char ip[16];
    uint16_t port = 0;
    if (!pc_udp_peer_addr(peer, ip, sizeof ip, &port))
    {
        return;
    }
    ring_push(data, len, ip, port);
}
#endif
 
// Route one ingested datagram to its peer slot (opening one for a fresh peer's ClientHello) and drive
// the DTLS handshake / CoAP exchange through the bridge.
void coaps_route_datagram(const CoapsIngest *ig, uint32_t now, uint8_t *out, size_t out_cap)
{
    // A DTLSCiphertext with the C bit (0b001C....) carries a connection id: route by it so a peer that
    // has roamed to a new address still reaches its connection (RFC 9146 / RFC 9147 §9). Otherwise route
    // by source address; a fresh peer's (plaintext) ClientHello opens a slot.
    // GCOVR_EXCL_BR_LINE below: ig->len >= 1 is always true here - ring_push (the ring's only producer)
    // rejects len == 0, so no entry ring_pop hands back can have a zero length.
    bool cid_rec = ig->len >= 1 && (ig->data[0] & 0xE0) == 0x20 && (ig->data[0] & 0x10); // GCOVR_EXCL_BR_LINE
    CoapsSlot *s = cid_rec ? slot_by_cid(ig->data + 1, ig->len - 1) : nullptr;
    if (!s)
    {
        s = slot_by_peer(ig->ip, ig->port);
    }
    if (!s && !cid_rec)
    {
        s = open_conn(ig->ip, ig->port);
    }
    if (!s)
    {
        return; // unknown connection id, or pool full: drop (the peer retransmits / DTLS PTO recovers)
    }
    // Address migration: a valid CID record from a new address updates where we send replies.
    if (cid_rec && (s->peer_port != ig->port || strcmp(s->peer_ip, ig->ip) != 0))
    {
        copy_str(s->peer_ip, sizeof s->peer_ip, ig->ip);
        s->peer_port = ig->port;
    }
    s->last_ms = now;
    int n = pc_coaps_process(&s->conn, ig->data, ig->len, out, out_cap);
    if (n > 0)
    {
        server_send(s->peer_ip, s->peer_port, out, (size_t)n);
    }
    else if (n < 0)
    {
        s->used = false; // fatal handshake error: free the slot
    }
}
 
// Fire the retransmission timer for a slot's outstanding flight, then reap it if the handshake failed or
// the connection has gone idle.
void coaps_service_slot(CoapsSlot *s, uint32_t now, uint8_t *out, size_t out_cap)
{
    if (!s->used)
    {
        return;
    }
    if (pc_dtls_conn_timeout_ms(&s->conn) == 0) // 0 == due now (-1 == no timer, >0 == still pending)
    {
        int n = pc_dtls_conn_on_timeout(&s->conn, out, out_cap);
        if (n > 0)
        {
            server_send(s->peer_ip, s->peer_port, out, (size_t)n);
        }
        // GCOVR_EXCL_BR_LINE below: n is never 0 here. pc_dtls_conn_on_timeout's two early "return 0" guards
        // (not-awaiting-reply/failed/done, not-yet-due) recompute the exact same fields and clock this call's
        // guard (timeout_ms(&s->conn) == 0) already evaluated true for, with no state change in between, so
        // neither can fire. Past those it either abandons the handshake (-1, retransmit ceiling) or fails to
        // build a record (-1), or returns flight_transmit's byte count, which is never 0: flight_arm (the only
        // place that sets awaiting_reply) always runs right after at least one flight_add call (1 message for
        // a HelloRetryRequest flight, 5 for the main flight), and nothing resets flight_count to 0 while
        // awaiting_reply stays true - so flight_transmit's loop always contributes at least one record's worth
        // of bytes when it succeeds.
        else if (n < 0) // GCOVR_EXCL_BR_LINE
        {
            s->used = false; // retransmission ceiling hit: abandon the handshake
            return;
        }
    }
    if (now - s->last_ms >= PC_COAPS_IDLE_MS) // wrap-safe idle delta (uint32_t arithmetic)
    {
        s->used = false;
    }
}
} // namespace
 
bool pc_coaps_server_begin(uint16_t port, const CoapsServerConfig *cfg)
{
    if (!cfg || !cfg->rng || !cfg->cert_der || cfg->cert_len == 0)
    {
        return false;
    }
    s_coaps.cert_der = cfg->cert_der;
    s_coaps.cert_len = cfg->cert_len;
    memcpy(s_coaps.ed25519_seed, cfg->ed25519_seed, sizeof s_coaps.ed25519_seed);
    memcpy(s_coaps.cookie_key, cfg->cookie_key, sizeof s_coaps.cookie_key);
    s_coaps.rng = cfg->rng;
    s_coaps.port = port ? port : PC_COAPS_PORT;
    for (uint8_t i = 0; i < PC_COAPS_MAX_CONNS; i++)
    {
        s_cpool.pool[i].used = false;
    }
    s_coaps.ring_head = 0;
    s_coaps.ring_tail = 0;
    s_coaps.running = true;
#if defined(ARDUINO)
    return pc_udp_listen(s_coaps.port, udp_ingest_cb, nullptr);
#else
    return true; // host: fed through pc_coaps_server_ingest()
#endif
}
 
void pc_coaps_server_poll()
{
    if (!s_coaps.running)
    {
        return;
    }
    uint32_t now = pc_millis();
    uint8_t out[PC_COAPS_OUT_CAP];
 
    // Drain queued datagrams: route each to its peer's slot (opening one for a new peer) and drive the
    // handshake / CoAP exchange through the bridge.
    CoapsIngest ig;
    while (ring_pop(&ig))
    {
        coaps_route_datagram(&ig, now, out, sizeof out);
    }
 
    // Fire the retransmission timer for any outstanding flight, then reap closed / idle connections.
    for (uint8_t i = 0; i < PC_COAPS_MAX_CONNS; i++)
    {
        coaps_service_slot(&s_cpool.pool[i], now, out, sizeof out);
    }
}
 
uint8_t pc_coaps_server_active_conns()
{
    uint8_t n = 0;
    for (uint8_t i = 0; i < PC_COAPS_MAX_CONNS; i++)
    {
        if (s_cpool.pool[i].used)
        {
            n++;
        }
    }
    return n;
}
 
void pc_coaps_server_stop()
{
    s_coaps.running = false;
    for (uint8_t i = 0; i < PC_COAPS_MAX_CONNS; i++)
    {
        s_cpool.pool[i].used = false;
    }
    s_coaps.ring_head = 0;
    s_coaps.ring_tail = 0;
}
 
#if !defined(ARDUINO)
void pc_coaps_server_set_out_sink_cb(CoapsServerOutFn fn, void *ctx)
{
    s_coaps.out_sink = fn;
    s_coaps.out_ctx = ctx;
}
 
bool pc_coaps_server_ingest(const uint8_t *datagram, size_t len, const char *ip, uint16_t port)
{
    return ring_push(datagram, len, ip, port);
}
#endif
 
#endif // PC_ENABLE_DTLS && PC_ENABLE_COAP