wolfCOSE

wolfCOSE 是一个轻量且快速的 C 库，实现了核心 CBOR 和 COSE 标准，并由 wolfSSL 提供密码学支持。

支持的标准与 RFC

核心规范：
- RFC 8949 - 简明二进制对象表示（CBOR）
- RFC 9052 - CBOR 对象签名与加密（COSE）
- RFC 9053 - COSE 算法
- RFC 9864 - JOSE 和 COSE 的完全指定算法
- RFC 9338 - COSE 计数器签名
后量子密码学：
- RFC 9964 - 用于 COSE 的 ML-DSA
- RFC 8778 - 用于 COSE 的 HSS/LMS
证明：
- RFC 9783 - 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 次验证/秒。请参阅性能与占用详情和 wolfCOSE 与同类对比。
PSA 证明： 支持 EAT / PSA 令牌的签发与验证，并支持委托 HSM 签名。
41 种密码学算法： 广泛覆盖签名、加密、MAC 和密钥分发算法。
嵌入式优先设计： 零动态内存分配（无堆，零 .data/.bss）。在调用者提供的缓冲区上运行，栈使用有界。
FIPS 140-3 路径： 使用 wolfCrypt（FIPS 证书 #4718）作为其唯一的密码学依赖。
STM32 集成： 提供即插即用的 STM32Cube 包（I-CUBE-wolfCOSE），适用于 STM32CubeMX / IDE（详情）。

支持的算法

数字签名：
- 经典： 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 作为其密码学后端。 最低支持版本：v5.8.0-stable。某些可选算法需要更新的版本；有关特定功能的依赖下限和构建说明，请参阅入门指南。HSS/LMS（RFC 8778）需要 v5.9.2-stable 或更高版本。

根据您需要的算法选择构建配置。

最小构建（ECC + AES-GCM）

这将为您提供 COSE Sign1（ESP256/384/512）和 Encrypt0（AES-GCM）：

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 构建从不使用的算法：

./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 的信息，请参阅为尺寸调优和为速度调优。

最小构建（仅后量子 / ML-DSA）

对于使用 ML-DSA-44/65/87 的纯后量子签名：

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。）

完整构建（所有算法）

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

构建

# 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% 行覆盖率

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

文档

官方 wolfCOSE 手册发布于 wolfssl.com/documentation/manuals/wolfcose：

wolfCOSE v2.0.0