CBOR Decoder

CBOR (Concise Binary Object Representation)

CBOR is defined in RFC 8949 as a binary data format inspired by JSON but more compact and efficient. It is used in FIDO2/CTAP2 for communication between browsers and authenticators, in COSE (CBOR Object Signing and Encryption) for signed and encrypted data, and in IoT protocols.

Encoding Structure

Each CBOR data item starts with a header byte: the upper 3 bits are the major type (0-7), the lower 5 bits are additional information (0-23 for direct value, 24-27 for 1/2/4/8 byte following values, 31 for indefinite length). Major types: 0 = unsigned integer, 1 = negative integer, 2 = byte string, 3 = text string, 4 = array, 5 = map, 6 = tagged value, 7 = simple values and floats. Maps use key-value pairs, arrays use sequential items. Indefinite length encoding allows streaming.

Use in FIDO2

In CTAP2, the browser sends CBOR-encoded commands to the authenticator. For example, a MakeCredential (registration) request contains: 0x01 (command ID), followed by a CBOR map with keys like clientDataHash (byte string), rp (map with id and name), user (map with id, name, displayName), pubKeyCredParams (array of algorithms), and options (map with flags). The authenticator responds with a CBOR map containing the credential ID, public key (in COSE format), and authenticator data. Use our FIDO2 Parser to decode authenticator responses.

CBOR vs JSON vs MessagePack vs BSON

CBOR was designed by the IETF (RFC 8949) specifically for constrained devices and deterministic encoding. JSON is text-based, human-readable, but verbose and ambiguous about number types (JSON has no distinction between integer and float). MessagePack is another binary JSON alternative, popular in RPC frameworks, but it lacks CBOR's deterministic encoding mode and semantic tagging system. BSON (Binary JSON, used by MongoDB) focuses on MongoDB's specific needs and includes non-standard types like ObjectId. CBOR's advantages include: compact encoding (integers 0-23 use a single byte, vs 2-3 bytes in JSON), deterministic encoding mode for cryptographic signatures (important for COSE), built-in byte string type (JSON requires Base64 encoding), semantic tags for standard types like timestamps and URLs, and streaming via indefinite-length encoding. For IoT and security protocols, CBOR is the preferred choice.

COSE (CBOR Object Signing and Encryption)

COSE (RFC 8152) is the CBOR-based equivalent of JOSE (JWT/JWS/JWE). It defines how to sign and encrypt CBOR data structures. A COSE_Sign1 structure contains a protected header (CBOR map with algorithm, key ID), an unprotected header (same but not integrity-protected), a payload (byte string), and a signature byte string. In FIDO2, the attestation object returned by an authenticator during registration uses COSE to package the attestation signature. The credential public key itself is a COSE_Key structure — a CBOR map with keys like 1 (kty: key type), 3 (alg: algorithm), -1 (crv: curve), -2 (x: public x-coordinate), -3 (y: public y-coordinate). Our decoder shows these as nested maps with numeric keys.

CTAP2 Command Structure

CTAP2 (Client to Authenticator Protocol version 2) wraps CBOR with a single-byte command prefix. The authenticator receives a byte stream where byte 0 is the command ID (0x01=MakeCredential, 0x02=GetAssertion, 0x03=GetInfo, 0x04=ClientPIN, 0x06=Reset, etc.) and the remaining bytes are a CBOR-encoded parameter map. The response is similarly structured: byte 0 is the status code (0x00=OK), followed by a CBOR-encoded result. When debugging FIDO2 issues, decode the CBOR portion to inspect the parameters. Common issues include: wrong rp.id (must match the origin domain), pubKeyCredParams listing unsupported algorithms (ES256 is widely supported, RS256 is not on all authenticators), and userVerification requirement not met by the authenticator's capabilities.

Indefinite Length and Streaming

CBOR supports indefinite-length encoding for arrays, maps, byte strings, and text strings. Instead of specifying the length upfront, the encoder uses the break code (0xFF) as a terminator. This is useful when the producer doesn't know the total length in advance — for example, streaming sensor data from an IoT device where the array grows until a time window closes. The decoder must handle this by reading items until it encounters the break code. Our decoder currently expects definite-length encoding (the common case in FIDO2 and COSE), but indefinite-length data appears in SenML (RFC 8428) batch streams and some CBOR-based logging formats.