Concise Binary Object Representation (CBOR)
obsoleted by
- rfc-8949 — Concise Binary Object Representation (CBOR)
Extracted elements (26)
CBOR allows multiple encodings of the same value (e.g., the integer 7 can be represented in several ways) because requiring unique encodings would add encoder complexity. Protocols requiring determinism are expected to layer canonical-form rules on top.
CBOR's data model extends JSON's but is a separate encoding rather than an extension of RFC 4627 grammar, deliberately avoiding backwards incompatibility with deployed JSON documents. The design adds binary byte strings and tags to JSON's core types.
Decoders are not required to understand tags; a decoder may skip the tag initial bytes and interpret the tagged data item directly, enabling forward compatibility without requiring decoder updates when new tags are registered.
The additional information codepoint space (values 28–30) is intentionally not managed by an IANA registry; allocations require updating this specification. Values 28 and 29 are provisionally reserved for 128-bit and 256-bit quantities, and value 30 is the only one available for general allocation.
JavaScript environments treat all numbers as floating point, which may silently lose precision for integers exceeding 53 significant bits. CBOR-based protocols targeting JavaScript environments should define their expectations for handling large integers.
When converting CBOR maps to JSON objects, only UTF-8 string keys map directly; converting other key types (e.g., integers) to strings risks key collisions. CBOR bytes strings without an encoding hint are base64url-encoded (no padding) when converted to JSON strings.
All multi-byte values are encoded in network byte order (most significant byte first, big-endian).
Decoders that understand bignum tags (2 and 3) MUST be able to decode bignums that have leading zeroes.
The exponent e in a decimal fraction or bigfloat MUST be represented as an integer of major type 0 or 1.
Within an indefinite-length byte string, every chunk between the indefinite-length indicator and the 'break' MUST be a definite-length byte string item; encountering any other item type is a parse error. Likewise, all chunks of indefinite-length text strings MUST be definite-length text strings, and a single UTF-8 character cannot be split across chunks.
A decimal fraction (tag 4) or bigfloat (tag 5) is a two-element array [exponent e, mantissa m]. Decimal fractions compute m*(10**e); bigfloats compute m*(2**e). The exponent MUST be major type 0 or 1; the mantissa may be a bignum.
Arrays (major type 4) and maps (major type 5) with additional information 31 are indefinite-length: items follow without a count and are terminated by the 'break' stop code (0xFF). A 'break' only closes the immediately enclosing indefinite-length item; nested indefinite items require matching 'break' codes.
Canonical CBOR requires: integers and lengths use the shortest possible encoding; map keys are sorted by length (shorter first), then by byte-wise lexical value for equal-length keys; indefinite-length items are forbidden. These rules ensure two encoders producing the same input yield identical output.
Strict mode requires a decoder to reject: maps with duplicate keys, tags applied to an incorrect data item type, and data items incorrectly formatted for their type (e.g., invalid UTF-8). On encountering an unknown tag or simple value, a strict decoder may either error or pass the unknown item to the application with an 'unrecognized' indication.
Tag 55799 (serialized as 0xd9d9f7) is the self-describe CBOR tag. It imparts no additional semantics but serves as a magic number to identify CBOR data when out-of-band context is unavailable; the byte sequence does not appear at the start of any valid Unicode text.
Tags (major type 6) precede a single data item and carry an integer tag number encoded as a positive integer. Tag 0 is an RFC 3339 date/time string, tag 1 is epoch-based numeric time, tags 2/3 are positive/negative bignums (byte strings in network byte order), tags 4/5 are decimal fraction and bigfloat, and tag 55799 is self-describe CBOR.
IANA 'Concise Binary Object Representation (CBOR) Simple Values' registry. Values 0–19 assigned by Standards Action (suggested to start at 16); values 32–255 by Specification Required. Initial allocations: 20=false, 21=true, 22=null, 23=undefined.
IANA 'Concise Binary Object Representation (CBOR) Tags' registry. Values 0–23 by Standards Action; 24–255 by Specification Required; 256–18446744073709551615 by First Come First Served. Initial allocations include tags 0–5 (date/time, bignums, decimal/bigfloat), 21–24 (encoding hints), 32–36 (encoded text types), and 55799 (self-describe CBOR).
IANA media type 'application/cbor' registered with file extension .cbor and CoAP Content-Format ID 60. The '+cbor' structured syntax suffix is also registered, allowing media types of the form 'xxx/yyy+cbor'.
In-place JSON-to-CBOR encoding in a single buffer is risky: strings with few escapes longer than 255 bytes may expand during CBOR encoding, and some short decimal floating-point values (1.1, 1e9) may expand in binary form, creating vulnerabilities exploitable by an attacker supplying crafted JSON.
Resource exhaustion attacks may induce a decoder to allocate very large strings, arrays, or maps, or exhaust stack depth via deeply nested items. Decoders must apply appropriate resource management; very large declared sizes may also probe for integer overflow vulnerabilities.
When a gatekeeper and an application independently decode the same CBOR item, an attacker can exploit duplicate map keys or number precision differences to cause the two decoders to reach different interpretations, bypassing the gatekeeper's security check. Firewalls and security systems decoding CBOR should only operate in strict mode.
CBOR defines eight major types: 0 (unsigned integer), 1 (negative integer), 2 (byte string), 3 (UTF-8 text string), 4 (array), 5 (map), 6 (tag), and 7 (floating-point/simple/break). The major type occupies the top 3 bits of the initial byte.
Every CBOR data item begins with an initial byte encoding the major type in the high-order 3 bits and additional information in the low-order 5 bits. Additional information 0–23 is a direct small unsigned integer; 24–27 indicate 1-, 2-, 4-, or 8-byte unsigned integers follow; 31 signals indefinite length; 28–30 are reserved.
Major type 7 encodes simple values (false=20, true=21, null=22, undefined=23), extended simple values in a following byte (values 32–255), and IEEE 754 floating-point in 16 bits (additional info 25), 32 bits (26), or 64 bits (27). The 'break' stop code is 0b111_11111 (0xFF).
Negative integers (major type 1) encode the value -1 minus the encoded unsigned integer, so -500 is encoded the same way as 499 but with major type 1. All multi-byte integer values are in network byte order (big-endian).