aidangarske/wolfCOSE
GitHub: aidangarske/wolfCOSE
一个基于 wolfSSL 的轻量级零分配 COSE 库，支持后量子签名并为资源受限嵌入式环境提供 CBOR 数据的签名、加密和消息认证功能。
Stars: 2 | Forks: 0
# wolfCOSE
一个轻量级、零分配的 C 语言库，实现了 [CBOR (RFC 8949)](https://www.rfc-editor.org/rfc/rfc8949) 和 [COSE (RFC 9052/9053)](https://www.rfc-editor.org/rfc/rfc9052)，并使用 [wolfSSL](https://www.wolfssl.com/) 作为加密后端。
专为资源受限的 IoT 设备、FIPS 限定部署以及任何需要在极小 RAM 中处理已认证 CBOR 负载的场景而构建。
## 亮点
- **首个支持后量子签名的 C 语言 COSE 库** -- 支持所有三个安全级别的 ML-DSA (FIPS 204 / Dilithium)
- **涵盖签名、加密和 MAC 的 26 种算法** -- 从经典的 ECC 到后量子算法
- **符合 CNSA 2.0 标准** -- ML-DSA-44/65/87 用于抗量子数字签名
- **零动态分配** -- 所有操作均使用调用者提供的缓冲区，无 `malloc`
- **极小的占用空间** -- 核心库约 15KB `.text`，零 `.data`/`.bss`
- **在 <1KB RAM 中完成完整 COSE 生命周期**（不包括 wolfCrypt 数学内部组件）
## 关键特性
- **零拷贝 CBOR 解码器** -- 单次遍历，数据指针直接引用输入缓冲区
- **C99 / MISRA-C:2023** -- 单一出口模式，无递归，记录偏差
- **wolfCrypt 集成** -- 利用 wolfSSL 的 FIPS 140-3 验证加密引擎
- **基于指针的密钥结构** -- `WOLFCOSE_KEY` 持有指向调用者拥有的 wolfCrypt 密钥的指针（约 48 字节，而非千字节）
- **编译时算法调度** -- `#ifdef` 梯度判断，零开销，无函数指针
- **敏感数据擦除** -- 对所有栈上的加密材料使用 `wc_ForceZero()`
## 支持的算法
### COSE_Sign1 (数字签名)
| Algorithm | COSE ID | wolfCrypt Guard | Notes |
|-----------|---------|-----------------|-------|
| ES256 | -7 | `HAVE_ECC` | ECDSA with P-256 / SHA-256 |
| ES384 | -35 | `HAVE_ECC` | ECDSA with P-384 / SHA-384 |
| ES512 | -36 | `HAVE_ECC` | ECDSA with P-521 / SHA-512 |
| EdDSA (Ed25519) | -8 | `HAVE_ED25519` | Curve25519 |
| EdDSA (Ed448) | -8 | `HAVE_ED448` | Curve448 (Goldilocks) |
| PS256 | -37 | `WC_RSA_PSS` | RSA-PSS with SHA-256 |
| PS384 | -38 | `WC_RSA_PSS` | RSA-PSS with SHA-384 |
| PS512 | -39 | `WC_RSA_PSS` | RSA-PSS with SHA-512 |
| ML-DSA-44 | -48 | `HAVE_DILITHIUM` | Post-quantum, FIPS 204 Level 2 |
| ML-DSA-65 | -49 | `HAVE_DILITHIUM` | Post-quantum, FIPS 204 Level 3 |
| ML-DSA-87 | -50 | `HAVE_DILITHIUM` | Post-quantum, FIPS 204 Level 5 |
### COSE_Encrypt0 (认证加密)
| Algorithm | COSE ID | wolfCrypt Guard | Notes |
|-----------|---------|-----------------|-------|
| A128GCM | 1 | `HAVE_AESGCM` | AES-GCM 128-bit |
| A192GCM | 2 | `HAVE_AESGCM` | AES-GCM 192-bit |
| A256GCM | 3 | `HAVE_AESGCM` | AES-GCM 256-bit |
| ChaCha20/Poly1305 | 24 | `HAVE_CHACHA && HAVE_POLY1305` | 256-bit, software-friendly |
| AES-CCM-16-64-128 | 10 | `HAVE_AESCCM` | 128-bit key, 8-byte tag |
| AES-CCM-16-64-256 | 11 | `HAVE_AESCCM` | 256-bit key, 8-byte tag |
| AES-CCM-64-64-128 | 12 | `HAVE_AESCCM` | 128-bit key, 8-byte tag, short nonce |
| AES-CCM-64-64-256 | 13 | `HAVE_AESCCM` | 256-bit key, 8-byte tag, short nonce |
| AES-CCM-16-128-128 | 30 | `HAVE_AESCCM` | 128-bit key, 16-byte tag |
| AES-CCM-16-128-256 | 31 | `HAVE_AESCCM` | 256-bit key, 16-byte tag |
| AES-CCM-64-128-128 | 32 | `HAVE_AESCCM` | 128-bit key, 16-byte tag, short nonce |
| AES-CCM-64-128-256 | 33 | `HAVE_AESCCM` | 256-bit key, 16-byte tag, short nonce |
### COSE_Mac0 (消息认证)
| Algorithm | COSE ID | wolfCrypt Guard | Notes |
|-----------|---------|-----------------|-------|
| HMAC 256/256 | 5 | `!NO_HMAC` | SHA-256, 32-byte tag |
| HMAC 384/384 | 6 | `WOLFSSL_SHA384` | SHA-384, 48-byte tag |
| HMAC 512/512 | 7 | `WOLFSSL_SHA512` | SHA-512, 64-byte tag |
### 密钥类型
| COSE kty | Guard | Algorithms |
|----------|-------|------------|
| EC2 (2) | `HAVE_ECC` | ES256, ES384, ES512 |
| OKP (1) | `HAVE_ED25519` / `HAVE_ED448` / `HAVE_DILITHIUM` | EdDSA, ML-DSA |
| RSA (3) | `WC_RSA_PSS` | PS256, PS384, PS512 |
| Symmetric (4) | always | AES-GCM, AES-CCM, ChaCha20, HMAC |
### 路线图
计划未来支持的算法：
- **ML-KEM** (FIPS 203 / Kyber) -- 用于 COSE_Encrypt 的后量子密钥封装
- **XMSS / LMS** -- 基于哈希的有状态签名 (NIST SP 800-208)
- **SLH-DSA** (SPHINCS+) -- 无状态基于哈希的签名
## 前置条件
需启用所需算法的 wolfSSL 5.x：
```
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
make && sudo make install
sudo ldconfig
```
对于最小构建（仅 ECC + AES-GCM）：
```
./configure --enable-ecc --enable-aesgcm --enable-sha384 \
--enable-sha512 --enable-keygen
```
## 构建
```
# 核心库 (libwolfcose.a)
make
# 运行单元测试
make test
# 构建并运行 CLI tool round-trip 测试（所有算法）
make tool-test
# 运行 lifecycle demo（11 种算法）
make demo
```
### 构建目标
| Target | Description |
|--------|-------------|
| `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` | 移除所有构建产物 |
## 项目结构
```
include/wolfcose/
wolfcose.h Public API (types, constants, all functions)
visibility.h WOLFCOSE_API export macros
src/
wolfcose_cbor.c CBOR encoder/decoder (RFC 8949, no wolfCrypt dep)
wolfcose.c COSE Sign1/Encrypt0/Mac0/Key (RFC 9052/9053, wolfCrypt)
wolfcose_internal.h Internal helpers (BE macros, header codec, AEAD dispatch)
tests/
test_cbor.c CBOR vectors (RFC 8949 Appendix A) + round-trip
test_cose.c COSE Sign1/Encrypt0/Mac0/Key tests
test_main.c Test harness (CI exit codes)
tools/
wolfcose_tool.c CLI: keygen, sign, verify, encrypt, decrypt, mac, info, test
examples/
lifecycle_demo.c Edge-to-cloud producer/consumer demo (11 algorithms)
```
核心库由两个目标文件组成。仅使用 CBOR 的项目只需链接 `wolfcose_cbor.o`。
## 快速入门
### 签名与验证 (C API)
```
#include
/* Caller owns all buffers and key lifecycle */
ecc_key eccKey;
WOLFCOSE_KEY coseKey;
uint8_t scratch[WOLFCOSE_MAX_SCRATCH_SZ];
uint8_t out[256];
size_t outLen;
WC_RNG rng;
/* Setup */
wc_ecc_init(&eccKey);
wc_ecc_make_key(&rng, 32, &eccKey);
wc_CoseKey_Init(&coseKey);
wc_CoseKey_SetEcc(&coseKey, WOLFCOSE_CRV_P256, &eccKey);
/* Sign */
wc_CoseSign1_Sign(&coseKey, WOLFCOSE_ALG_ES256,
kid, kidLen, payload, payloadLen, NULL, 0,
scratch, sizeof(scratch), out, sizeof(out), &outLen, &rng);
/* Verify */
WOLFCOSE_HDR hdr;
const uint8_t* decoded;
size_t decodedLen;
wc_CoseSign1_Verify(&coseKey, out, outLen, NULL, 0,
scratch, sizeof(scratch), &hdr, &decoded, &decodedLen);
/* Cleanup -- caller frees wolfCrypt key, not wolfCOSE */
wc_ecc_free(&eccKey);
```
### 后量子签名 (ML-DSA)
```
#include
dilithium_key dlKey;
WOLFCOSE_KEY coseKey;
uint8_t scratch[8192]; /* PQC needs larger scratch */
uint8_t out[8192];
size_t outLen;
wc_dilithium_init(&dlKey);
wc_dilithium_set_level(&dlKey, 2); /* Level 2 = ML-DSA-44 */
wc_dilithium_make_key(&dlKey, &rng);
wc_CoseKey_Init(&coseKey);
wc_CoseKey_SetDilithium(&coseKey, WOLFCOSE_ALG_ML_DSA_44, &dlKey);
wc_CoseSign1_Sign(&coseKey, WOLFCOSE_ALG_ML_DSA_44,
NULL, 0, payload, payloadLen, NULL, 0,
scratch, sizeof(scratch), out, sizeof(out), &outLen, &rng);
```
### CLI 工具
```
# 为各种算法生成密钥
./tools/wolfcose_tool keygen -a ES256 -o ec.key
./tools/wolfcose_tool keygen -a PS256 -o rsa.key
./tools/wolfcose_tool keygen -a ML-DSA-44 -o pqc.key
# 签名和验证
./tools/wolfcose_tool sign -k ec.key -a ES256 -i data.bin -o data.cose
./tools/wolfcose_tool verify -k ec.key -i data.cose
# 加密和解密
./tools/wolfcose_tool keygen -a A128GCM -o sym.key
./tools/wolfcose_tool enc -k sym.key -a A128GCM -i secret.bin -o secret.cose
./tools/wolfcose_tool dec -k sym.key -i secret.cose -o recovered.bin
# MAC 和验证
./tools/wolfcose_tool keygen -a HMAC256 -o hmac.key
./tools/wolfcose_tool mac -k hmac.key -a HMAC256 -i data.bin -o data.mac
./tools/wolfcose_tool macverify -k hmac.key -i data.mac
# 检查 COSE 结构
./tools/wolfcose_tool info -i data.cose
# 运行所有 round-trip self-tests
./tools/wolfcose_tool test --all
# 测试单一算法
./tools/wolfcose_tool test -a ML-DSA-87
```
### 支持的 CLI 算法
```
ES256, EdDSA, Ed448, PS256, PS384, PS512,
ML-DSA-44, ML-DSA-65, ML-DSA-87,
A128GCM, A192GCM, A256GCM, ChaCha20, AES-CCM,
HMAC256, HMAC384, HMAC512
```
## 在真实硬件上部署
### 交叉编译
```
# 示例：ARM Cortex-M 与 arm-none-eabi-gcc
make CC=arm-none-eabi-gcc \
CFLAGS="-std=c99 -Os -mcpu=cortex-m4 -mthumb \
-I./include -I/path/to/wolfssl/include \
-DWOLFSSL_USER_SETTINGS"
```
请提供一个包含您的 wolfSSL 配置的 `user_settings.h`，以代替 `wolfssl/options.h`。有关嵌入式构建选项，请参阅 [wolfSSL 手册](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter02.html)。
### 针对受限目标的调优
```
/* In your user_settings.h or build flags: */
/* Reduce scratch buffer (default 512, minimum depends on payload size) */
#define WOLFCOSE_MAX_SCRATCH_SZ 256
/* Reduce protected header buffer */
#define WOLFCOSE_PROTECTED_HDR_MAX 32
/* Reduce CBOR nesting depth (default 8) */
#define WOLFCOSE_CBOR_MAX_DEPTH 4
/* For PQC (ML-DSA), increase scratch and signature buffers */
/* #define WOLFCOSE_MAX_SCRATCH_SZ 8192 */
/* #define WOLFCOSE_MAX_SIG_SZ 4627 */
```
### 集成检查清单
1. 为您的目标构建仅包含所需算法的 wolfSSL
2. 链接 `libwolfcose.a`（或直接编译 `src/wolfcose_cbor.c` + `src/wolfcose.c`）
3. **不要**在生产固件中包含 `tools/` 或 `examples/`
4. 将密钥预置在安全存储中 -- 参见 `lifecycle_demo.c 了解模式`
5. 调用者拥有所有 `WC_RNG`、密钥、缓冲区的生命周期 -- wolfCOSE 从不分配内存
### 栈预算
各函数的栈使用情况（来自 `-fstack-usage`，GCC，`-Os`，aarch64）：
| Function | Stack (bytes) |
|----------|--------------|
| `wc_CoseSign1_Sign` | 464 |
| `wc_CoseSign1_Verify` | 288 |
| `wc_CoseEncrypt0_Encrypt` | 1120 |
| `wc_CoseEncrypt0_Decrypt` | 1072 |
| `wc_CoseMac0_Create` | 1104 |
| `wc_CoseMac0_Verify` | 1072 |
| `wc_CoseKey_Encode` | 352 |
| `wc_CoseKey_Decode` | 224 |
| `wc_CBOR_Skip` | 112 |
| CBOR encode/decode | 0-48 |
## CI / 测试
wolfCOSE 在每次推送和拉取请求时运行以下 CI 检查：
- **构建和测试** -- Ubuntu (latest + 22.04), macOS，包含完整的单元测试套件
- **多编译器** -- GCC 10/11/12/13/14 和 Clang 14/15/16/17/18
- **示例** -- 生命周期演示（11 种算法）和工具往返测试（17 种算法）
- **静态分析** -- cppcheck, Clang analyzer, GCC `-fanalyzer`
- **Coverity Scan** -- 每晚缺陷分析
## 许可证
wolfCOSE 是根据 [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html) 许可的自由软件。
Copyright (C) 2026 wolfSSL Inc.
## 支持
如需商业许可、支持和 FIPS 验证构建，请联系 [wolfSSL](https://www.wolfssl.com/contact/)。
## 许可证
wolfCOSE 是根据 [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html) 许可的自由软件。
Copyright (C) 2026 wolfSSL Inc.
## 支持
如需商业许可、支持和 FIPS 验证构建，请联系 [wolfSSL](https://www.wolfssl.com/contact/)。标签：CBOR, CNSA 2.0, COSE, CVE, DNS 反向解析, ECDSA, Ed25519, FIPS 140-3, IoT安全, MISRA C, ML-DSA, PQC, RFC 8949, RFC 9052, RSA-PSS, wolfCrypt, wolfSSL, 低功耗安全, 后量子密码学, 完整性校验, 客户端加密, 客户端加密, 嵌入式加密, 数字签名, 数据加密, 本体建模, 物联网, 资源受限环境, 轻量级库, 零分配, 零拷贝, 静态分配