diff --git a/IDE/STM32Cube/README.md b/IDE/STM32Cube/README.md new file mode 100644 index 0000000..db20529 --- /dev/null +++ b/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. diff --git a/IDE/STM32Cube/default_conf.ftl b/IDE/STM32Cube/default_conf.ftl new file mode 100644 index 0000000..4b91f30 --- /dev/null +++ b/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****/ diff --git a/IDE/STM32Cube/wolfcose_test.c b/IDE/STM32Cube/wolfcose_test.c new file mode 100644 index 0000000..8171f9d --- /dev/null +++ b/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 . + */ + +#include "wolfcose_test.h" + +#include +#include + +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 +} diff --git a/IDE/STM32Cube/wolfcose_test.h b/IDE/STM32Cube/wolfcose_test.h new file mode 100644 index 0000000..4465c02 --- /dev/null +++ b/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 . + */ + +#ifndef WOLFCOSE_TEST_H_ +#define WOLFCOSE_TEST_H_ + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +int wolfCOSETest(void); + +#ifdef __cplusplus +} +#endif + +#endif /* WOLFCOSE_TEST_H_ */ diff --git a/README.md b/README.md index a97709c..fcb2b6d 100644 --- a/README.md +++ b/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 diff --git a/docs/Home.md b/docs/Home.md index e75a0a7..4a58bc8 100644 --- a/docs/Home.md +++ b/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 diff --git a/docs/STM32Cube.md b/docs/STM32Cube.md new file mode 100644 index 0000000..4b10773 --- /dev/null +++ b/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. diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md index 2d4ee2e..6683ebe 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -10,4 +10,5 @@ - [[Testing]] - [[MISRA Compliance]] - [[Project Structure]] +- [[STM32Cube]] - [[Release Notes]]