wolfSSL/wolfCOSE

来源：https://github.com/wolfSSL/wolfCOSE

wolfCOSE

wolfCOSE 是一个轻量级 C 语言库，使用 wolfSSL（https://www.wolfssl.com/）作为加密后端，实现了 CBOR（RFC 8949）（https://www.rfc-editor.org/rfc/rfc8949）和 COSE（RFC 9052/9053）（https://www.rfc-editor.org/rfc/rfc9052）。

主要特性

• 完整的 RFC 9052 消息集：全部六种 COSE 消息类型，包括多签名者的 COSE_Sign 和多接收者的 COSE_Encrypt / COSE_Mac
• 后量子签名：支持所有三个安全级别的 ML-DSA (Dilithium)
• 40种算法：涵盖签名、加密、MAC 和密钥分发
• 零动态分配：所有操作均使用调用者提供的缓冲区
• 极小的体积：最小构建（Sign1+ECC）仅 7.5 KB .text 段，完整构建（40种算法）为 25.6 KB，.data/.bss 段为零
• 完整 COSE 生命周期仅需约 <1KB RAM（不含 wolfCrypt 内部结构）
• 可通向 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 Key Wrap, ECDH-ES+HKDF

COSE 消息类型 (RFC 9052)

wolfCOSE 已实现所有 RFC 9052 消息，包括单角色和多角色变体:

前提条件 (wolfSSL)

wolfCOSE 需要 wolfSSL（https://www.wolfssl.com/）作为其加密后端。

最低支持版本：v5.8.0-stable（首个同时发布公共 wc_ForceZero 符号以及用于 FIPS 204 最终版 ML-DSA 和上下文感知 wc_dilithium_*_ctx_msg API 的版本）。较老的 5.x 版本技术上也可支持，但需要进行源码级修改；商业支持请联系 wolfSSL（https://www.wolfssl.com/contact/）。

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

最小构建 (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

最小构建 (仅后量子 / ML-DSA)

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

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

启用的算法： ML-DSA-44, ML-DSA-65, ML-DSA-87（SHAKE-128/256 由 --enable-dilithium 自动引入。）

完整构建 (所有算法)

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-dilithium --enable-hkdf --enable-aeskeywrap
make && sudo make install
sudo ldconfig

构建

# 核心库 (libwolfcose.a)
make

# 运行单元测试
make test

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

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

构建目标

快速入门

示例

参见 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 分析器, 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（https://github.com/aidangarske/wolfCOSE/wiki）：

• 入门指南（https://github.com/aidangarske/wolfCOSE/wiki/Getting-Started）：构建说明和第一步
• 消息类型（https://github.com/aidangarske/wolfCOSE/wiki/Message-Types）：全部六种 RFC 9052 消息（Sign1, Sign, Encrypt0, Encrypt, Mac0, Mac）及代码示例
• 算法（https://github.com/aidangarske/wolfCOSE/wiki/Algorithms）：完整的 40 种支持算法列表及 COSE ID
• API 参考（https://github.com/aidangarske/wolfCOSE/wiki/API-Reference）：函数签名、数据结构、错误码
• 宏（https://github.com/aidangarske/wolfCOSE/wiki/Macros）：编译时配置选项
• 测试（https://github.com/aidangarske/wolfCOSE/wiki/Testing）：测试基础设施、覆盖率和故障注入
• MISRA 合规性（https://github.com/aidangarske/wolfCOSE/wiki/MISRA-Compliance）：MISRA C:2012 和 C:2023 合规状态及偏差理由
• 项目结构（https://github.com/aidangarske/wolfCOSE/wiki/Project-Structure）：源文件布局

博客

博客和更新可在此处找到：wolfCOSE 博客（https://aidangarske.github.io/wolfCOSE/）

许可证

wolfCOSE 是根据 GPLv3（https://www.gnu.org/licenses/gpl-3.0.html）发布的自由软件。 版权所有 (C) 2026 wolfSSL Inc.

支持

注意： 虽然 wolfCOSE 目前由 wolfSSL 开发者维护，但尚未被归类为官方支持的产品。它从设计之初便旨在达到与 wolfSSL 套件其他部分相同的高质量标准，并着眼于未来的采用。随着需求的增长，我们热切希望将其转变为完全支持的产品；如果您的组织需要官方支持、有特定功能需求，或者只是有一般性问题或希望获得产品使用指导，请与我们联系。

如需商业许可、专业支持合同或讨论将 wolfCOSE 引入您的生产环境，请联系 wolfSSL（https://www.wolfssl.com/contact/）。