wolfCOSE

wolfCOSE 是一个轻量级 C 库，实现了 CBOR (RFC 8949)、COSE (RFC 9052/9053) 以及后量子 ML-DSA for COSE (RFC 9964)，并使用 wolfSSL 作为加密后端。

主要特性

完整的 RFC 9052 消息集：所有六种 COSE 消息类型，包括多签名者 COSE_Sign 和多接收者 COSE_Encrypt / COSE_Mac
后量子签名：ML-DSA (FIPS 204) 全部三个安全级别，支持 RFC 9964 COSE_Key（AKP 密钥类型，基于种子的私钥）
40 种算法：涵盖签名、加密、MAC 和密钥分发
零动态分配：无堆分配且非递归。每个操作都在调用方提供的缓冲区上运行，具有有界且可目标自定义的栈上限（无堆分配，零 .data/.bss）
极小体积：ES256 COSE_Sign1 wolfCOSE (COSE + CBOR 引擎) 约 5.1 KB 仅验证，约 6.8 KB 签名+验证。包含 wolfCrypt 的总闪存为 约 26.2 KB 仅验证 (WOLFCOSE_LEAN_VERIFY) 和 约 34.6 KB 签名+验证
快速：(ES256 COSE_Sign1, x86_64, wolfCrypt sp_256 汇编)：66,538 签名/秒，26,437 验证/秒
相同开销下的后量子：ML-DSA-44 COSE_Sign1 包含 wolfCrypt 的总闪存为 约 20.8 KB 仅验证 (WOLFCOSE_LEAN_VERIFY_MLDSA)，约 35.8 KB 签名+验证，与经典 ES256 相差约 1 KB。仅 wolfCOSE 部分分别为 4.6 KB 和 约 6.6 KB。详见体积
通向 FIPS 140-3 之路：通过 wolfCrypt FIPS 证书 #4718（唯一加密依赖）

支持的算法

签名： ES256, ES384, ES512, EdDSA (Ed25519/Ed448), PS256/384/512, ML-DSA-44/65/87

加密： AES-GCM (128/192/256), ChaCha20-Poly1305, AES-CCM 变体

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

密钥分发： 直接, AES 密钥包装, 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`	所有密钥类型的密钥序列化

前提条件 (wolfSSL)

wolfCOSE 需要 wolfSSL 作为加密后端。最低支持版本：v5.8.0-stable（首个包含公开 wc_ForceZero 符号的版本）。后量子签名使用规范的 FIPS 204 wc_MlDsaKey API，该 API 在 wolfSSL v5.9.1-stable 之后 才可用；针对 v5.8.0–v5.9.1 版本构建 wolfCOSE 可以支持除 ML-DSA 之外的所有功能。理论上可以支持更早的 5.x 版本，但需要修改源代码；请联系 wolfSSL 获取商业支持。

根据所需算法选择构建配置。

最小构建 (ECC + AES-GCM)

这将支持 COSE Sign1 (ES256/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

启用的算法： ES256, ES384, ES512, 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 （--enable-mldsa 会自动引入 SHAKE-128/256。 wc_MlDsaKey API 需要 wolfSSL 版本高于 v5.9.1-stable。）

完整构建（所有算法）

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

构建

# 核心库 (libwolfcose.a)
make

# 运行单元测试
make test

# 构建并运行 CLI 工具往返测试（所有算法）
make tool-test

# 运行生命周期演示（11 种算法）
make demo

构建目标

目标	描述
`make all`	构建 `libwolfcose.a`（仅核心库）
`make shared`	构建 `libwolfcose.so`
`make test`	构建并运行 CBOR 和 COSE 单元测试
`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/：固件签名、认证、设备配置

CI / 测试

每次推送和 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.c 为 99.3%，wolfcose_cbor.c 为 100%

make coverage                  # 使用 gcov 运行测试
make coverage-force-failure    # 包含加密失败路径测试

文档

完整文档见 Wiki：

入门指南：构建说明和第一步
消息类型：所有六种 RFC 9052 消息（Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac）及代码示例
算法：40 种支持算法的完整列表及其 COSE ID
API 参考：函数签名、数据结构、错误码
宏：编译时配置选项
体积：大小和速度数据（桌面和嵌入式设备）
测试：测试基础设施、覆盖率和故障注入
MISRA 合规：MISRA C:2012 和 C:2023 合规状态及偏差理由
项目结构：源文件布局

发布说明

当前版本为 1.0.0，是首个稳定版本：完整的 RFC 9052 COSE 消息集（所有六种消息类型，单角色和多角色），40 种算法，以及标准化的后量子 ML-DSA (RFC 9964)，全部采用零动态分配。完整发布说明见 ChangeLog.md。

wolfCOSE 1.0.0 按照 wolfSSL 的开发和 QA 流程（参见 https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance）开发，并成功通过了质量标准。

许可证

wolfCOSE 是自由软件，采用 GPLv3 许可证；完整文本见 LICENSE。

支持

如需商业授权、专业支持合同，或讨论将 wolfCOSE 部署到生产环境，请联系 wolfSSL。

wolfCOSE v2.0.0

分类