zbor - a CBOR en-/ decoder

I've been toying around with WebAuthn for a couple of months. For those who have never heard of it, it's part of the FIDO2 standard and used for registering and authenticating users to a Relying Party (Server) using public key cryptography. Some say it's the next big thing and will eradicate passwords once and for all. I'd say you trade one problem for another, but maybe the new one is better from an IT-Security perspective. But that's not what I want to talk about.

Some data like the attestationObject, which is part of the credential object returned from the create() function call, is encoded using the Concise Binary Object Representation (CBOR). If you want to read more about WebAuthn, I recommend the WebAuthn guide by Suby Raman. During my tests, I found that the C++ JSON library with CBOR support I used has issues decoding captured credential objects, so I had three options.

1. read through the source code and find the problem.
2. try out another library.
3. use this new programming language, I wanted to try for a while now and implement a CBOR en-/decoder that fits my needs.

As you might have guessed, I chose the third option. You can find the project on Github.

zbor

In general CBOR encodes data in so called data items. A data item can contain zero, one or more nested data items, and each belongs to one of seven major types (unsigned integer, signed integer, byte string, text string, data item array, (key, value) map, tagged data item or simple value). The library reflects this structure using a tagged union (DataItem) where each field is associated with one of the seven major types.

/// A single piece of CBOR data.
///
/// The structure of a DataItem may contain zero, one, or more nested DataItems.
pub const DataItem = union(DataItemTag) {
        /// Major type 0 and 1: An integer in the range -2^64..2^64-1
    int: i128,
    /// Major type 2: A byte string.
    bytes: []u8,
    /// Major type 3: A text string encoded as utf-8.
    text: []u8,
    /// Major type 4: An array of data items.
    array: []DataItem,
    /// Major type 5: A map of pairs of data items.
    map: []Pair,
    /// Major type 6: A tagged data item.
    tag: Tag,
    /// Major type 7: IEEE 754 Half-, Single-, or Double-Precision float.
    float: Float,
    /// Major type 7: Simple value [false, true, null]
    simple: SimpleValue,

    // more code...
}

The three most significant bits of the first byte of a data item encode the major type and the remaining 5 bits give additional information, usually how to load an unsigned integer that represents a value (major type 0, 1 and 7) or a size (major type 2, 3, 4 and 5).

The unsigned integer 65536 is for example encoded as 1a 00 01 00 00. 1a = 0001 1010 can be split into major type 000 = 0 and additional information 11010 = 26, i.e. the next four bytes encode an unsigned integer (see CBOR encoding). Note that CTAP2 canonical CBOR encoding requires that integers are encoded as small as possible.

If you want to encode 65536 using the library you can define a DataItem and pass it to the encode() function. This function will return a std.ArrayList(u8) containing the CBOR byte string on success, or an CborError otherwise.

var gpa = std.heap.GeneralPurposeAllocator(.{}){};
const allocator = gpa.allocator();

const data_item = DataItem.int(65536);
const cbor = try encode(allocator, &data_item);
defer cbor.deinit();

try std.testing.expectEqualSlices(u8, &.{ 0x1a, 0x00, 0x01, 0x00, 0x00 }, cbor.items);

To decode a CBOR byte string just use the decode() function, which will return a (nested) DataItem on success.

const di = try decode(allocator, cbor);
// Always use deinit() to free the allocated memory of all
// (nested) data items.
defer di.deinit(allocator);

This is just a trivial example but you can also decode more complex CBOR data like a attestationObject. If you're interested, please take a look at the zbor repo.

current state

Encoder and decoder support most of the types defined by RFC 8949. The next thing I want to add is serialization from and to JSON. If you have any suggestions feel free to open a issue or just leave a comment :).

Edit - 29.07.2022

Loris Cro suggested slices instead of std.Arraylis. He told me about the approach to ask the user to provide an Allocator to any function call that might need it. Because the same Allocator is usually used for every (nested) DataItem, the approach seemed to fit quite well with my use case and I adopted it.