| Internet-Draft | CBOR CIE | July 2024 |
| Lundblade | Expires 24 January 2025 | [Page] |
CBOR allows variable serialization to accommodate varying use cases in constrained environments, but leaves it without a default interoperable serialization. Here a base interoperability serialization is defined that should usable for a majority of CBOR based protocols.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 24 January 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Partial implementation of IETF protocols is quite common. For example, not all CWT implementations will implement all the defined claims. For another example, COSE use cases that don't need encryption won't implement it. In these, it is clear by use case what parts to implement and why.¶
The issue with CBOR serialization is that there are multiple non-interoperable serializations for exactly the same thing. For example, there are multiple ways to encode an integer, a string, an array or a map.¶
Because CBOR is targeted at constrained environments, it is common to minimize what is implemented. It can't be assumed that a decoder will implement every serialization varient for the data types it chooses to support. In particular, indefinite-length strings are less likely to be supported universally. They are the only thing where data can't be take directly out of the encoded message. Because of this they usually require dynamic memory allocation where usually nothing else does.¶
This draft establishes a single way to serialize the data types defined in [RFC8949] that will work well for a large number of CBOR protocols. CBOR protocols can still of course choose from any of serialization variants in [RFC8949] should it be necessary for their use case. The purpose of this draft is to provide an easy clear choice when there is not any special serialization need.¶
This is nearly the same as preferred serialization from [RFC8949].¶
The principle difference is that this unconditionally requires definite length encoding and prohibits indefinite length encoding. Preferred serialization only makes conditional recommendation for the use of definite-length encoding.¶
Another difference is that this establishes the serialization requirements as a standard using normative language. While this is intended to be as close to and consistent with preferred serialization as possible, this document is the authoritative description of CBOR Interoperable Encoding.¶
CIE is essentially the same as CDE without the map sorting requirement. While CDE has all the characteristics necessary to provide gauranteed interoperability, map sorting can be burdensome to implement in some constrained environments.¶
Shortest-form encoding of the argument MUST be used for all major types. Major type 7 is used for floating-point and simple values; floating point values have its specific rules for how the shortest form is derived for the argument. The shortest form encoding for any argument that is not a floating point value is:¶
0 to 23 and -1 to -24 MUST be encoded in the same byte as the major type.¶
24 to 255 and -25 to -256 MUST be encoded only with an additional byte (ai = 0x18).¶
256 to 65535 and -257 to -65536 MUST be encoded only with an additional two bytes (ai = 0x19).¶
65536 to 4294967295 and -65537 to -4294967296 MUST be encoded only with an additional four bytes (ai = 0x1a).¶
If maps or arrays are emitted, they MUST use definite-length encoding (never indefinite-length).¶
If text or byte strings are emitted, they MUST use definite-length encoding (never indefinite-length).¶
If floating-point numbers are emitted, the following apply:¶
The length of the argument indicates half (binary16, ai = 0x19), single (binary32, ai = 0x1a) and double (binary64, ai = 0x1b) precision encoding. If multiple of these encodings preserve the precision of the value to be encoded, only the shortest form of these MUST be emitted. That is, encoders MUST support half-precision and single-precision floating point. Positive and negative infinity and zero MUST be represented in half-precision floating point.¶
NaNs, and thus NaN payloads MUST be supported.¶
As with all floating point numbers, NaNs with payloads MUST be reduced to the shortest of double, single or half precision that preserves the NaN payload. The reduction is performed by removing the rightmost N bits of the payload, where N is the difference in the number of bits in the significand (mantissa) between the original format and the reduced format. The reduction is performed only (preserves the value only) if all the rightmost bits removed are zero.¶
If big numbers (tags 2 and 3) are supported, the following apply:¶
If big floats or decimal fractions with a big number mantissa are supported, the big number serialization must conform to the above requirements for big numbers.¶
Decoders MUST accept shortest-form encoded arguments.¶
If arrays or maps are supported, definite-length arrays or maps MUST be accepted.¶
If text or byte strings are supported, definite-length text or byte strings MUST be accepted.¶
If floating-point numbers are supported, the following apply:¶
Half-precision values MUST be accepted.¶
Double- and single-precision values SHOULD be accepted; leaving these out is only foreseen for decoders that need to work in exceptionally constrained environments.¶
If double-precision values are accepted, single-precision values MUST be accepted.¶
NaNs, and thus NaN payloads, MUST be accepted.¶
If big numbers (tags 2 and 3) are supported, type 0 and type 1 integers MUST be accepted in place of a byte string big number. Leading zeros in a big number byte string must be ignored.¶
If big floats or decimal fractions with a big number mantissa are supported, type 0 and type 1 integers must be accepted for the big number mantissa.¶