Add SUIT directive-fetch (host callback) and minimal status report for networked update

Author: aidangarske

docs/SUIT.md

@@ -37,7 +37,9 @@ verify objects (lean, `WOLFCOSE_LEAN_VERIFY`). Fine-tuning macros:
 | `SUIT_HAVE_ENCRYPTION` | decrypt COSE_Encrypt0 payloads on install (AES-GCM); enables AES-GCM in the build |
 | `SUIT_DEVICE_VENDOR_ID` / `SUIT_DEVICE_CLASS_ID` | this device's identity (brace initializers) for the vendor/class conditions |
 | `SUIT_KEY_SLOT` | fallback trust-anchor slot when the COSE_Sign1 carries no key id |
-| `SUIT_HAVE_FETCH` / `SUIT_HAVE_TRY_EACH` / `SUIT_HAVE_RUN_SEQUENCE` | optional commands |
+| `SUIT_HAVE_FETCH` | enable directive-fetch; the host supplies an `ops->fetch` callback that retrieves the payload by uri (e.g. wolfUpdate transport) |
+| `SUIT_HAVE_REPORT` | build `suit_report_encode()`, a compact `{ result, sequence }` status record an update server reads to learn the outcome |
+| `SUIT_HAVE_TRY_EACH` / `SUIT_HAVE_RUN_SEQUENCE` | optional commands |
 
 ## Architecture
 
@@ -90,8 +92,11 @@ CBOR/COSE tooling (test B); it is not a full draft-34 implementation.
 
 - Unrecognized (or known-but-unsupported) commands are **default-denied** (the
   sequence fails), as a SUIT processor must, rather than silently skipped.
-- Not implemented (and rejected if present): directive-fetch, severable members,
-  try-each / run-sequence / swap, dependencies/trust-domains, SUIT Reports.
+- Optional, built only when their macro is set: directive-fetch
+  (`SUIT_HAVE_FETCH`, via a host callback) and a compact status report
+  (`SUIT_HAVE_REPORT`, not the full draft-suit-report COSE attestation).
+- Not implemented (and rejected if present): severable members,
+  try-each / run-sequence / swap, dependencies/trust-domains.
 
 ## Status
 
@@ -110,8 +115,18 @@ image or content larger than the partition space, and an out-of-range component
 index), and **key-id selection** (the COSE_Sign1 `kid` picks the trust anchor
 via the keystore, like the TLV path's pubkey hint).
 
-Follow-ups: `directive-fetch` (networked payload retrieval, wolfUpdate), and the
-optional commands (`try-each` / `run-sequence` / `swap`).
+Networked update support: `directive-fetch` (`SUIT_HAVE_FETCH`) retrieves the
+payload by uri through a host callback, and `suit_report_encode()`
+(`SUIT_HAVE_REPORT`) emits a compact status record, so a server (e.g. wolfUpdate)
+can pull images and learn outcomes. Remaining optional commands: `try-each` /
+`run-sequence` / `swap`.
+
+Production readiness: this feature is experimental and off by default. Before
+enabling it in a shipping product the gate is, at minimum: fuzz the manifest
+parser and complete a security review (the manifest is attacker-controlled),
+hardware-test the boot/swap path, and provision the content-encryption key by
+key-wrap rather than handing it in raw. Encryption (`SUIT_HAVE_ENCRYPTION`) is
+not production-ready until the key-wrap step exists.
 
 This PR is gated on the wolfCOSE fixes in wolfSSL/wolfCOSE PR #53; the submodule
 is pinned to that work and should be repinned to the wolfCOSE v1.0 tag before

include/suit.h

@@ -46,6 +46,7 @@
 #define SUIT_E_INSTALL           (-9)
 #define SUIT_E_ROLLBACK          (-10)
 #define SUIT_E_BOUNDS            (-11)
+#define SUIT_E_FETCH             (-12)
 
 /* SUIT_Envelope map keys (IANA SUIT Envelope Elements). */
 enum suit_envelope_key {
@@ -173,6 +174,8 @@ struct suit_params {
     size_t         classIdLen;
     const uint8_t* content;        /* directive-write content */
     size_t         contentLen;
+    const uint8_t* uri;            /* directive-fetch source (tstr bytes) */
+    size_t         uriLen;
     uint64_t       imageSize;
     size_t         sourceComponent;
     int            componentSlot;
@@ -186,6 +189,9 @@ struct suit_component_ops {
     int (*hash)(void* ctx, size_t idx, uint8_t* out, size_t outLen);
     int (*write)(void* ctx, size_t idx, const uint8_t* src, size_t len);
     int (*copy)(void* ctx, size_t idx, size_t srcIdx);
+    /* Retrieve the payload at uri into component idx (SUIT_HAVE_FETCH). The host
+     * (e.g. wolfUpdate transport) owns the network/storage; NULL if unsupported. */
+    int (*fetch)(void* ctx, size_t idx, const uint8_t* uri, size_t uriLen);
 };
 
 /* Command-sequence interpreter state. Fixed-size, no heap. */
@@ -213,6 +219,22 @@ int suit_open(struct suit_manifest* m, const uint8_t* env, size_t len);
 int suit_verify_auth(struct suit_manifest* m);
 int suit_process(struct suit_context* ctx, struct suit_manifest* m);
 
+#ifdef SUIT_HAVE_REPORT
+/* Minimal SUIT status report keys: a compact outcome record for an update server
+ * (e.g. wolfUpdate), not the full draft-suit-report COSE attestation. */
+enum suit_report_key {
+    SUIT_REPORT_RESULT          = 1, /* int: 0 on success, else the SUIT_E_* code */
+    SUIT_REPORT_SEQUENCE_NUMBER = 2  /* uint: the manifest sequence number */
+};
+
+/* Encode a status report for a finished suit_process into the caller's buffer as
+ * CBOR. result is the suit_process return code. Writes the encoded length to
+ * written. Zero allocation: out is caller-owned. */
+int suit_report_encode(const struct suit_context* ctx,
+    const struct suit_manifest* m, int result,
+    uint8_t* out, size_t outLen, size_t* written);
+#endif /* SUIT_HAVE_REPORT */
+
 /* wolfBoot entry point: open + authenticate + process a staged SUIT envelope.
  * The caller supplies the component I/O ops and this device's identity. */
 int wolfBoot_suit_verify(const uint8_t* env, size_t envLen,

options.mk

@@ -1602,6 +1602,10 @@ ifeq ($(WOLFBOOT_SUIT),1)
   ifeq ($(SUIT_HAVE_FETCH),1)
     CFLAGS+=-DSUIT_HAVE_FETCH
   endif
+  ifeq ($(SUIT_HAVE_REPORT),1)
+    CFLAGS+=-DSUIT_HAVE_REPORT
+    OBJS+=./src/suit/suit_report.o
+  endif
   ifeq ($(SUIT_HAVE_TRY_EACH),1)
     CFLAGS+=-DSUIT_HAVE_TRY_EACH
   endif

src/suit/suit_process.c

@@ -144,6 +144,15 @@ static int suit_override(struct suit_context* ctx, WOLFCOSE_CBOR_CTX* c)
                 ctx->params.contentLen = dataLen;
             }
         }
+        else if (pkey == (int64_t)SUIT_PARAM_URI) {
+            if (wc_CBOR_DecodeTstr(c, &data, &dataLen) != WOLFCOSE_SUCCESS) {
+                ret = SUIT_E_PARSE;
+            }
+            else {
+                ctx->params.uri = data;
+                ctx->params.uriLen = dataLen;
+            }
+        }
         else if (pkey == (int64_t)SUIT_PARAM_SOURCE_COMPONENT) {
             if (wc_CBOR_DecodeUint(c, &uval) != WOLFCOSE_SUCCESS) {
                 ret = SUIT_E_PARSE;
@@ -313,6 +322,23 @@ static int suit_run_sequence(struct suit_context* ctx, const uint8_t* seq,
                     ctx->params.contentLen);
             }
         }
+#ifdef SUIT_HAVE_FETCH
+        else if (cmd == (int64_t)SUIT_DIR_FETCH) {
+            if (wc_CBOR_Skip(&c) != WOLFCOSE_SUCCESS) {
+                ret = SUIT_E_PARSE;
+            }
+            else if ((ctx->ops == NULL) || (ctx->ops->fetch == NULL)) {
+                ret = SUIT_E_UNSUPPORTED;
+            }
+            else if (ctx->params.uri == NULL) {
+                ret = SUIT_E_FETCH;
+            }
+            else if (ctx->ops->fetch(ctx->ops->ctx, ctx->componentIndex,
+                    ctx->params.uri, ctx->params.uriLen) != 0) {
+                ret = SUIT_E_FETCH;
+            }
+        }
+#endif
         else if (cmd == (int64_t)SUIT_DIR_COPY) {
             if (wc_CBOR_Skip(&c) != WOLFCOSE_SUCCESS) {
                 ret = SUIT_E_PARSE;

src/suit/suit_report.c

@@ -0,0 +1,81 @@
+/* suit_report.c
+ *
+ * Copyright (C) 2025 wolfSSL Inc.
+ *
+ * This file is part of wolfBoot.
+ *
+ * wolfBoot is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * wolfBoot is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
+ */
+/**
+ * @file suit_report.c
+ * @brief Minimal SUIT status report: a compact CBOR { result, sequence-number }
+ * record an update server (e.g. wolfUpdate) reads to learn an update's outcome
+ * without a second boot. Not the full draft-suit-report COSE attestation.
+ */
+#include "suit.h"
+
+#if defined(WOLFBOOT_SUIT) && defined(SUIT_HAVE_REPORT)
+
+#include <wolfcose/wolfcose.h>
+
+int suit_report_encode(const struct suit_context* ctx,
+    const struct suit_manifest* m, int result,
+    uint8_t* out, size_t outLen, size_t* written)
+{
+    int ret = SUIT_SUCCESS;
+    WOLFCOSE_CBOR_CTX c;
+
+    (void)ctx;
+    if ((m == NULL) || (out == NULL) || (written == NULL)) {
+        return SUIT_E_INVALID_ARG;
+    }
+
+    c.buf = out;
+    c.cbuf = NULL;
+    c.bufSz = outLen;
+    c.idx = 0;
+
+    if (wc_CBOR_EncodeMapStart(&c, 2) != WOLFCOSE_SUCCESS) {
+        ret = SUIT_E_BOUNDS;
+    }
+    if (ret == SUIT_SUCCESS) {
+        if (wc_CBOR_EncodeInt(&c, (int64_t)SUIT_REPORT_RESULT)
+                != WOLFCOSE_SUCCESS) {
+            ret = SUIT_E_BOUNDS;
+        }
+    }
+    if (ret == SUIT_SUCCESS) {
+        if (wc_CBOR_EncodeInt(&c, (int64_t)result) != WOLFCOSE_SUCCESS) {
+            ret = SUIT_E_BOUNDS;
+        }
+    }
+    if (ret == SUIT_SUCCESS) {
+        if (wc_CBOR_EncodeInt(&c, (int64_t)SUIT_REPORT_SEQUENCE_NUMBER)
+                != WOLFCOSE_SUCCESS) {
+            ret = SUIT_E_BOUNDS;
+        }
+    }
+    if (ret == SUIT_SUCCESS) {
+        if (wc_CBOR_EncodeUint(&c, m->sequenceNumber) != WOLFCOSE_SUCCESS) {
+            ret = SUIT_E_BOUNDS;
+        }
+    }
+    if (ret == SUIT_SUCCESS) {
+        *written = c.idx;
+    }
+    return ret;
+}
+
+#endif /* WOLFBOOT_SUIT && SUIT_HAVE_REPORT */

tests/suit_host_test.sh

@@ -18,6 +18,7 @@ cd "$ROOT"
 # wolfCOSE is built lean for ES256 sign+verify only, matching a minimal host
 # wolfSSL; the verify path itself is what wolfBoot uses on-target.
 "$CC" -DWOLFBOOT_SUIT -DSUIT_INSTALL_DIRECTIVES -DSUIT_HAVE_ENCRYPTION \
+    -DSUIT_HAVE_FETCH -DSUIT_HAVE_REPORT \
     -DWOLFCOSE_NO_ENCRYPT -DWOLFCOSE_NO_MAC0 \
     -DWOLFCOSE_NO_MAC -DWOLFCOSE_NO_SIGN -DWOLFCOSE_NO_RECIPIENTS \
     -DWOLFCOSE_NO_MLDSA -DWOLFCOSE_NO_KEY_ENCODE -DWOLFCOSE_NO_KEY_DECODE \
@@ -27,6 +28,7 @@ cd "$ROOT"
     -isystem "$WOLFSSL_DIR/include" \
     tests/suit_test.c \
     src/suit/suit_parse.c src/suit/suit_verify.c src/suit/suit_process.c \
+    src/suit/suit_report.c \
     lib/wolfCOSE/src/wolfcose.c lib/wolfCOSE/src/wolfcose_cbor.c \
     -L"$WOLFSSL_DIR/lib" -lwolfssl -o "$OUT"