wolfcose

Rust workspace for wolfSSL wolfCOSE bindings and high-level COSE/CBOR APIs.

This repository provides:

• wolfcose-sys: low-level unsafe C bindings to wolfSSL/wolfCOSE.
• wolfcose: safe Rust API with builders, typed headers/messages, CBOR helpers, examples, and benchmarks.
• wolfcose-derive: #[derive(CborSerialize, CborDeserialize)] macros for serde-like CBOR models without depending on serde.

The default build vendors wolfCOSE and pulls/builds wolfSSL from source through wolfcose-sys. wolfCOSE and wolfSSL are GPL/commercial dual-license projects; contact wolfSSL for commercial licensing.

What You Can Build

wolfcose is intended for software that exchanges signed, encrypted, or authenticated CBOR messages:

• firmware update and supply-chain metadata systems
• IoT telemetry and command protocols
• secure device configuration delivery
• COSE inspection/sign/encrypt CLI tools
• embedded protocol SDKs that need CBOR data models and COSE envelopes

The high-level crate includes a secured drone telemetry/control protocol example that uses encrypted telemetry (COSE_Encrypt0) and authenticated commands (COSE_Mac0).

Quick Start

Run the workspace tests:

cargo test --workspace

Prefer the just recipes for local development:

just fmt-check
just test
just lint
just check-wolfcose-alloc

Run the drone protocol example:

cargo run -p wolfcose --example drone_protocol

Run the drone protocol benchmark:

just bench-drone

High-Level Example

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 Coverage

wolfcose-sys binds the public wolfCOSE header surface, including:

• all wc_CBOR_* functions
• all wc_CoseKey_* functions
• COSE_Sign1 and COSE_Sign APIs
• COSE_Encrypt0 and COSE_Encrypt APIs
• COSE_Mac0 and COSE_Mac APIs
• public WOLFCOSE_* constants and structs
• referenced wolfCrypt key/RNG types

wolfcose provides safe wrappers and higher-level APIs for the same operation groups:

• CBOR encoders/decoders and serde-like to_vec / to_slice / from_slice
• derive macros for structs and externally tagged enums
• builders for Sign1, Sign, Encrypt0, Encrypt, Mac0, and Mac
• typed headers and parsed message envelopes
• symmetric key builders and COSE_Key metadata views
• opt-in detailed CBOR/COSE error context
• explicit raw FFI escape hatch through wolfcose::raw

Optional wolfSSL-backed key attachment and CBOR float functions are exposed through stable shim-backed methods that return Error::Unsupported when the linked wolfSSL/wolfCOSE build does not include the underlying feature.

Features and Build Modes

The default wolfcose feature set is:

• std
• alloc
• vendored
• full
• derive

For a true no-std/no-alloc high-level build, disable default features and keep only the vendored operation surface:

cargo check -p wolfcose --no-default-features --features "vendored full"

This mode exposes the raw CBOR encoder/decoder, primitive serializer traits, borrowed byte-string helpers, algorithm/key type constants, errors, stream item reader, and wolfcose::raw. Allocation-backed APIs such as builders, owned keys, parsed messages, dynamic CBOR values, and *_to_vec helpers require the alloc feature.

To check alloc without std:

cargo check -p wolfcose --no-default-features \
  --features "alloc derive vendored full"

The default wolfcose-sys feature set vendors wolfCOSE and builds a pinned wolfSSL source commit statically. For offline builds, pre-populate a wolfSSL source tree and set:

WOLFSSL_SRC=/path/to/wolfssl

To use an installed wolfSSL instead, disable defaults and enable the system feature path:

cargo test -p wolfcose-sys --no-default-features \
  --features "vendored full system-wolfssl"

Do not use --all-features as the default validation command. It enables system feature paths such as system-wolfssl and system-wolfcose, which require installed headers/libraries and can fail in CI.

CI-safe lint commands are encoded in just lint.

Examples

Examples live in crates/wolfcose/examples:

• drone_protocol.rs: secured drone telemetry/control protocol.
• builders.rs: builder-first Encrypt0 and Mac0 flow.
• derive_models.rs: derive macros and CBOR model attributes.
• headers_messages.rs: typed COSE headers and message parsing.
• key_metadata.rs: symmetric keys and CoseKeyView.
• detailed_errors.rs: opt-in detailed decode errors.
• stream_reader.rs: top-level CBOR item reader.
• cbor.rs, encrypt0.rs, mac0.rs, multi_recipient.rs: focused API examples.
• sign1.rs, multi_sign.rs: asymmetric signing API guidance; real signing requires caller-owned wolfCrypt keys.

Benchmarks live in crates/wolfcose/benches.

Development

Useful commands:

just ci
just docs
just package
cargo check -p wolfcose --examples
cargo bench -p wolfcose --bench drone_protocol -- --test

The GitHub workflow runs:

just fmt-check
just test
just lint
just check-wolfcose-alloc

See AGENTS.md for codebase-specific guidance on feature selection, FFI safety, high-quality Rust standards, and security-sensitive crypto examples.

Licensing

wolfCOSE and wolfSSL are GPL/commercial dual-license projects. This workspace uses GPL-compatible metadata. Contact wolfSSL for commercial licensing if your use case is not compatible with GPL terms.