RustedBytes/wolfcose

# wolfcose [](https://github.com/RustedBytes/wolfcose/actions/workflows/ci.yml) [](https://crates.io/crates/wolfcose) 用于 wolfSSL wolfCOSE 绑定和高级 COSE/CBOR API 的 Rust workspace。 本仓库提供： - `wolfcose-sys`：用于 wolfSSL/wolfCOSE 的底层 unsafe C 绑定。 - `wolfcose`：安全的 Rust API，包含 builders、类型化的 headers/messages、CBOR helpers、examples 和 benchmarks。 - `wolfcose-derive`：`#[derive(CborSerialize, CborDeserialize)]` macros，用于实现类似 serde 的 CBOR 模型，且不依赖 serde。 默认构建会 vendor wolfCOSE，并通过 `wolfcose-sys` 从源码拉取并构建 wolfSSL。wolfCOSE 和 wolfSSL 是 GPL/商业双授权项目；如需商业授权，请联系 wolfSSL。 ## 你可以构建什么 `wolfcose` 适用于需要交换已签名、已加密或已认证的 CBOR 消息的软件： - 固件更新和供应链元数据系统 - IoT 遥测和命令协议 - 安全的设备配置分发 - COSE 检查/签名/加密 CLI 工具 - 需要 CBOR 数据模型和 COSE envelopes 的嵌入式协议 SDK 高级 crate 包含了一个安全的无人机遥测/控制协议示例，该示例使用了加密遥测（`COSE_Encrypt0`）和已认证的命令（`COSE_Mac0`）。 ## 快速开始 运行 workspace 测试： ``` cargo test --workspace ``` 对于本地开发，推荐使用 `just` recipes： ``` just fmt-check just test just lint just check-wolfcose-alloc ``` 运行无人机协议示例： ``` cargo run -p wolfcose --example drone_protocol ``` 运行无人机协议 benchmark： ``` just bench-drone ``` ## 高级示例 ``` use wolfcose::{Algorithm, CoseKeyBuilder, Mac0Builder, PayloadMode}; let key = CoseKeyBuilder::symmetric([0x33u8; 32]) .algorithm(Algorithm::HMAC256) .kid(b"device-a") .build()?; let msg = Mac0Builder::new() .key(&key) .algorithm(Algorithm::HMAC256) .kid(b"device-a") .payload(PayloadMode::Attached(b"hello wolfCOSE")) .mac_to_vec()?; # let _ = msg; # Ok::<(), wolfcose::Error>(()) ``` ## API 覆盖范围 `wolfcose-sys` 绑定了公开的 wolfCOSE header 接口，包括： - 所有 `wc_CBOR_*` 函数 - 所有 `wc_CoseKey_*` 函数 - COSE_Sign1 和 COSE_Sign API - COSE_Encrypt0 和 COSE_Encrypt API - COSE_Mac0 和 COSE_Mac API - 公开的 `WOLFCOSE_*` 常量和结构体 - 引用的 wolfCrypt key/RNG 类型 `wolfcose` 为相同的操作组提供了安全 wrappers 和高级 API： - CBOR encoders/decoders 以及类似 serde 的 `to_vec` / `to_slice` / `from_slice` - 用于结构体和外部标记 enums 的 derive macros - 用于 Sign1、Sign、Encrypt0、Encrypt、Mac0 和 Mac 的 builders - 类型化的 headers 和已解析的 message envelopes - 对称 key builders 和 COSE_Key 元数据视图 - 可选的详细 CBOR/COSE 错误上下文 - 通过 `wolfcose::raw` 提供的显式原始 FFI escape hatch 可选的由 wolfSSL 支持的 key attachment 和 CBOR float 函数通过稳定的 shim-backed 方法暴露，当链接的 wolfSSL/wolfCOSE 构建未包含底层特性时，这些方法将返回 `Error::Unsupported`。 ## 特性和构建模式 默认的 `wolfcose` 特性集为： - `std` - `alloc` - `vendored` - `full` - `derive` 要进行真正的 no-std/no-alloc 高级构建，请禁用默认特性并仅保留 vendored 操作接口： ``` cargo check -p wolfcose --no-default-features --features "vendored full" ``` 此模式暴露了原始 CBOR encoder/decoder、基础 serializer traits、借用的 byte-string helpers、算法/key 类型常量、错误、stream item reader 以及 `wolfcose::raw`。依赖内存分配的 API（例如 builders、拥有的 keys、已解析的消息、动态 CBOR 值以及 `*_to_vec` helpers）需要启用 `alloc` 特性。 要在不使用 `std` 的情况下检查 `alloc`： ``` cargo check -p wolfcose --no-default-features \ --features "alloc derive vendored full" ``` 默认的 `wolfcose-sys` 特性集会 vendor wolfCOSE 并静态构建一个固定版本的 wolfSSL 源码 commit。对于离线构建，请预先填充 wolfSSL 源码树并设置： ``` WOLFSSL_SRC=/path/to/wolfssl ``` 要改为使用已安装的 wolfSSL，请禁用默认特性并启用 system 特性路径： ``` cargo test -p wolfcose-sys --no-default-features \ --features "vendored full system-wolfssl" ``` 请勿将 `--all-features` 作为默认的验证命令。它会启用诸如 `system-wolfssl` 和 `system-wolfcose` 之类的系统特性路径，这需要已安装的 headers/libraries，并且可能会在 CI 中失败。 CI 安全的 lint 命令已编码在 `just lint` 中。 ## 示例 示例位于 `crates/wolfcose/examples`： - `drone_protocol.rs`：安全的无人机遥测/控制协议。 - `builders.rs`：builder 优先的 Encrypt0 和 Mac0 流程。 - `derive_models.rs`：derive macros 和 CBOR 模型属性。 - `headers_messages.rs`：类型化的 COSE headers 和消息解析。 - `key_metadata.rs`：对称 keys 和 `CoseKeyView`。 - `detailed_errors.rs`：可选的详细解码错误。 - `stream_reader.rs`：顶层 CBOR item reader。 - `cbor.rs`、`encrypt0.rs`、`mac0.rs`、`multi_recipient.rs`：针对性的 API 示例。 - `sign1.rs`、`multi_sign.rs`：非对称签名 API 指南；真正的签名需要调用者拥有的 wolfCrypt keys。 Benchmarks 位于 `crates/wolfcose/benches`。 ## 开发 有用的命令： ``` just ci just docs just package cargo check -p wolfcose --examples cargo bench -p wolfcose --bench drone_protocol -- --test ``` GitHub workflow 会运行： ``` just fmt-check just test just lint just check-wolfcose-alloc ``` 有关特性选择、FFI 安全性、高质量 Rust 标准以及安全敏感型加密示例的代码库特定指南，请参阅 `AGENTS.md`。 ## 许可 wolfCOSE 和 wolfSSL 是 GPL/商业双授权项目。本 workspace 使用与 GPL 兼容的元数据。如果您的使用场景与 GPL 条款不兼容，请联系 wolfSSL 获取商业授权。

标签：CBOR, COSE, Rust, wolfSSL, 可视化界面, 密码学, 嵌入式开发, 手动系统调用, 物联网, 网络流量审计, 通知系统