Add STM32Cube pack support docs and on device test for wolfCOSE (#61)

Author: lealem47

IDE/STM32Cube/README.md

@@ -0,0 +1,45 @@
+# wolfCOSE for STM32Cube
+
+wolfCOSE is a zero-allocation C implementation of CBOR (RFC 8949) and COSE
+(RFC 9052/9053) built on top of wolfCrypt. It ships as an STM32Cube pack,
+`I-CUBE-wolfCOSE`, which provides wolfCOSE as an STM32 middleware and depends
+on the wolfSSL pack (`I-CUBE-wolfSSL`) for wolfCrypt.
+
+This directory holds the files the pack builds from:
+
+- `wolfcose_test.c` / `wolfcose_test.h`: a self test that runs a `COSE_Sign1`
+  ES256 sign and verify and prints the result. It is built by the pack `Test`
+  component. Call `wolfCOSETest()` from your application once the clocks and
+  console are initialized; it returns `0` on success.
+- `default_conf.ftl`: the STM32CubeMX configuration template for the pack.
+
+## Dependency
+
+Install the wolfSSL pack (`I-CUBE-wolfSSL`, version 5.9.2 or later) first and
+enable `wolfCrypt: Core`. wolfCOSE uses wolfCrypt for hashing, signing, and AEAD.
+See the
+[wolfSSL STM32Cube README](https://github.com/wolfSSL/wolfssl/blob/master/IDE/STM32Cube/README.md)
+for the wolfSSL pack documentation and install instructions.
+
+## Enabling in STM32CubeMX
+
+1. `Help`, `Manage embedded software packages`, `From Local...` and install
+   the wolfSSL pack, then this wolfCOSE pack.
+2. Enable the RNG peripheral under `Pinout & Configuration`, `Security`, `RNG`.
+   Signing needs entropy, and `wc_GenerateSeed()` fails without it.
+3. In the project `.ioc`, open `Software Packs`, `Select Components`, expand
+   `wolfCOSE` and check `Core` (and `wolfSSL`, `wolfCrypt: Core`). To run the
+   on device self test, also check `wolfCOSE` `Test`.
+4. In the `Software Packs` configuration category, enable the wolfCOSE pack.
+5. Generate code and build.
+
+## Configuration
+
+wolfCOSE is configured through the wolfSSL `user_settings.h` (included before
+`wolfcose/settings.h`). Algorithm support such as `WOLFCOSE_ENABLE_ES384`,
+`WOLFCOSE_ENABLE_ES512`, and `WOLFCOSE_ENABLE_MLDSA` requires the matching
+wolfCrypt features (`HAVE_ECC`, `WOLFSSL_SHA384/512`, `WOLFSSL_HAVE_MLDSA`).
+
+See the wolfCOSE `examples/` for sign1, mac0, and encrypt0 usage, and the
+[STM32Cube wiki page](https://github.com/wolfSSL/wolfCOSE/wiki/STM32Cube) for
+the full walkthrough including a ready to run NUCLEO-H563ZI project.

IDE/STM32Cube/default_conf.ftl

@@ -0,0 +1,81 @@
+[#ftl]
+/**
+  ******************************************************************************
+  * File Name          : ${name}
+  * Description        : This file provides code for the configuration
+  *                      of the ${name} instances.
+  ******************************************************************************
+[@common.optinclude name=mxTmpFolder+"/license.tmp"/][#--include License text --]
+  ******************************************************************************
+  */
+[#assign s = name]
+[#assign toto = s?replace(".","_")]
+[#assign toto = toto?replace("/","")]
+[#assign toto = toto?replace("-","_")]
+[#assign inclusion_protection = toto?upper_case]
+/* Define to prevent recursive inclusion -------------------------------------*/
+#ifndef __${inclusion_protection}__
+#define __${inclusion_protection}__
+
+#ifdef __cplusplus
+ extern "C" {
+#endif
+
+
+/* Includes ------------------------------------------------------------------*/
+[#if includes??]
+[#list includes as include]
+#include "${include}"
+[/#list]
+[/#if]
+
+[#-- SWIPdatas is a list of SWIPconfigModel --]  
+[#list SWIPdatas as SWIP]  
+[#-- Global variables --]
+[#if SWIP.variables??]
+	[#list SWIP.variables as variable]
+extern ${variable.value} ${variable.name};
+	[/#list]
+[/#if]
+
+[#-- Global variables --]
+
+[#assign instName = SWIP.ipName]   
+[#assign fileName = SWIP.fileName]   
+[#assign version = SWIP.version]   
+
+/**
+	MiddleWare name : ${instName}
+	MiddleWare fileName : ${fileName}
+	MiddleWare version : ${version}
+*/
+[#if SWIP.defines??]
+	[#list SWIP.defines as definition]	
+/*---------- [#if definition.comments??]${definition.comments}[/#if] -----------*/
+#define ${definition.name} #t#t ${definition.value} 
+[#if definition.description??]${definition.description} [/#if]
+	[/#list]
+[/#if]
+
+
+
+[/#list]
+
+#define WOLFCOSE_STM32_CUBEMX
+
+/* wolfCOSE takes its crypto configuration from the wolfSSL user_settings.h. */
+
+#if defined(WOLFCOSE_CONF_DEBUG) && WOLFCOSE_CONF_DEBUG == 1
+    #define DEBUG_WOLFCOSE
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* ${inclusion_protection}_H */
+
+/**
+  * @}
+  */
+
+/*****END OF FILE****/

IDE/STM32Cube/wolfcose_test.c

@@ -0,0 +1,103 @@
+/* wolfcose_test.c
+ *
+ * Copyright (C) 2026 wolfSSL Inc.
+ *
+ * This file is part of wolfCOSE.
+ *
+ * wolfCOSE 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.
+ *
+ * wolfCOSE 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, see <https://www.gnu.org/licenses/>.
+ */
+
+#include "wolfcose_test.h"
+
+#include <stdio.h>
+#include <string.h>
+
+int wolfCOSETest(void)
+{
+#if defined(WOLFCOSE_HAVE_ES256) && defined(WOLFCOSE_SIGN1_SIGN) && \
+    defined(WOLFCOSE_SIGN1_VERIFY)
+    WOLFCOSE_KEY key;
+    ecc_key eccKey;
+    WC_RNG rng;
+    WOLFCOSE_HDR hdr;
+    const uint8_t payload[] = "wolfCOSE STM32 self test";
+    uint8_t scratch[WOLFCOSE_MAX_SCRATCH_SZ];
+    uint8_t out[512];
+    const uint8_t* decPayload = NULL;
+    size_t payloadLen = sizeof(payload) - 1u;
+    size_t outLen = 0;
+    size_t decPayloadLen = 0;
+    int rngInited = 0;
+    int eccInited = 0;
+    int keyInited = 0;
+    int ret;
+
+    printf("Running wolfCOSE test (COSE_Sign1 ES256)...\n");
+
+    ret = wc_InitRng(&rng);
+    if (ret == 0) {
+        rngInited = 1;
+        ret = wc_ecc_init(&eccKey);
+    }
+    if (ret == 0) {
+        eccInited = 1;
+        ret = wc_ecc_make_key(&rng, 32, &eccKey);
+    }
+    if (ret == 0) {
+        ret = wc_CoseKey_Init(&key);
+    }
+    if (ret == 0) {
+        keyInited = 1;
+        ret = wc_CoseKey_SetEcc(&key, WOLFCOSE_CRV_P256, &eccKey);
+    }
+    if (ret == 0) {
+        ret = wc_CoseSign1_Sign(&key, WOLFCOSE_ALG_ES256,
+            NULL, 0, payload, payloadLen, NULL, 0, NULL, 0,
+            scratch, sizeof(scratch), out, sizeof(out), &outLen, &rng);
+    }
+    if (ret == 0) {
+        ret = wc_CoseSign1_Verify(&key, out, outLen, NULL, 0, NULL, 0,
+            scratch, sizeof(scratch), &hdr, &decPayload, &decPayloadLen);
+    }
+    if (ret == 0) {
+        if ((decPayload == NULL) || (decPayloadLen != payloadLen) ||
+            (memcmp(decPayload, payload, decPayloadLen) != 0) ||
+            (hdr.alg != WOLFCOSE_ALG_ES256)) {
+            ret = -1;
+        }
+    }
+
+    if (keyInited != 0) {
+        wc_CoseKey_Free(&key);
+    }
+    if (eccInited != 0) {
+        (void)wc_ecc_free(&eccKey);
+    }
+    if (rngInited != 0) {
+        (void)wc_FreeRng(&rng);
+    }
+
+    if (ret == 0) {
+        printf("wolfCOSE test: PASS (COSE_Sign1 %lu bytes)\n", (unsigned long)outLen);
+    }
+    else {
+        printf("wolfCOSE test: FAIL, ret %d\n", ret);
+    }
+    return ret;
+#else
+    /* ES256 COSE_Sign1 not compiled in; report not run so it is not read as pass */
+    printf("wolfCOSE test: needs ES256 with COSE_Sign1 sign and verify\n");
+    return -1;
+#endif
+}

IDE/STM32Cube/wolfcose_test.h

@@ -0,0 +1,38 @@
+/* wolfcose_test.h
+ *
+ * Copyright (C) 2026 wolfSSL Inc.
+ *
+ * This file is part of wolfCOSE.
+ *
+ * wolfCOSE 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.
+ *
+ * wolfCOSE 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, see <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef WOLFCOSE_TEST_H_
+#define WOLFCOSE_TEST_H_
+
+#include <wolfcose/wolfcose.h>
+#include <wolfssl/wolfcrypt/ecc.h>
+#include <wolfssl/wolfcrypt/random.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+int wolfCOSETest(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* WOLFCOSE_TEST_H_ */

README.md

@@ -17,6 +17,7 @@ wolfCOSE is a lightweight C library implementing [CBOR (RFC 8949)](https://www.r
   (`WOLFCOSE_LEAN_VERIFY_MLDSA`) and **~35.8 KB** sign + verify, within about 1 KB of classical ES256. The wolfCOSE portion
   alone is **4.6 KB** and **~6.6 KB** respectively. See [Footprint](https://github.com/wolfSSL/wolfCOSE/wiki/Footprint)
 - **Path to FIPS 140-3**: via wolfCrypt **FIPS Certificate #4718** (sole crypto dependency)
+- **STM32Cube ready**: available as a drop-in STM32Cube pack (`I-CUBE-wolfCOSE`) for STM32CubeMX and STM32CubeIDE, so STM32 devices get COSE and CBOR out of the box (see [STM32Cube](https://github.com/wolfSSL/wolfCOSE/wiki/STM32Cube))
 
 ## Supported Algorithms
 
@@ -193,6 +194,7 @@ Full documentation is available in the [Wiki](https://github.com/wolfSSL/wolfCOS
 - [Testing](https://github.com/wolfSSL/wolfCOSE/wiki/Testing): Test infrastructure, coverage, and failure injection
 - [MISRA Compliance](https://github.com/wolfSSL/wolfCOSE/wiki/MISRA-Compliance): MISRA C:2012 and C:2023 compliance status and deviation rationale
 - [Project Structure](https://github.com/wolfSSL/wolfCOSE/wiki/Project-Structure): Source file layout
+- [STM32Cube](https://github.com/wolfSSL/wolfCOSE/wiki/STM32Cube): Install and run wolfCOSE as an STM32Cube pack on device
 
 ## Release Notes
 

docs/Home.md

@@ -36,6 +36,7 @@ It uses [wolfSSL](https://www.wolfssl.com/) as the cryptographic backend and is
 | [[Footprint]] | Size and speed numbers, desktop and on-device |
 | [[Testing]] | Unit tests, coverage, and failure injection |
 | [[Project Structure]] | Source code layout and file descriptions |
+| [[STM32Cube]] | Install and run wolfCOSE as an STM32Cube pack on device |
 | [[Release Notes]] | Per-version changelog and release highlights |
 
 ## Supported Message Types

docs/STM32Cube.md

@@ -0,0 +1,85 @@
+# STM32Cube
+
+wolfCOSE ships as an STM32Cube pack, `I-CUBE-wolfCOSE`, so it drops into any
+STM32CubeMX or STM32CubeIDE project without manual source integration. The pack
+provides wolfCOSE as an STM32 middleware and uses the wolfSSL pack
+(`I-CUBE-wolfSSL`) for all cryptography.
+
+Supported cores: Cortex-M0, M0+, M3, M4, M7, M23, M33, M55, and STM32MP1.
+
+## Prerequisites
+
+- STM32CubeMX, plus STM32CubeIDE or another toolchain to build.
+- The wolfSSL pack, `I-CUBE-wolfSSL` 5.9.2 or later. wolfCOSE depends on
+  wolfCrypt for hashing, signing, and AEAD.
+- A board with a hardware RNG and a UART for console output.
+
+## Install the packs
+
+1. Download the wolfSSL pack
+   ([I-CUBE-wolfSSL.pack](https://www.wolfssl.com/files/ide/I-CUBE-wolfSSL.pack))
+   and the wolfCOSE pack
+   ([I-CUBE-wolfCOSE.pack](https://www.wolfssl.com/files/ide/I-CUBE-wolfCOSE.pack)).
+2. In STM32CubeMX, open `Help`, `Manage embedded software packages`,
+   `From Local...`, and install the wolfSSL pack first, then the wolfCOSE pack.
+
+## Add wolfCOSE to a project
+
+1. Open or create a project `.ioc` for your board.
+2. Enable the RNG peripheral under `Pinout & Configuration`, `Security`, `RNG`.
+   Signing needs entropy, and `wc_GenerateSeed()` fails without it.
+3. Open `Software Packs`, `Select Components`.
+4. Enable `wolfSSL` `wolfCrypt` `Core` and `wolfCOSE` `Core`. To run the
+   on device self test, also enable `wolfCOSE` `Test`.
+5. In the `Software Packs` configuration category, enable each pack.
+6. Generate code and build with your toolchain.
+
+## Configure algorithms
+
+wolfCOSE reads its configuration from the wolfSSL `user_settings.h`, included
+before `wolfcose/settings.h`. Enable the wolfCrypt features that match the COSE
+algorithms you use:
+
+- ES256: `HAVE_ECC`, `WOLFSSL_SHA256`
+- ES384 or ES512: add `WOLFSSL_SHA384` or `WOLFSSL_SHA512`
+- ML-DSA (RFC 9964): `WOLFSSL_HAVE_MLDSA`
+- Encrypt0 AEAD: `HAVE_AESGCM`, or `HAVE_CHACHA` with `HAVE_POLY1305`
+- MAC0: HMAC, which is on by default with SHA support
+
+If a required wolfCrypt feature is missing, `wolfcose/settings.h` raises a
+compile error naming it.
+
+## Run on a device
+
+The `Test` component builds `wolfcose_test.c`, a self test that runs a
+`COSE_Sign1` sign and verify and reports the result over your configured
+console. Call `wolfCOSETest()` from your application once `main` has initialized
+the clocks and console.
+
+A ready to run example for the NUCLEO-H563ZI board lives in
+[wolfssl-examples-stm32](https://github.com/wolfSSL/wolfssl-examples-stm32),
+with a pre-configured `.ioc`: install the packs, open the `.ioc`, generate,
+add the glue and software-crypto config from that example's README, build,
+flash, and watch the console.
+
+Verified on NUCLEO-H563ZI hardware, the console prints:
+
+```
+== wolfCOSE NUCLEO-H563ZI ==
+Running wolfCOSE test (COSE_Sign1 ES256)...
+wolfCOSE test: PASS (COSE_Sign1 99 bytes)
+```
+
+## Notes
+
+- Only pack source is kept in the repository. The built pack is posted at
+  [wolfssl.com/files/ide/I-CUBE-wolfCOSE.pack](https://www.wolfssl.com/files/ide/I-CUBE-wolfCOSE.pack).
+- On some STM32 families the wolfSSL pack enables hardware hash and RNG by
+  default. If a build reports a missing HAL module or hash symbol, enable the
+  matching peripheral in the `.ioc`, or select software crypto with
+  `NO_STM32_HASH` and `NO_STM32_RNG` in the generated
+  `wolfSSL.I-CUBE-wolfSSL_conf.h`. On the STM32H5 the hardware hash block
+  references a HAL enum that does not exist, so software crypto is required
+  there; the
+  [NUCLEO-H563ZI example](https://github.com/wolfSSL/wolfssl-examples-stm32/tree/master/wolfCOSE-STM32-Example)
+  shows the exact edit.

docs/_Sidebar.md

@@ -10,4 +10,5 @@
 - [[Testing]]
 - [[MISRA Compliance]]
 - [[Project Structure]]
+- [[STM32Cube]]
 - [[Release Notes]]