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 (FIPS 204) - **40 种算法**涵盖签名、加密、MAC 和密钥分发 - **零动态分配**：所有操作都使用调用者提供的缓冲区 - **小巧的体积**：7.5 KB `.text` 最小构建（Sign1+ECC），25.6 KB 完整（40 算法），零 `.data`/`.bss` - **完整的 COSE 生命周期在 ~<1KB RAM**（不包括 wolfCrypt 内部）中 - **通过 wolfCrypt FIPS 证书 #4718 路径到 FIPS 140-3**（唯一的加密依赖项） ## 支持的算法 **签名：** `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` | Sec. 4.2 | `wc_CoseSign1_Sign` / `wc_CoseSign1_Verify` | 单签名者签名 | | `COSE_Sign` | Sec. 4.1 | `wc_CoseSign_Sign` / `wc_CoseSign_Verify` | **多签名者**（对相同有效负载的独立签名） | | `COSE_Encrypt0` | Sec. 5.2 | `wc_CoseEncrypt0_Encrypt` / `wc_CoseEncrypt0_Decrypt` | 单接收者 AEAD | | `COSE_Encrypt` | Sec. 5.1 | `wc_CoseEncrypt_Encrypt` / `wc_CoseEncrypt_Decrypt` | **多接收者**（一个密文，多个接收者通过直接/AES-KW/ECDH-ES） | | `COSE_Mac0` | Sec. 6.2 | `wc_CoseMac0_Create` / `wc_CoseMac0_Verify` | 单接收者 MAC | | `COSE_Mac` | Sec. 6.1 | `wc_CoseMac_Create` / `wc_CoseMac_Verify` | **多接收者** MAC（共享 MAC 密钥，分发给接收者） | | `COSE_Key` / `COSE_KeySet` | Sec. 7 | `wc_CoseKey_Encode` / `wc_CoseKey_Decode` | 所有密钥类型的密钥序列化 | ## 前置条件（wolfSSL） wolfCOSE 需要 [wolfSSL](https://www.wolfssl.com/) 作为其加密后端。**最低支持版本：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](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 为了缩小 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 上进一步缩小 wolfCrypt 的信息，请参阅 [Tuning for Constrained Targets](docs/Macros.md#tuning-for-constrained-targets) ### 最小构建（仅后量子 / 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 需要 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 分析器，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 # Run tests with gcov make coverage-force-failure # Include crypto failure path testing ``` ## 文档 完整的文档可在 [Wiki](https://github.com/wolfSSL/wolfCOSE/wiki）中找到： - [入门](https://github.com/wolfSSL/wolfCOSE/wiki/Getting-Started）：构建说明和第一步 - [消息类型](https://github.com/wolfSSL/wolfCOSE/wiki/Message-Types）：所有六种 RFC 9052 消息（Sign1、Sign、Encrypt0、Encrypt、Mac0、Mac）以及代码示例 - [算法](https://github.com/wolfSSL/wolfCOSE/wiki/Algorithms）：40 种支持算法的完整列表及其 COSE ID - [API 参考](https://github.com/wolfSSL/wolfCOSE/wiki/API-Reference）：函数签名、数据结构、错误代码 - [宏](https://github.com/wolfSSL/wolfCOSE/wiki/Macros）：编译时配置选项 - [测试](https://github.com/wolfSSL/wolfCOSE/wiki/Testing）：测试基础设施、覆盖率以及故障注入 - [MISRA 合规性](https://github.com/wolfSSL/wolfCOSE/wiki/MISRA-Compliance）：MISRA C:2012 和 C:2023 合规性状态和偏差理由 - [项目结构](https://github.com/wolfSSL/wolfCOSE/wiki/Project-Structure）：源文件布局 ## 许可证 wolfCOSE 是免费软件，根据 [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html）许可。 版权所有 (C) 2026 wolfSSL Inc。 ## 支持 有关商业许可、专业支持合同或讨论将 wolfCOSE 移入您的生产环境，请联系 [wolfSSL](https://www.wolfssl.com/contact/）。

标签：AES-CCM, AES-GCM, AES-MAC, CBOR, ChaCha20-Poly1305, COSE, DO-178, FIPS 140-3, FIPS认证, HMAC-SHA256, LangChain, MAC算法, MISRA C, ML-DSA, PQC, RFC 8949, RFC 9052, wolfSSL, 内存占用小, 加密库, 加密算法, 后量子密码, 安全协议, 客户端加密, 密钥分发, 嵌入式系统, 消息类型, 签名算法, 轻量级, 零动态分配