Skip to content

Restore README refresh documentation #88

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattia-moffa merged 1 commit into from
Sep 16, 2026
Merged

Restore README refresh documentation #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 43 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,52 @@
# wolfCOSE

wolfCOSE is a lightweight C library built on [wolfSSL](https://www.wolfssl.com/) as the crypto backend, implementing:

- [CBOR (RFC 8949)](https://www.rfc-editor.org/rfc/rfc8949)
- [COSE (RFC 9052/9053)](https://www.rfc-editor.org/rfc/rfc9052)
- [Fully-specified signature algorithms (RFC 9864)](https://www.rfc-editor.org/rfc/rfc9864)
- [COSE countersignatures (RFC 9338)](https://www.rfc-editor.org/rfc/rfc9338)
- Post-quantum [ML-DSA for COSE (RFC 9964)](https://www.rfc-editor.org/rfc/rfc9964)
- Post-quantum [HSS/LMS for COSE (RFC 8778)](https://www.rfc-editor.org/rfc/rfc8778)
- The [PSA Attestation Token profile of EAT (RFC 9783)](https://www.rfc-editor.org/rfc/rfc9783)
wolfCOSE is a lightweight and fast C library implementing core CBOR and COSE standards, backed by [wolfSSL](https://github.com/wolfSSL/wolfssl) for cryptography.

## Supported Standards & RFCs

* **Core Specifications:**
* [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) - Concise Binary Object Representation (CBOR)
* [RFC 9052](https://www.rfc-editor.org/rfc/rfc9052) - CBOR Object Signing and Encryption (COSE)
* [RFC 9053](https://www.rfc-editor.org/rfc/rfc9053) - COSE algorithms
* [RFC 9864](https://www.rfc-editor.org/rfc/rfc9864) - Fully-Specified Algorithms for JOSE and COSE
* [RFC 9338](https://www.rfc-editor.org/rfc/rfc9338) - COSE Countersignatures
* **Post-Quantum Cryptography:**
* [RFC 9964](https://www.rfc-editor.org/rfc/rfc9964) - ML-DSA for COSE
* [RFC 8778](https://www.rfc-editor.org/rfc/rfc8778) - HSS/LMS for COSE
* **Attestation:**
* [RFC 9783](https://www.rfc-editor.org/rfc/rfc9783) - PSA Attestation Token Profile of EAT

## Main Features

- **Complete COSE Suite (RFC 9052):** Full support for all six message types, including `COSE_Sign1`, `COSE_Encrypt0`, and `COSE_Mac0`.
- **V2 Countersignatures (RFC 9338):** Full and abbreviated in-place countersignatures across all six tagged COSE message types.
- **Post-Quantum Cryptography:**
- ML-DSA (FIPS 204 / RFC 9964) at all security levels.
- HSS/LMS stateful hash-based signing (RFC 8778 / CNSA 2.0).
- **Fast Post-Quantum Performance:** End-to-end ML-DSA-44 `COSE_Sign1` reaches 21,986 sign/s and 53,686 verify/s on an Intel i9-11950H with AVX2. See the [performance and footprint details](https://github.com/wolfSSL/wolfCOSE/wiki/Footprint) and [wolfCOSE vs. The Field](https://www.wolfssl.com/wolfcose-vs-the-field-the-smallest-and-fastest-cose-library-now-with-post-quantum-ml-dsa-at-the-same-cost/).
- **PSA Attestation:** EAT / PSA Token issuance and verification with delegated HSM signing support.
- **41 Cryptographic Algorithms:** Broad algorithm coverage across signing, encryption, MAC, and key distribution.
- **Embedded-First Design:** Zero dynamic memory allocation (no heap, zero `.data`/`.bss`). Operates on caller-supplied buffers with bounded stack usage.
- **FIPS 140-3 Path:** Uses wolfCrypt (FIPS Certificate #4718) as its sole cryptographic dependency.
- **STM32 Integrated:** Drop-in STM32Cube pack (`I-CUBE-wolfCOSE`) available for STM32CubeMX / IDE ([Details](https://github.com/wolfSSL/wolfCOSE/wiki/STM32Cube)).
* **Complete COSE Suite (RFC 9052):** Full support for all six message types, including `COSE_Sign1`, `COSE_Encrypt0`, and `COSE_Mac0`.
* **V2 Countersignatures (RFC 9338):** Full and abbreviated in-place countersignatures across all six tagged COSE message types.
* **Post-Quantum Cryptography:**
* ML-DSA (FIPS 204 / RFC 9964) at all security levels.
* HSS/LMS stateful hash-based signing (RFC 8778 / CNSA 2.0).
* **Fast Performance:** On an Intel i9-11950H, end-to-end `COSE_Sign1` reaches 66,538 sign/s and 26,437 verify/s with ES256, and 21,986 sign/s and 53,686 verify/s with ML-DSA-44. See the [performance and footprint details](https://github.com/wolfSSL/wolfCOSE/wiki/Footprint) and [wolfCOSE vs. The Field](https://www.wolfssl.com/wolfcose-vs-the-field-the-smallest-and-fastest-cose-library-now-with-post-quantum-ml-dsa-at-the-same-cost/).
* **PSA Attestation:** EAT / PSA Token issuance and verification with delegated HSM signing support.
* **41 Cryptographic Algorithms:** Broad algorithm coverage across signing, encryption, MAC, and key distribution.
* **Embedded-First Design:** Zero dynamic memory allocation (no heap, zero `.data`/`.bss`). Operates on caller-supplied buffers with bounded stack usage.
* **FIPS 140-3 Path:** Uses wolfCrypt (FIPS Certificate #4718) as its sole cryptographic dependency.
* **STM32 Integrated:** Drop-in STM32Cube pack (`I-CUBE-wolfCOSE`) available for STM32CubeMX / IDE ([Details](https://github.com/wolfSSL/wolfCOSE/wiki/STM32Cube)).

## Supported Algorithms

**Signing:** `ESP256, ESP384, ESP512, Ed25519, Ed448, PS256/384/512, ML-DSA-44/65/87, HSS-LMS`

The polymorphic RFC 9053 IDs `ES256, ES384, ES512, EdDSA` are deprecated by RFC 9864 and are accepted only when built with `WOLFCOSE_ENABLE_DEPRECATED_ALGS` (see [Macros](https://github.com/wolfSSL/wolfCOSE/wiki/Macros)).

**Migrating from the RFC 9053 IDs:** a default build now rejects the deprecated
IDs with `WOLFCOSE_E_COSE_BAD_ALG`, so messages and keys that use them stop
verifying. Move to the fully-specified replacement, or rebuild with
`WOLFCOSE_ENABLE_DEPRECATED_ALGS` to keep accepting the old IDs.

| Deprecated (RFC 9053) | Replacement (RFC 9864) |
| --- | --- |
| `ES256` (-7) | `ESP256` (-9) |
| `ES384` (-35) | `ESP384` (-51) |
| `ES512` (-36) | `ESP512` (-52) |
| `EdDSA` (-8), Ed25519 key | `Ed25519` (-19) |
| `EdDSA` (-8), Ed448 key | `Ed448` (-53) |

**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`
* **Digital Signatures:**
* **Classical:** `ESP256`, `ESP384`, `ESP512`, `Ed25519`, `Ed448`, `PS256`, `PS384`, `PS512`
* **Post-Quantum:** `ML-DSA-44`, `ML-DSA-65`, `ML-DSA-87`
* **Stateful Hash-Based:** `HSS-LMS`
* **Encryption (AEAD):**
* `AES-GCM` (128 / 192 / 256)
* `AES-CCM` (variants)
* `ChaCha20-Poly1305`
* **Message Authentication (MAC):**
* `HMAC-SHA256`, `HMAC-SHA384`, `HMAC-SHA512`
* `AES-MAC`
* **Key Distribution:**
* `Direct`
* `AES Key Wrap`
* `ECDH-ES + HKDF`

## COSE Message Types (RFC 9052)

Expand All @@ -68,7 +67,7 @@ table. Use `wc_Cose_AddCounterSignature()` or
`wc_Cose_AddCounterSignature0()` to add one, then verify it independently with
the corresponding `wc_Cose_VerifyCounterSignature*()` API.

## Prerequisites (wolfSSL)
## Dependencies (wolfSSL)

wolfCOSE requires [wolfSSL](https://www.wolfssl.com/) as its crypto backend.
**Minimum supported version: v5.8.0-stable**. Some optional algorithms require
Expand Down Expand Up @@ -195,7 +194,7 @@ Runs on every push and PR:
- **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
- **Internal Static Analysis:** Fenrir wolfssl advanced static analysis tools
- **Code Coverage**: 100% line coverage enforced for every wolfCOSE source file

```bash
Expand All @@ -211,12 +210,6 @@ make coverage-force-failure # Include crypto failure path testing
<img alt="CI Status"
src="https://img.shields.io/github/actions/workflow/status/wolfSSL/wolfCOSE/build-test.yml?label=CI&logo=github"/>
</a>
<a href="https://github.com/wolfssl/skoll"> <img alt="Skoll Review" src="https://img.shields.io/badge/skoll-passed-blue"/>
</a>
<a href="https://github.com/wolfssl/fenrir">
<img alt="Fenrir Review" src="https://img.shields.io/badge/fenrir-passed-blueviolet"/>
</a>


## Documentation

Expand Down
21 changes: 21 additions & 0 deletions docs/Algorithms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,27 @@ wolfCOSE supports 46 algorithms across signing, encryption, MAC, and key distrib
| ML-DSA-87 | -50 | `WOLFSSL_HAVE_MLDSA` | Post-quantum (FIPS 204) |
| HSS-LMS | -46 | `WOLFSSL_HAVE_LMS` | Post-quantum stateful hash-based (RFC 8778, SP 800-208); COSE_Key kty 5; signature size follows the key's parameter set; signing state is caller-managed, verify-only builds pair with `WOLFSSL_LMS_VERIFY_ONLY` |

### Migrating from RFC 9053 Signature IDs

RFC 9864 deprecates the polymorphic RFC 9053 signature IDs. Default wolfCOSE
builds accept the fully specified replacements and reject the deprecated IDs
with `WOLFCOSE_E_COSE_BAD_ALG`.

| Deprecated RFC 9053 ID | RFC 9864 replacement |
|------------------------|----------------------|
| ES256 (-7) | ESP256 (-9) |
| ES384 (-35) | ESP384 (-51) |
| ES512 (-36) | ESP512 (-52) |
| EdDSA (-8) with an Ed25519 key | Ed25519 (-19) |
| EdDSA (-8) with an Ed448 key | Ed448 (-53) |

Use the replacement ID when creating new messages. The protected `alg` value
is part of the signed `Sig_structure`, so an existing message must be signed
again rather than relabeled. Define `WOLFCOSE_ENABLE_DEPRECATED_ALGS` when
compatibility with peers that still emit the RFC 9053 IDs is required. See
[Deprecated Algorithm IDs](Macros.md#deprecated-algorithm-ids-rfc-9864) for
configuration details.

### ML-DSA Signature Sizes

| Algorithm | Signature Size | Public Key Size |
Expand Down
18 changes: 9 additions & 9 deletions docs/Footprint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Footprint and Performance

wolfCOSE's own size and speed for one identical operation (ES256 `COSE_Sign1`, and post-quantum ML-DSA), every part built from source with dead-code elimination so only the code actually reached by the operation is counted.
This page reports build-profile footprint and end-to-end `COSE_Sign1` throughput for ES256 and ML-DSA-44.

**Method.** One fixed key and payload. Built `-ffunction-sections -fdata-sections` and linked `-Wl,--gc-sections`, so unreached functions are dropped; this is the real flash cost, not the whole-archive size. Sizes are code + rodata. Two numbers are reported: **glue** is the wolfCOSE COSE + CBOR engine alone (independent of the crypto backend); **total** is glue plus the minimal wolfCrypt build pulled in. Desktop: x86_64 Intel i9-11950H, GCC 14.2. On-device: NUCLEO-H563ZI (STM32H563ZI, Cortex-M33 @ 250 MHz). June 2026.
**Size method.** One fixed key and payload. Built `-ffunction-sections -fdata-sections` and linked `-Wl,--gc-sections`, so unreached functions are dropped; this is the real flash cost, not the whole-archive size. Sizes are code + rodata. Two numbers are reported: **glue** is the wolfCOSE COSE + CBOR engine alone (independent of the crypto backend); **total** is glue plus the minimal wolfCrypt build pulled in. Desktop: x86_64 Intel i9-11950H, GCC 14.2. On-device: NUCLEO-H563ZI (STM32H563ZI, Cortex-M33 @ 250 MHz). June 2026.

## Library size (glue)

Expand Down Expand Up @@ -48,14 +48,14 @@ Post-quantum sign + verify lands within ~1 KB of classical ES256, and verify-onl

## Speed (Intel i9-11950H, x86_64)

End-to-end `COSE_Sign1` throughput using optimized wolfCrypt assembly.
ES256 and ML-DSA-44 rates are measured end-to-end for `COSE_Sign1` on an Intel i9-11950H using optimized wolfCrypt assembly. See the [published measurements](https://www.wolfssl.com/wolfcose-vs-the-field-the-smallest-and-fastest-cose-library-now-with-post-quantum-ml-dsa-at-the-same-cost/) for more background.

| Operation | Ops/s |
|-----------|-------|
| ES256 verify | 26,437 |
| ES256 sign | 66,538 |
| ML-DSA-44 verify | 53,686 |
| ML-DSA-44 sign | 21,986 |
| Operation | Scope | Ops/s |
|-----------|-------|-------|
| ES256 verify | End-to-end `COSE_Sign1` | 26,437 |
| ES256 sign | End-to-end `COSE_Sign1` | 66,538 |
| ML-DSA-44 verify | End-to-end `COSE_Sign1` | 53,686 |
| ML-DSA-44 sign | End-to-end `COSE_Sign1` | 21,986 |

## On a real MCU: STM32H563 (Cortex-M33 @ 250 MHz)

Expand Down
Loading