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：