CBOR

Concise Binary Object Representation (CBOR) is a binary data serialization format loosely based on JSON. Like JSON it allows the transmission of data objects that contain name–value pairs, but in a more concise manner. This increases processing and transfer speeds at the cost of human-readability. It is defined in IETF RFC 8949.[1]

CBOR
Filename extension
.cbor
Internet media type
application/cbor
Type of formatData interchange
StandardRFC 8949
Open format?Yes
Websitecbor.io

Amongst other uses, it is the recommended data serialization layer for the CoAP Internet of Things protocol suite[2] and the data format on which COSE messages are based. It is also used in the Client-to-Authenticator Protocol (CTAP) within the scope of the FIDO2 project.[3]

Specification of the CBOR encoding

CBOR encoded data is seen as a stream of data items. E.g.

CBOR data Data item 1 Data item 2 Data item X...
Byte count 1 byte (CBOR data item header) Variable Variable 1 byte (CBOR data item header) Variable Variable etc...
Structure Major type Additional information Payload length (optional) Data payload (optional) Major type Additional information Payload length (optional) Data payload (optional) etc...
Bit count 3 Bits 5 Bits 8 Bits × variable 8 Bits × variable 3 Bits 5 Bits 8 Bits × variable 8 Bits × variable etc..

Major type and additional type handling in each data item

Each data item behaviour is defined by the major type and additional type. The major type is used for selecting the main behaviour or type of each data item.

The additional type is additional information whose exact behaviour is dependent on the major type value.

Tiny Field Encoding

Byte count 1 byte (CBOR data item header)
Structure Major type Additional information (Value)
Bit count 3 Bits 5 Bits

Short Field Encoding

Byte count 1 byte (CBOR data item header) Variable
Structure Major type Additional information Value
Bit count 3 Bits 5 Bits 8 Bits × (Value_Field_Byte_Count)

Long Field Encoding

Byte count 1 byte (CBOR data item header) Variable Variable
Structure Major type Additional information (Size Of Length Field) Payload length (Length Of Value Field) Value
Bit count 3 Bits 5 Bits 8 Bits × (Length_Field_Byte_Count) 8 Bits × (Value_Field_Byte_Count)

CBOR data item header

The table below illustrates how the CBOR data item header works.

Major type Major type value Additional type value (unsigned) Additional type meaning Item Size In Bytes Field Encoding Type
Positive/Unsigned integer 0 0b000 The 5-bit additional information is either the integer itself (for additional information values 0 through 23) or the length of additional data.
0 to 23 (0x0 to 0x17) (0b00000 to 0b10111) Used directly as the data value. Thus keeping a compact size. 1 Tiny
24 Next byte is uint8_t in data value section 2 Short
25 Next 2 bytes uint16_t in data value section 3 Short
26 Next 4 bytes is uint32_t in data value section 5 Short
27 Next 8 bytes is uint64_t in data value section 9 Short
... ... ... ...
31 ... ... ...
Negative integer 1 0b001 The encoding follows the rules for unsigned integers (major type 0), except that the value is then -1 minus the encoded unsigned integer.
0 to 23 (0x0 to 0x17) (0b00000 to 0b10111) Used directly as the data value. Thus keeping a compact size. 1 Tiny
24 Next byte is uint8_t in data value section 2 Short
25 Next 2 bytes uint16_t in data value section 3 Short
26 Next 4 bytes is uint32_t in data value section 5 Short
27 Next 8 bytes is uint64_t in data value section 9 Short
... ... ... ...
31 ... ... ...
Byte string 2 0b010 The string's length in bytes is represented following the rules for positive integers (major type 0).
0 to 23 (0x0 to 0x17) (0b00000 to 0b10111) Used directly as the data length specifier. Thus keeping a compact size. up to 1+23 Short
24 Next byte is uint8_t for payload length up to 2+2^8-1 Long
25 Next 2 bytes uint16_t for payload length up to 3+2^16-1 Long
26 Next 4 bytes is uint32_t for payload length up to 5+2^32-1 Long
27 Next 8 bytes is uint64_t for payload length up to 9+2^64-1 Long
... ... ... ...
31 Start of Indefinite String: Concatenation of definite-length strings, till next corresponding "Break" Code. 1 Tiny
Text string 3 0b011 A text string, specifically a string of Unicode characters that is encoded as UTF-8 [RFC3629].
0 to 23 (0x0 to 0x17) (0b00000 to 0b10111) Used directly as the data length specifier. Thus keeping a compact size. up to 1+23 Short
24 Next byte is uint8_t for payload length up to 2+2^8-1 Long
25 Next 2 bytes uint16_t for payload length up to 3+2^16-1 Long
26 Next 4 bytes is uint32_t for payload length up to 5+2^32-1 Long
27 Next 8 bytes is uint64_t for payload length up to 9+2^64-1 Long
... ... ... ...
31 Start of Indefinite String: Concatenation of definite-length strings, till next corresponding "Break" Code. 1 Tiny
Array of data items 4 0b100 Arrays are also called lists, sequences, or tuples. The length denotes the number of data items in array rather than the byte length.
0 to 23 (0x0 to 0x17) (0b00000 to 0b10111) Used directly as the item count specifier. Thus keeping a compact size. 1 Tiny
24 Next byte is uint8_t for payload length 2 Short
25 Next 2 bytes uint16_t for payload length 3 Short
26 Next 4 bytes is uint32_t for payload length 5 Short
27 Next 8 bytes is uint64_t for payload length 9 Short
... ... ... ...
31 Start of Indefinite Array till next corresponding "Break" Code. 1 Tiny
Map of pairs of data items 5 0b101 A map of pairs of data items. Maps are also called tables, dictionaries, hashes, or objects (in JSON).

The length denotes the number of pairs of data items rather than the byte length.

Every map entry takes two data items in sequential order, a key data item and a value data item.

0 to 23 (0x0 to 0x17) (0b00000 to 0b10111) Used directly as the item count specifier. Thus keeping a compact size. 1 Tiny
24 Next byte is uint8_t for payload length 2 Short
25 Next 2 bytes uint16_t for payload length 3 Short
26 Next 4 bytes is uint32_t for payload length 5 Short
27 Next 8 bytes is uint64_t for payload length 9 Short
... ... ... ...
31 Start of indefinite map till next corresponding "break" code. 1 Tiny
Semantic tag 6 0b110 Used for optional semantic tagging of other major types
Value Field represents Tag ID: Refer to https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml for the semantic meaning of each tag.
0 to 23 (0x0 to 0x17) (0b00000 to 0b10111) Used directly as the data value. Thus keeping a compact size. 1 Tiny
24 Next byte is uint8_t in data value section 2 Short
25 Next 2 bytes uint16_t in data value section 3 Short
26 Next 4 bytes is uint32_t in data value section 5 Short
27 Next 8 bytes is uint64_t in data value section 9 Short
... ... ... ...
31 ... 1 ...
Primitives

e.g. break,

float,

simple values

7 0b111 floating-point numbers and simple data types that need no content, as well as the "break" stop code[4]
0..19 (Unassigned) 1 Tiny
20 False 1 Tiny
21 True 1 Tiny
22 Null 1 Tiny
23 Undefined 1 Tiny
24 Next Byte is uint8_t as Simple value (value 32..255) 2 Short
25 Next 2 Bytes uint16_t as IEEE 754 half-precision float 3 Short
26 Next 4 Bytes is uint32_t as IEEE 754 single-precision float 5 Short
27 Next 8 Bytes is uint64_t as IEEE 754 double-precision float 9 Short
28 Unassigned
29
30
31 "break" stop code for indefinite-length items 1 Tiny
  • Byte = 8 bits

Primitives (Major type = 7)

The primitives major type has a major type value of 7. It is used for simple data types, common complex float types, as well as control code.

Major type Additional value Extra bytes (if required)
Bytes 0 1 2 3 4 5 6 7 8
Bit size 3 bits 5 bits 8 8 8 8 8 8 8 8
Simple value 0 to 23 (value X) 7 X=0...23 Not used
Simple value 24 to 255 (value X) 7 24 X=32...255 Not used
IEEE 754 half-precision float (16 bits follow) 7 25 16 bits IEEE 754 Not used
IEEE 754 single-precision float (32 bits follow) 7 26 32 bits IEEE 754 Not used
IEEE 754 double-precision float (64 bits follow) 7 27 64 bits IEEE 754
Break from indefinite array or map 7 31 Not used

Break control code (Additional type value = 31)

This is a meta value, that is used in conjunction with arrays and maps set to indefinite length mode. This indicates to the CBOR parser to close the corresponding map or array level.

IEEE 754 Floats (Additional type value = 25 or 26 or 27)

This allows for storing floats, encoded as IEEE 754 float values.

Simple value

Most simple values are either unassigned or reserved for future improvements.

However these are defined.

Simple value Semantic
20 Boolean false
21 Boolean true
22 Null
23 Undefined

Semantic Tag Registration

IANA has created the CBOR tags registry, located in https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml . Registration must contain these template.

Semantic tag type Range Template
Data item Semantic description (Short Form) Point of contact Description of semantics (URL)
Standard actions 0–23 Required Required N/A N/A
Specification required 24–255 Required Required N/A N/A
First Come First Served 256–18446744073709551615 Required Required Required Description is optional.

The URL can point to an Internet-Draft or a web page.

https://www.rfc-editor.org/rfc/rfc8949.html#name-cbor-tags-registry

Implementations

Name Primary author Language License Source Remarks
cbor-js Patrick Gansterer JavaScript MIT https://github.com/paroga/cbor-js
node-cbor Joe Hildebrand JavaScript MIT https://github.com/hildjj/node-cbor
CBOREncode Pavel Gulbin PHP PHP https://github.com/2tvenom/CBOREncode
cbor Faye Amacker Go MIT https://github.com/fxamacker/cbor Safe & fast, CBOR tags, float64/32/16, duplicate map key detection, API is encoding/json + toarray & keyasint struct tags, Canonical CBOR, CTAP2, fuzz tested.
cbor Pavel Gulbin Go WTFPL https://github.com/2tvenom/cbor
cbor_go Brian Olson Go APL 2.0 https://github.com/brianolson/cbor_go
go-codec Ugorji Nwoke Go MIT https://godoc.org/github.com/ugorji/go/codec Also handles JSON, MsgPack and BinC.
serde_cbor Pyfisch Rust MIT or APL 2.0 https://github.com/pyfisch/cbor
cbor-codec Toralf Wittner Rust MPL 2.0 https://twittner.gitlab.io/cbor-codec/cbor/
SwiftCBOR [email protected] Swift Unlicense https://github.com/myfreeweb/SwiftCBOR
CBOR.jl Saurav Sachidanand Julia MIT https://github.com/saurvs/CBOR.jl
Lua-CBOR Kim Alvefur Lua MIT https://www.zash.se/lua-cbor.html
org.conman.cbor Sean Conner Lua LGPL-3 https://github.com/spc476/CBOR
cbor_py Brian Olson Python APL 2.0 https://github.com/brianolson/cbor_py
flynn Fritz Conrad Grimpen Python MIT https://github.com/fritz0705/flynn
cbor2 Alex Grönholm Python MIT https://github.com/agronholm/cbor2
CBOR::Free Felipe Gasper Perl Artistic & GPL https://metacpan.org/pod/CBOR::Free
CBOR::PP Felipe Gasper Perl Artistic & GPL https://metacpan.org/pod/CBOR::PP
CBOR::XS Marc Lehmann Perl GPL-3 https://metacpan.org/pod/CBOR::XS
cbor-ruby Sadayuki Furuhashi

Carsten Bormann

Ruby APL 2.0 https://github.com/cabo/cbor-ruby
libcbor-ruby Pavel Kalvoda Ruby MIT https://github.com/PJK/libcbor-ruby Binding to libcbor.
cbor-erlang Jihyun Yu Erlang BSD-3-clause https://github.com/yjh0502/cbor-erlang
excbor Carsten Bormann Elixir not specified,

ask the author

https://github.com/cabo/excbor
CBOR R. Kyle Murphy Haskell LGPL-3 https://github.com/orclev/CBOR
borc Joe Hildebrand

Friedel Ziegelmayer

JavaScript MIT https://github.com/dignifiedquire/borc Fork of node-cbor.
borc-refs Joe Hildebrand

Friedel Ziegelmayer

Sandro Hawke

JavaScript MIT https://github.com/sandhawke/borc-refs Fork of borc.
CBOR Peter Occil C# Public domain software https://github.com/peteroupc/CBOR Also handles JSON.
Dahomey.Cbor Michaël Catanzariti C# MIT License https://github.com/dahomey-technologies/Dahomey.Cbor
Jackson Tatu Saloranta Java APL-2.0 https://github.com/FasterXML/jackson-dataformats-binary/tree/master/cbor Also handles other formats.
cbor-java Constantin Rack Java APL-2.0 https://github.com/c-rack/cbor-java
jacob J.W. Janssen Java APL-2.0 https://github.com/jawi/jacob
kotlinx.serialization JetBrains Kotlin APL-2.0 https://github.com/Kotlin/kotlinx.serialization Supports cross-platform
cn-cbor Joe Hildebrand

Carsten Bormann

C MIT https://github.com/cabo/cn-cbor
cbor-cpp Stanislav Ovsyannikov C++ APL-2.0 https://github.com/naphaso/cbor-cpp
cppbor David Preece C++ BSD https://github.com/rantydave/cppbor Uses C++17 variants.
libcbor Pavel Kalvoda C MIT https://github.com/PJK/libcbor
tinycbor Intel C MIT https://github.com/01org/tinycbor
NanoCBOR Koen Zandberg C LGPL https://github.com/bergzand/NanoCBOR Used by RIOT-OS
cbor-d Andrey Penechko D Boost 1.0 https://github.com/MrSmith33/cbor-d
clj-cbor Greg Look Clojure Unlicense https://github.com/greglook/clj-cbor
JSON for Modern C++ Niels Lohmann C++ MIT https://github.com/nlohmann/json Also handles JSON and MsgPack.
borabora Christoph Engelbert Java APL-2.0 https://github.com/noctarius/borabora
lua-ConciseSerialization François Perrad Lua MIT https://web.archive.org/web/20170322112326/https://fperrad.github.io/lua-ConciseSerialization/
flunn Fritz Conrad Grimpen

Sokolov Yura

Python MIT https://pypi.python.org/pypi/flunn
cbor-qt Anton Dutov C++ Public domain https://github.com/anton-dutov/cbor-qt
QCborValue Qt Project C++ LGPL https://doc.qt.io/qt-5/qcborvalue.html Part of the Qt framework since version 5.12
cbor11 Jakob Varmose Bentzen C++ Public domain https://github.com/jakobvarmose/cbor11
cborcpp Alex Nekipelov C++ MIT https://github.com/nekipelov/cborcpp
GoldFish Vincent Lascaux C++ MIT https://github.com/OneNoteDev/GoldFish
Library-Arduino-Cbor Juanjo Tara C++ APL-2.0 https://github.com/jjtara/Library-Arduino-Cbor
cborg Duncan Coutts Haskell BSD-3-clause https://github.com/well-typed/cborg
cbor Steve Hamblett Dart MIT https://github.com/shamblett/cbor
borer Mathias Doenitz Scala MPL 2.0 https://github.com/sirthias/borer Also handles JSON.
nim_cbor Emery Hemingway Nim MIT https://git.sr.ht/~ehmry/nim_cbor
ciborium Nathaniel McCallum

Mark Bestavros

Enarx Team

Rust Apache 2.0 https://github.com/enarx/ciborium

See also

  • Comparison of binary data serialization formats

References

This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.