一个快速、便携且轻量级的COSE + CBOR实现,适用于嵌入式系统。支持PQC、FIPS 140-3、DO-178和MISRA C。由wolfSSL提供技术支持。
# wolfCOSE
wolfCOSE 是一个轻量且快速的 C 库,实现了核心 CBOR 和 COSE 标准,并由 [wolfSSL](https://github.com/wolfSSL/wolfssl) 提供密码学支持。
## 支持的标准与 RFC
* **核心规范:**
* [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) - 简明二进制对象表示(CBOR)
* [RFC 9052](https://www.rfc-editor.org/rfc/rfc9052) - CBOR 对象签名与加密(COSE)
* [RFC 9053](https://www.rfc-editor.org/rfc/rfc9053) - COSE 算法
* [RFC 9864](https://www.rfc-editor.org/rfc/rfc9864) - JOSE 和 COSE 的完全指定算法
* [RFC 9338](https://www.rfc-editor.org/rfc/rfc9338) - COSE 计数器签名
* **后量子密码学:**
* [RFC 9964](https://www.rfc-editor.org/rfc/rfc9964) - 用于 COSE 的 ML-DSA
* [RFC 8778](https://www.rfc-editor.org/rfc/rfc8778) - 用于 COSE 的 HSS/LMS
* **证明:**
* [RFC 9783](https://www.rfc-editor.org/rfc/rfc9783) - EAT 的 PSA 证明令牌配置文件
## 主要特性
* **完整的 COSE 套件(RFC 9052):** 全面支持全部六种消息类型,包括 `COSE_Sign1`、`COSE_Encrypt0` 和 `COSE_Mac0`。
* **V2 计数器签名(RFC 9338):** 在所有六种带标签的 COSE 消息类型上支持完整和简写的就地计数器签名。
* **后量子密码学:**
* 所有安全级别的 ML-DSA(FIPS 204 / RFC 9964)。
* HSS/LMS 有状态基于哈希的签名(RFC 8778 / CNSA 2.0)。
* **快速性能:** 在 Intel i9-11950H 上,端到端 `COSE_Sign1` 使用 ES256 可达到 66,538 次签名/秒和 26,437 次验证/秒,使用 ML-DSA-44 可达到 21,986 次签名/秒和 53,686 次验证/秒。请参阅[性能与占用详情](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html)和 [wolfCOSE 与同类对比](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 证明:** 支持 EAT / PSA 令牌的签发与验证,并支持委托 HSM 签名。
* **41 种密码学算法:** 广泛覆盖签名、加密、MAC 和密钥分发算法。
* **嵌入式优先设计:** 零动态内存分配(无堆,零 `.data`/`.bss`)。在调用者提供的缓冲区上运行,栈使用有界。
* **FIPS 140-3 路径:** 使用 wolfCrypt(FIPS 证书 #4718)作为其唯一的密码学依赖。
* **STM32 集成:** 提供即插即用的 STM32Cube 包(`I-CUBE-wolfCOSE`),适用于 STM32CubeMX / IDE([详情](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html))。
## 支持的算法
* **数字签名:**
* **经典:** `ESP256`、`ESP384`、`ESP512`、`Ed25519`、`Ed448`、`PS256`、`PS384`、`PS512`
* **后量子:** `ML-DSA-44`、`ML-DSA-65`、`ML-DSA-87`
* **有状态基于哈希:** `HSS-LMS`
* **加密(AEAD):**
* `AES-GCM`(128 / 192 / 256)
* `AES-CCM`(变体)
* `ChaCha20-Poly1305`
* **消息认证(MAC):**
* `HMAC-SHA256`、`HMAC-SHA384`、`HMAC-SHA512`
* `AES-MAC`
* **密钥分发:**
* `Direct`
* `AES Key Wrap`
* `ECDH-ES + HKDF`
## COSE 消息类型(RFC 9052)
wolfCOSE 已实现所有 RFC 9052 消息的单参与者和多参与者变体:
| 消息 | RFC 9052 | API | 用途 |
|---|---|---|---|
| `COSE_Sign1` | 第 4.2 节 | `wc_CoseSign1_Sign` / `wc_CoseSign1_Verify` | 单签名者签名 |
| `COSE_Sign` | 第 4.1 节 | `wc_CoseSign_Sign` / `wc_CoseSign_Verify` | **多签名者**(对同一负载的独立签名) |
| `COSE_Encrypt0` | 第 5.2 节 | `wc_CoseEncrypt0_Encrypt` / `wc_CoseEncrypt0_Decrypt` | 单接收者 AEAD |
| `COSE_Encrypt` | 第 5.1 节 | `wc_CoseEncrypt_Encrypt` / `wc_CoseEncrypt_Decrypt` | **多接收者**(一个密文,通过 Direct / AES-KW / ECDH-ES 分发给多个接收者) |
| `COSE_Mac0` | 第 6.2 节 | `wc_CoseMac0_Create` / `wc_CoseMac0_Verify` | 单接收者 MAC |
| `COSE_Mac` | 第 6.1 节 | `wc_CoseMac_Create` / `wc_CoseMac_Verify` | **多接收者** MAC(共享 MAC 密钥,分发给各接收者) |
| `COSE_Key` / `COSE_KeySet` | 第 7 节 | `wc_CoseKey_Encode` / `wc_CoseKey_Decode` | 所有密钥类型的密钥序列化 |
RFC 9338 计数器签名可以附加到本表中的任何带标签消息上。使用
`wc_Cose_AddCounterSignature()` 或
`wc_Cose_AddCounterSignature0()` 添加一个,然后使用相应的
`wc_Cose_VerifyCounterSignature*()` API 独立验证它。
## 依赖项(wolfSSL)
wolfCOSE 需要 [wolfSSL](https://www.wolfssl.com/) 作为其密码学后端。
**最低支持版本:v5.8.0-stable**。某些可选算法需要
更新的版本;有关特定功能的依赖下限和构建说明,请参阅[入门指南](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html#prerequisites)。HSS/LMS(RFC 8778)
需要 v5.9.2-stable 或更高版本。
根据您需要的算法选择构建配置。
### 最小构建(ECC + AES-GCM)
这将为您提供 COSE Sign1(ESP256/384/512)和 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
```
**启用的算法:** ESP256、ESP384、ESP512、AES-GCM-128/192/256
为了获得更小的 wolfCrypt 占用,添加 `--enable-cryptonly` 以去掉 TLS
栈,并禁用 Sign1 + Encrypt0 构建从不使用的算法:
```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
```
有关在 MCU 上进一步压缩 wolfCOSE 和 wolfCrypt 的信息,请参阅[为尺寸调优](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-size)和[为速度调优](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html#tuning-for-speed)。
### 最小构建(仅后量子 / ML-DSA)
对于使用 ML-DSA-44/65/87 的纯后量子签名:
```bash
cd wolfssl
./autogen.sh
./configure --enable-cryptonly --enable-mldsa
make && sudo make install
sudo ldconfig
```
**启用的算法:** ML-DSA-44、ML-DSA-65、ML-DSA-87
(SHAKE-128/256 由 `--enable-mldsa` 自动引入。
`wc_MlDsaKey` API 需要高于 v5.9.1-stable 的 wolfSSL。)
### 完整构建(所有算法)
```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-lms \
--enable-hkdf --enable-aeskeywrap
make && sudo make install
sudo ldconfig
```
## 构建
```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
```
### 构建目标
| 目标 | 描述 |
|--------|-------------|
| `make all` | 构建 `libwolfcose.a`(仅核心库) |
| `make shared` | 构建 `libwolfcose.so` |
| `make test` | 构建并运行 CBOR 和 COSE 单元测试 |
| `make pkg-config-test` | 验证 wolfSSL 包发现和覆盖 |
| `make eat-psa-test` | 构建并运行显式的完整 RFC 9783 PSA/EAT 一致性套件 |
| `make eat-psa-min-buffers-test` | 在 `WOLFCOSE_MIN_BUFFERS` 受限目标限制下运行完整 PSA/EAT 套件 |
| `make eat-psa-config-check` | 验证 PSA/EAT 默认不存在,并验证功能门组合 |
| `make psa-eat-lean-verify` | 构建并运行完整的 `#tfm` 仅验证 PSA/EAT RFC 向量示例 |
| `make psa-eat-demo` | 签发、验证并评估当前 RFC 9783 设备入网令牌 |
| `make tool` | 构建 CLI 工具(`tools/wolfcose_tool`) |
| `make tool-test` | 所有 17 种算法的往返自测 |
| `make demo` | 构建并运行生命周期演示(11 种算法) |
| `make clean` | 移除所有构建产物 |
## 快速开始
### 示例
请参阅 `examples/` 获取完整可运行代码:
- `sign1_demo.c`、`encrypt0_demo.c`、`mac0_demo.c`:算法演示
- `lifecycle_demo.c`:完整的边缘到云工作流
- `comprehensive/`:算法矩阵测试
- `scenarios/`:固件签名、证明、车队配置
- `psa_eat_demo.c`:带测量评估的 RFC 9783 设备入网
- `psa_eat_verify_lean.c`:精简构建中的 RFC 9783 当前配置文件 Sign1 验证
## CI / 测试
在每次 push 和 PR 时运行:
- **构建 + 测试**:Ubuntu、macOS、GCC 10-14、Clang 14-18
- **综合测试**:约 240 个算法组合测试
- **静态分析**:cppcheck、Clang analyzer、GCC `-fanalyzer`
- **MISRA C 2012**:cppcheck `--addon=misra` 检查所有 wolfCOSE 代码路径
- **MISRA C 2023**:严格的 GCC 警告和 clang-tidy(`bugprone-*`、`cert-*`、`clang-analyzer-*`、`misc-*`)
- **Coverity Scan**:每晚缺陷分析
- **内部静态分析:** Fenrir wolfssl 高级静态分析工具
- **代码覆盖率**:对每个 wolfCOSE 源文件强制要求 100% 行覆盖率
```bash
make coverage # Run tests with gcov
make coverage-force-failure # Include crypto failure path testing
```
<a href="https://scan.coverity.com/projects/wolfcose">
<img alt="Coverity Scan Build Status"
src="https://scan.coverity.com/projects/32918/badge.svg"/>
</a>
<a href="https://github.com/wolfSSL/wolfCOSE/actions">
<img alt="CI Status"
src="https://img.shields.io/github/actions/workflow/status/wolfSSL/wolfCOSE/build-test.yml?label=CI&logo=github"/>
</a>
## 文档
官方 wolfCOSE 手册发布于
[wolfssl.com/documentation/manuals/wolfcose](https://www.wolfssl.com/documentation/manuals/wolfcose/index.html):
- [入门指南](https://www.wolfssl.com/documentation/manuals/wolfcose/Getting-Started.html):构建说明和第一步
- [消息类型](https://www.wolfssl.com/documentation/manuals/wolfcose/Message-Types.html):所有六种 RFC 9052 消息(Sign1、Sign、Encrypt0、Encrypt、Mac0、Mac)以及 RFC 9338 计数器签名,附代码示例
- [算法](https://www.wolfssl.com/documentation/manuals/wolfcose/Algorithms.html):41 种受支持算法的完整列表及 COSE ID
- [API 参考](https://www.wolfssl.com/documentation/manuals/wolfcose/API-Reference.html):函数签名、数据结构、错误码
- [宏](https://www.wolfssl.com/documentation/manuals/wolfcose/Macros.html):编译时配置、尺寸调优和 ECDSA nonce 策略
- [PSA-EAT](https://www.wolfssl.com/documentation/manuals/wolfcose/PSA-EAT.html):RFC 9783 PSA 令牌配置文件、API、宏和安全指南
- [占用](https://www.wolfssl.com/documentation/manuals/wolfcose/Footprint.html):桌面和设备上的尺寸与速度数据
- [测试](https://www.wolfssl.com/documentation/manuals/wolfcose/Testing.html):测试基础设施、覆盖率和故障注入
- [MISRA 合规性](https://www.wolfssl.com/documentation/manuals/wolfcose/MISRA-Compliance.html):MISRA C:2012 和 C:2023 合规状态及偏差理由
- [项目结构](https://www.wolfssl.com/documentation/manuals/wolfcose/Project-Structure.html):源文件布局
- [STM32Cube](https://www.wolfssl.com/documentation/manuals/wolfcose/STM32Cube.html):在设备上以 STM32Cube 包安装并运行 wolfCOSE
手册源文件位于 [`docs/`](https://github.com/wolfssl/wolfcose/blob/main/docs);`mkdocs.yml` 定义了导航,
共享的 [`wolfSSL/documentation`](https://github.com/wolfSSL/documentation)
工具链构建 HTML 和 PDF。有关本地预览以及更改如何发布到网站,请参阅 [docs/dev/DOCS-BUILD.md](https://github.com/wolfssl/wolfcose/blob/main/docs/dev/DOCS-BUILD.md)。
## 发行说明
当前版本为 **2.0.0**。它新增了标准化的 HSS/LMS 签名(RFC 8778)、COSE 计数器签名(RFC 9338)、PSA/EAT 证明(RFC 9783)、RFC 9864 签名 ID、委托签名、扩展的密钥和 CBOR API、实验性 COSE-HPKE 以及大量加固,全部实现零动态分配。完整发行说明请参阅 [ChangeLog.md](https://github.com/wolfssl/wolfcose/blob/main/ChangeLog.md)。
wolfCOSE 2.0.0 按照 wolfSSL 的开发和 QA 流程开发(参见 https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance),并成功通过了质量标准。
## 许可证
wolfCOSE 是自由软件,采用 [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html) 许可;完整文本请参阅 [LICENSE](https://github.com/wolfssl/wolfcose/blob/main/LICENSE)。
版权所有 (C) 2026 wolfSSL Inc.
## 支持
如需商业许可、专业支持合同,或讨论将 wolfCOSE 引入您的生产环境,请联系 [wolfSSL](https://www.wolfssl.com/contact/)。