# cbor2

A serde implementation of [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
— the Concise Binary Object Representation (CBOR) — for Rust.

[![CI](https://github.com/ldclabs/cbor2/actions/workflows/ci.yml/badge.svg)](https://github.com/ldclabs/cbor2/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/cbor2.svg)](https://crates.io/crates/cbor2)
[![docs.rs](https://docs.rs/cbor2/badge.svg)](https://docs.rs/cbor2)

CBOR adopts and modestly builds on the *data model* used by JSON, except the
encoding is in binary form. Its primary goals include a balance of
implementation size, message size and extensibility. `cbor2` brings it to
any `serde::Serialize`/`Deserialize` type, on `std` and `no_std` targets
alike, with a dynamic `Value` type, deterministic encoding, tag support and
first-class COSE ergonomics on top.

Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org).

## Quick start

```toml
[dependencies]
cbor2 = "1"
```

```rust
use serde::{Deserialize, Serialize};

#[derive(Debug, PartialEq, Deserialize, Serialize)]
struct Photo {
    title: String,
    pixels: (u32, u32),
    tags: Vec<String>,
}

let photo = Photo {
    title: "Sunrise".into(),
    pixels: (1920, 1080),
    tags: vec!["morning".into(), "gradient".into()],
};

let bytes = cbor2::to_vec(&photo).unwrap();
let back: Photo = cbor2::from_slice(&bytes).unwrap();
assert_eq!(photo, back);
```

`to_writer` and `from_reader` work with any `std::io::Write`/`Read`, and
`Deserializer::into_iter` decodes a stream of concatenated items.
`from_slice`/`from_reader` read one leading CBOR item; use `validate` when
a buffer must contain exactly one item.

## Highlights

* **Full serde integration** — `#[derive(Serialize, Deserialize)]` types
  encode and decode directly.
* **RFC 8949 preferred serialization** — integers and floats are always
  encoded in their smallest lossless form, including half-precision floats.
* **A dynamic `Value` type** — the CBOR analogue of `serde_json::Value`,
  with a `cbor!` macro for building values in JSON-like syntax.
* **Tag support** — capture and emit semantic tags (RFC 8949 §3.4) through
  the wrapper types in the `tag` module; `u128`/`i128` map to bignum tags
  automatically.
* **Deterministic encoding** — `to_canonical_vec`/`to_canonical_writer` and
  `Value::canonicalize` implement the core deterministic encoding
  requirements (RFC 8949 §4.2.1): bytewise lexicographic map key order,
  definite lengths, preferred serializations, normalized bignums and NaN.
  For protocols built on the older RFC 7049 §3.9 "Canonical CBOR" rule
  (kept as RFC 8949 §4.2.3, and used by ciborium's canonical module), the
  `*_with` variants take `KeyOrder::LengthFirst`.
* **Integer map keys and tags (COSE)** — with the `derive` feature,
  `#[derive(cbor2::Cbor)]` maps struct fields to integer keys
  (`#[cbor(key = 1)]`) and wraps the struct in a CBOR tag
  (`#[cbor(tag = 18)]`), as RFC 9052 requires, with no ambiguity against
  textual keys. Field names and the type name stay untouched, so the same
  types still serialize to plain JSON — `serde_json::to_string(&v)` just
  works, with the original field names and no tag. The declared keys and
  tag stay inspectable at runtime through the `cbor2::Cbor` trait.
* **Raw values** — `RawValue` keeps one item as validated, undecoded
  bytes: serializing splices them into the stream untouched and
  deserializing captures them byte for byte, for signature payloads,
  pass-through items and deferred decoding. `TryFrom` converts in both
  directions between `RawValue` and `Value`.
* **Robust decoding** — indefinite-length items, segmented strings,
  duplicate map keys, unknown tags and CBOR sequences (RFC 8742) are all
  handled; recursion is depth-limited and forged lengths cannot trigger
  huge allocations.
* **Diagnostic notation** — `diagnostic` renders raw CBOR as the
  human-readable text of RFC 8949 §8 (matching the Appendix A examples
  exactly, indefinite-length markers and all); `Value` implements
  `Display` with the same notation and `Debug` as its indented,
  multi-line form.
* **Allocation-free helpers** — `validate` checks that an input is exactly
  one well-formed CBOR item (RFC 8949 §5.3.1, including text UTF-8),
  `serialized_size` computes the exact encoded size of any serializable
  value and `to_slice` encodes into a caller-provided buffer; none of them
  allocates heap memory.
* **A low-level header codec** — the `core` module exposes the pull/push
  `Header` interface for applications that need precise wire control.
* **`no_std` support** — `default-features = false, features = ["alloc"]`
  keeps the full API minus `std::io` interop and `HashMap` conversions;
  without `alloc` the crate still serializes (`to_writer`/`to_slice`/
  `serialized_size`), validates and speaks the `core` header codec.

## Crate features

| Feature  | Default         | Effect                                                                                                                                               |
| -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `std`    | yes             | Implements the `cbor2::io` traits for every `std::io::Read`/`Write` and adds the `HashMap` conversions. Implies `alloc`.                             |
| `alloc`  | yes (via `std`) | Everything needing a heap: `Value`, `to_vec`/`from_slice`/`from_reader`, `RawValue`, `diagnostic`, the deterministic encoders and the `cbor!` macro. |
| `derive` | no              | The `#[derive(cbor2::Cbor)]` macro.                                                                                                                  |

With no features at all the crate is a `#![no_std]` core for constrained
targets: streaming serialization with `to_writer`/`to_slice`/
`serialized_size`, `validate`, the `tag` wrappers and the `core` header
codec. Deserializing through serde requires `alloc`. Readers and writers
implement the small `cbor2::io` traits, which are provided for byte slices
(and `Vec<u8>` with `alloc`):

```toml
[dependencies]
cbor2 = { version = "1", default-features = false } # or features = ["alloc"]
```

```rust
// Works on no_std + no alloc targets:
let mut buffer = [0u8; 64];
let item = cbor2::to_slice(&("id", 42u8), &mut buffer).unwrap();
assert!(cbor2::validate(&item[..]).is_ok());
```

## Guide

### Byte strings and `serde_bytes`

A common serde pitfall: bare `Vec<u8>` and `&[u8]` serialize as arrays of
integers, not as CBOR byte strings. Use
[`serde_bytes`](https://docs.rs/serde_bytes/latest/serde_bytes/) for binary
payloads.

```rust
let bytes = vec![1u8, 2, 3, 4];

// Bare Vec<u8>: [1, 2, 3, 4]
assert_eq!(hex::encode(cbor2::to_vec(&bytes).unwrap()), "8401020304");

// serde_bytes: h'01020304'
let bytes = serde_bytes::ByteBuf::from(bytes);
assert_eq!(hex::encode(cbor2::to_vec(&bytes).unwrap()), "4401020304");
```

For fields in derived structs, annotate byte buffers explicitly:

```rust
use serde::{Deserialize, Serialize};

#[derive(Debug, PartialEq, Deserialize, Serialize)]
struct Packet {
    #[serde(with = "serde_bytes")]
    payload: Vec<u8>,
}

let packet = Packet { payload: vec![0xde, 0xad, 0xbe, 0xef] };
assert_eq!(
    hex::encode(cbor2::to_vec(&packet).unwrap()),
    "a1677061796c6f616444deadbeef"
);
```

If you build data with `Value`, use `Value::Bytes(...)` or the `From`
implementations for byte slices/vectors; those already represent a CBOR
byte string.

### Integer map keys and tags: COSE with `#[derive(Cbor)]`

With the `derive` feature, `#[derive(cbor2::Cbor)]` generates the serde
`Serialize`/`Deserialize` impls with CBOR protocol details: fields
annotated `#[cbor(key = ...)]` use integer map keys and the container is
wrapped in a CBOR tag (`#[cbor(tag = ...)]`, required on decode). Field
names and the type name stay untouched, so the same types still
serialize to plain JSON.

```toml
[dependencies]
cbor2 = { version = "1", features = ["derive"] }
```

This reproduces the Simple Encrypted Message of
[RFC 9052, Appendix C.4.1](https://datatracker.ietf.org/doc/html/rfc9052#appendix-C.4)
byte for byte (52 bytes):

```rust
use cbor2::Cbor;

/// Protected header parameters (RFC 9052 §3.1). They travel as a byte
/// string holding their own CBOR encoding.
#[derive(Debug, PartialEq, Cbor)]
struct Protected {
    /// 10 = AES-CCM-16-64-128 (RFC 9053 §4.2)
    #[cbor(key = 1)]
    alg: i8,
}

/// Unprotected header parameters.
#[derive(Debug, PartialEq, Cbor)]
struct Unprotected {
    #[cbor(key = 5)]
    #[serde(with = "serde_bytes")]
    iv: Vec<u8>,
}

/// COSE_Encrypt0 (RFC 9052 §5.2): tag 16 around
/// `[protected: bstr, unprotected: map, ciphertext: bstr]`.
#[derive(Debug, PartialEq, Cbor)]
#[cbor(tag = 16)]
struct CoseEncrypt0(
    #[serde(with = "serde_bytes")] Vec<u8>, // protected, already encoded
    Unprotected,
    #[serde(with = "serde_bytes")] Vec<u8>, // ciphertext
);

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // The protected header is the encoded map {1: 10}.
    let protected = cbor2::to_canonical_vec(&Protected { alg: 10 })?;
    assert_eq!(hex::encode(&protected), "a1010a");

    let msg = CoseEncrypt0(
        protected,
        Unprotected {
            iv: hex::decode("89f52f65a1c580933b5261a78c")?,
        },
        hex::decode("5974e1b99a3a4cc09a659aa2e9e7fff161d38ce71cb45ce460ffb569")?,
    );

    // The RFC's 52-byte message, byte for byte.
    let bytes = cbor2::to_canonical_vec(&msg)?;
    assert_eq!(bytes.len(), 52);
    assert_eq!(
        hex::encode(&bytes),
        "d08343a1010aa1054d89f52f65a1c580933b5261a78c581c\
         5974e1b99a3a4cc09a659aa2e9e7fff161d38ce71cb45ce460ffb569"
    );

    println!("{}", cbor2::diagnostic(&bytes[..])?);
    // 16([h'a1010a', {5: h'89f52f65a1c580933b5261a78c'},
    //     h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce71cb45ce460ffb569'])

    // Decoding requires tag 16 and restores every layer.
    let back: CoseEncrypt0 = cbor2::from_slice(&bytes)?;
    assert_eq!(back, msg);
    let header: Protected = cbor2::from_slice(&back.0)?;
    assert_eq!(header, Protected { alg: 10 });

    // JSON stays natural — original field names, no tags, no integer keys.
    let json = serde_json::to_string(&header)?;
    assert_eq!(json, r#"{"alg":10}"#);
    Ok(())
}
```

The full program lives in [`examples/cose.rs`](examples/cose.rs):
`cargo run --features derive --example cose`.

The derive also implements the `cbor2::Cbor` trait, which exposes the
declared protocol details at runtime — `T::KEYS` and `T::TAG` as
allocation-free constants, and `value.keys()` as a
`BTreeMap<String, i128>`:

```rust
use cbor2::Cbor; // one import: the derive macro and the trait

assert_eq!(Protected::KEYS, &[("alg", 1)]);
assert_eq!(CoseEncrypt0::TAG, Some(16));
```

### Dynamic values

```rust
use cbor2::{cbor, Value};

let value = cbor!({
    "code": 415,
    "message": null,
    "extra": { "numbers": [8.2341e+4, 0.251425] },
}).unwrap();

let bytes = cbor2::to_vec(&value).unwrap();
let back: Value = cbor2::from_slice(&bytes).unwrap();
assert_eq!(value, back);
```

### Raw values

`RawValue` defers decoding and preserves the exact wire bytes of one item
— the right tool for signature payloads:

```rust
use serde::{Deserialize, Serialize};

#[derive(Debug, PartialEq, Deserialize, Serialize)]
struct Signed {
    #[serde(with = "serde_bytes")]
    signature: Vec<u8>,
    payload: cbor2::RawValue,
}

let bytes = cbor2::to_vec(&Signed {
    signature: vec![0xde, 0xad],
    payload: cbor2::RawValue::serialized(&("untouched", 42)).unwrap(),
}).unwrap();

let signed: Signed = cbor2::from_slice(&bytes).unwrap();
// Verify `signed.signature` over `signed.payload.as_bytes()`, then:
let (text, n): (String, u8) = signed.payload.deserialized().unwrap();
assert_eq!((text.as_str(), n), ("untouched", 42));
```

### Tags

```rust
use cbor2::tag::RequireExact;

// Tag 0: standard date/time string.
let datetime = RequireExact::<String, 0>("2013-03-21T20:04:00Z".into());
let bytes = cbor2::to_vec(&datetime).unwrap();
assert_eq!(bytes[0], 0xc0);
```

### CBOR sequences

```rust
let mut stream = Vec::new();
cbor2::to_writer(&"first", &mut stream).unwrap();
cbor2::to_writer(&2u64, &mut stream).unwrap();

let items: Vec<cbor2::Value> = cbor2::de::Deserializer::from_reader(&stream[..])
    .into_iter()
    .collect::<Result<_, _>>()
    .unwrap();

assert_eq!(items, vec![cbor2::Value::from("first"), cbor2::Value::from(2)]);
assert!(cbor2::validate(&stream[..]).is_err()); // a sequence is not one item
```

### More examples

Runnable examples live in `examples/`:

```bash
cargo run --example basic
cargo run --example bytes
cargo run --example sequence
cargo run --example core_headers
cargo run --features derive --example cose
```

## Design decisions

This implementation deliberately matches ciborium's wire behavior, so the
two crates interoperate byte for byte:

* Numbers always encode in their smallest lossless form, as deterministic
  encoding (RFC 8949 §4.2.1) requires. Integer width in Rust is treated as
  an in-memory detail, not a wire property.
* Enums encode as a bare string (unit variants) or a single-entry map
  `{variant: payload}` (everything else).
* `Value` maps are `Vec<(Value, Value)>`, preserving wire order and
  arbitrary keys.
* Decoding follows the robustness principle: indefinite lengths, segmented
  strings, half-width floats and unknown tags are accepted even though
  encoding never produces them.

## History

This project descends from the `cbor` crate created by
[Andrew Gallant](https://github.com/BurntSushi) in 2015, which was built on
the pre-serde `rustc-serialize` framework and went unmaintained for many
years. Version 0.5 was a from-scratch rewrite on top of
[serde](https://serde.rs), maintained by [LDC Labs](https://github.com/ldclabs)
and published as **`cbor2`** — the `cbor` name on crates.io stays with the
legacy 0.4 release — and 1.0 stabilizes it. None of the 0.4 API survives.

The rewrite follows the design of (and is wire-compatible with)
[ciborium](https://github.com/enarx/ciborium) — many thanks to its authors.

## Command line tools

The workspace ships two small converters in `cbor_conv`:

```bash
$ echo '{"name": "example", "ok": true}' | json2cbor | cbor2json
{
  "name": "example",
  "ok": true
}
```

## Testing

`cargo test` runs the unit tests, a single integration-test binary and the
doc tests — including the RFC 8949 Appendix A vectors and fault-injection
tests for I/O failures and malformed input. CI builds and tests every
feature combination, down to a bare-metal `no_std` target. Coverage
measured with `cargo llvm-cov` is 100% of functions and about 98% of
lines; the only never-executed lines are defensive branches that cannot
occur, such as error paths that the `RawValue` validity invariant rules
out.

## Minimum supported Rust version

Rust 1.85.

## License

Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org), like the
original crate.
