wolfCOSE

wolfCOSE is a lightweight C library implementing CBOR (RFC 8949), COSE (RFC 9052/9053), and post-quantum ML-DSA for COSE (RFC 9964) using wolfSSL as the crypto backend.

Main Features

Complete RFC 9052 message set: all six COSE message types, including multi-signer
COSE_Sign and multi-recipient COSE_Encrypt / COSE_Mac
Post-quantum signing: ML-DSA (FIPS 204) at all three security levels, with RFC 9964 COSE_Key (AKP key type, seed-based private keys)
40 algorithms across signing, encryption, MAC, and key distribution
Zero dynamic allocation: heap-allocation-free and non-recursive. Every operation runs on caller-provided buffers
within a bounded, target-customizable stack ceiling (nothing on the heap, zero .data/.bss)
Tiny footprint: ES256 COSE_Sign1 wolfCOSE (COSE + CBOR engine) ~5.1 KB verify-only and ~6.8 KB sign + verify.
Total flash including wolfCrypt is ~26.2 KB verify-only (WOLFCOSE_LEAN_VERIFY) and ~34.6 KB sign + verify
Fast: (ES256 COSE_Sign1, x86_64, wolfCrypt sp_256 asm): 66,538 sign/s, 26,437 verify/s
Post-quantum at the same cost: ML-DSA-44 COSE_Sign1 total flash including wolfCrypt is ~20.8 KB verify-only
(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
Path to FIPS 140-3: via wolfCrypt FIPS Certificate #4718 (sole crypto dependency)

Supported Algorithms

Signing: ES256, ES384, ES512, EdDSA (Ed25519/Ed448), PS256/384/512, ML-DSA-44/65/87

Encryption: AES-GCM (128/192/256), ChaCha20-Poly1305, AES-CCM variants

MAC: HMAC-SHA256/384/512, AES-MAC

Key Distribution: Direct, AES Key Wrap, ECDH-ES+HKDF

COSE Message Types (RFC 9052)

wolfCOSE has implemented all RFC 9052 messages both single-actor and multi-actor variants:

Message	RFC 9052	API	Purpose
`COSE_Sign1`	Sec. 4.2	`wc_CoseSign1_Sign` / `wc_CoseSign1_Verify`	Single-signer signature
`COSE_Sign`	Sec. 4.1	`wc_CoseSign_Sign` / `wc_CoseSign_Verify`	Multi-signer (independent signatures over the same payload)
`COSE_Encrypt0`	Sec. 5.2	`wc_CoseEncrypt0_Encrypt` / `wc_CoseEncrypt0_Decrypt`	Single-recipient AEAD
`COSE_Encrypt`	Sec. 5.1	`wc_CoseEncrypt_Encrypt` / `wc_CoseEncrypt_Decrypt`	Multi-recipient (one ciphertext, many recipients via Direct / AES-KW / ECDH-ES)
`COSE_Mac0`	Sec. 6.2	`wc_CoseMac0_Create` / `wc_CoseMac0_Verify`	Single-recipient MAC
`COSE_Mac`	Sec. 6.1	`wc_CoseMac_Create` / `wc_CoseMac_Verify`	Multi-recipient MAC (shared MAC key, distributed to recipients)
`COSE_Key` / `COSE_KeySet`	Sec. 7	`wc_CoseKey_Encode` / `wc_CoseKey_Decode`	Key serialization for all key types

Prerequisites (wolfSSL)

wolfCOSE requires wolfSSL as its crypto backend. Minimum supported version: v5.8.0-stable (first release with the public wc_ForceZero symbol). Post-quantum signing uses the canonical FIPS 204 wc_MlDsaKey API, which lands in wolfSSL after v5.9.1-stable; building wolfCOSE against v5.8.0–v5.9.1 works for everything except ML-DSA. Older 5.x releases can technically be supported but require source-level changes; contact wolfSSL for commercial support.

Choose a build configuration based on the algorithms you need.

Minimal Build (ECC + AES-GCM)

This gives you COSE Sign1 (ES256/384/512) and Encrypt0 (AES-GCM):

bash
cd wolfssl
./autogen.sh
./configure --enable-ecc --enable-aesgcm \
            --enable-sha384 --enable-sha512 --enable-keygen
make && sudo make install
sudo ldconfig

Algorithms enabled: ES256, ES384, ES512, AES-GCM-128/192/256

For a smaller wolfCrypt footprint, add --enable-cryptonly to drop the TLS
stack and disable the algorithms a Sign1 + Encrypt0 build never uses:

bash
./configure --enable-cryptonly --enable-ecc --enable-aesgcm \
            --enable-sha384 --enable-sha512 --enable-keygen \
            --enable-lowresource \
            --disable-dh --disable-rsa --disable-aescbc \
            --disable-sha --disable-md5 --disable-chacha --disable-poly1305 \
            --disable-errorstrings

See Tuning for Size and Tuning for Speed
for squeezing wolfCOSE and wolfCrypt further on MCUs.

Minimal Build (Post-Quantum / ML-DSA only)

For pure post-quantum signing with ML-DSA-44/65/87:

bash
cd wolfssl
./autogen.sh
./configure --enable-cryptonly --enable-mldsa
make && sudo make install
sudo ldconfig

Algorithms enabled: ML-DSA-44, ML-DSA-65, ML-DSA-87
(SHAKE-128/256 are pulled in automatically by --enable-mldsa. The
wc_MlDsaKey API requires wolfSSL newer than v5.9.1-stable.)

Full Build (All Algorithms)

bash
cd wolfssl
./autogen.sh
./configure --enable-ecc --enable-ed25519 --enable-ed448 \
            --enable-curve25519 --enable-aesgcm --enable-aesccm \
            --enable-sha384 --enable-sha512 --enable-keygen \
            --enable-rsapss --enable-chacha --enable-poly1305 \
            --enable-mldsa \
            --enable-hkdf --enable-aeskeywrap
make && sudo make install
sudo ldconfig

Build

bash
# Core library (libwolfcose.a)
make

# Run unit tests
make test

# Build and run CLI tool round-trip tests (all algorithms)
make tool-test

# Run lifecycle demo (11 algorithms)
make demo

Build Targets

Target	Description
`make all`	Build `libwolfcose.a` (core library only)
`make shared`	Build `libwolfcose.so`
`make test`	Build + run CBOR and COSE unit tests
`make tool`	Build CLI tool (`tools/wolfcose_tool`)
`make tool-test`	Round-trip self-test for all 17 algorithms
`make demo`	Build + run lifecycle demo (11 algorithms)
`make clean`	Remove all build artifacts

Quick Start

Examples

See examples/ for complete working code:

sign1_demo.c, encrypt0_demo.c, mac0_demo.c: algorithm demos
lifecycle_demo.c: full edge-to-cloud workflow
comprehensive/: algorithm matrix tests
scenarios/: firmware signing, attestation, fleet config

CI / Testing

Runs on every push and PR:

Build + Test: Ubuntu, macOS, GCC 10-14, Clang 14-18
Comprehensive Tests: ~240 algorithm combination tests
Static Analysis: cppcheck, Clang analyzer, GCC -fanalyzer
MISRA C 2012: cppcheck --addon=misra checking all wolfCOSE code paths
MISRA C 2023: strict GCC warnings and clang-tidy (bugprone-*, cert-*, clang-analyzer-*, misc-*)
Coverity Scan: nightly defect analysis
Advanced Internal Static Analysis: Fenrir wolfssl advanced static analysis tools
Code Coverage: 99.3% for wolfcose.c, 100% for wolfcose_cbor.c

bash
make coverage                  # Run tests with gcov
make coverage-force-failure    # Include crypto failure path testing

Documentation

Full documentation is available in the Wiki:

Getting Started: Build instructions and first steps
Message Types: All six RFC 9052 messages (Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac) with code samples
Algorithms: Complete list of 40 supported algorithms with COSE IDs
API Reference: Function signatures, data structures, error codes
Macros: Compile-time configuration options
Footprint: Size and speed numbers, desktop and on-device
Testing: Test infrastructure, coverage, and failure injection
MISRA Compliance: MISRA C:2012 and C:2023 compliance status and deviation rationale
Project Structure: Source file layout

Release Notes

The current release is 1.0.0, the first stable release: the complete RFC 9052 COSE message set (all six message types, single- and multi-actor), 40 algorithms, and standardized post-quantum ML-DSA (RFC 9964), all with zero dynamic allocation. See ChangeLog.md for the full release notes.

wolfCOSE 1.0.0 has been developed according to wolfSSL's development and QA process (see https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance) and successfully passed the quality criteria.