--- 1/draft-ietf-cbor-7049bis-11.txt 2019-12-18 08:14:44.074037161 -0800 +++ 2/draft-ietf-cbor-7049bis-12.txt 2019-12-18 08:14:44.222040935 -0800 @@ -1,19 +1,19 @@ Network Working Group C. Bormann Internet-Draft Universitaet Bremen TZI Obsoletes: 7049 (if approved) P. Hoffman Intended status: Standards Track ICANN -Expires: June 20, 2020 December 18, 2019 +Expires: 20 June 2020 18 December 2019 Concise Binary Object Representation (CBOR) - draft-ietf-cbor-7049bis-11 + draft-ietf-cbor-7049bis-12 Abstract The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document is a revised edition of RFC 7049, with editorial @@ -42,114 +42,113 @@ 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 June 20, 2020. + This Internet-Draft will expire on 20 June 2020. Copyright Notice Copyright (c) 2019 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 Simplified BSD License text as described in Section 4.e of - the Trust Legal Provisions and are provided without warranty as - described in the Simplified BSD License. + 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 Simplified BSD License text + as described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 2. CBOR Data Models . . . . . . . . . . . . . . . . . . . . . . 7 2.1. Extended Generic Data Models . . . . . . . . . . . . . . 8 2.2. Specific Data Models . . . . . . . . . . . . . . . . . . 9 3. Specification of the CBOR Encoding . . . . . . . . . . . . . 9 3.1. Major Types . . . . . . . . . . . . . . . . . . . . . . . 11 3.2. Indefinite Lengths for Some Major Types . . . . . . . . . 13 3.2.1. The "break" Stop Code . . . . . . . . . . . . . . . . 13 3.2.2. Indefinite-Length Arrays and Maps . . . . . . . . . . 14 3.2.3. Indefinite-Length Byte Strings and Text Strings . . . 16 3.3. Floating-Point Numbers and Values with No Content . . . . 16 3.4. Tagging of Items . . . . . . . . . . . . . . . . . . . . 18 - 3.4.1. Standard Date/Time String . . . . . . . . . . . . . . 21 - 3.4.2. Epoch-based Date/Time . . . . . . . . . . . . . . . . 21 - 3.4.3. Bignums . . . . . . . . . . . . . . . . . . . . . . . 22 + 3.4.1. Standard Date/Time String . . . . . . . . . . . . . . 20 + 3.4.2. Epoch-based Date/Time . . . . . . . . . . . . . . . . 20 + 3.4.3. Bignums . . . . . . . . . . . . . . . . . . . . . . . 21 3.4.4. Decimal Fractions and Bigfloats . . . . . . . . . . . 22 - 3.4.5. Content Hints . . . . . . . . . . . . . . . . . . . . 24 - 3.4.5.1. Encoded CBOR Data Item . . . . . . . . . . . . . 24 + 3.4.5. Content Hints . . . . . . . . . . . . . . . . . . . . 23 + 3.4.5.1. Encoded CBOR Data Item . . . . . . . . . . . . . 23 3.4.5.2. Expected Later Encoding for CBOR-to-JSON - Converters . . . . . . . . . . . . . . . . . . . 24 - 3.4.5.3. Encoded Text . . . . . . . . . . . . . . . . . . 25 - 3.4.6. Self-Described CBOR . . . . . . . . . . . . . . . . . 26 + Converters . . . . . . . . . . . . . . . . . . . . 24 + 3.4.5.3. Encoded Text . . . . . . . . . . . . . . . . . . 24 + 3.4.6. Self-Described CBOR . . . . . . . . . . . . . . . . . 25 4. Serialization Considerations . . . . . . . . . . . . . . . . 26 4.1. Preferred Serialization . . . . . . . . . . . . . . . . . 26 4.2. Deterministically Encoded CBOR . . . . . . . . . . . . . 27 - 4.2.1. Core Deterministic Encoding Requirements . . . . . . 28 - 4.2.2. Additional Deterministic Encoding Considerations . . 29 + 4.2.1. Core Deterministic Encoding Requirements . . . . . . 27 + 4.2.2. Additional Deterministic Encoding Considerations . . 28 4.2.3. Length-first map key ordering . . . . . . . . . . . . 30 5. Creating CBOR-Based Protocols . . . . . . . . . . . . . . . . 31 - 5.1. CBOR in Streaming Applications . . . . . . . . . . . . . 32 + 5.1. CBOR in Streaming Applications . . . . . . . . . . . . . 31 5.2. Generic Encoders and Decoders . . . . . . . . . . . . . . 32 - 5.3. Validity of Items . . . . . . . . . . . . . . . . . . . . 33 + 5.3. Validity of Items . . . . . . . . . . . . . . . . . . . . 32 5.3.1. Basic validity . . . . . . . . . . . . . . . . . . . 33 - 5.3.2. Tag validity . . . . . . . . . . . . . . . . . . . . 34 + 5.3.2. Tag validity . . . . . . . . . . . . . . . . . . . . 33 5.4. Validity and Evolution . . . . . . . . . . . . . . . . . 34 5.5. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 35 - 5.6. Specifying Keys for Maps . . . . . . . . . . . . . . . . 36 - 5.6.1. Equivalence of Keys . . . . . . . . . . . . . . . . . 37 - 5.7. Undefined Values . . . . . . . . . . . . . . . . . . . . 38 + 5.6. Specifying Keys for Maps . . . . . . . . . . . . . . . . 35 + 5.6.1. Equivalence of Keys . . . . . . . . . . . . . . . . . 36 + 5.7. Undefined Values . . . . . . . . . . . . . . . . . . . . 37 6. Converting Data between CBOR and JSON . . . . . . . . . . . . 38 6.1. Converting from CBOR to JSON . . . . . . . . . . . . . . 38 6.2. Converting from JSON to CBOR . . . . . . . . . . . . . . 39 - 7. Future Evolution of CBOR . . . . . . . . . . . . . . . . . . 41 + 7. Future Evolution of CBOR . . . . . . . . . . . . . . . . . . 40 7.1. Extension Points . . . . . . . . . . . . . . . . . . . . 41 - 7.2. Curating the Additional Information Space . . . . . . . . 42 + 7.2. Curating the Additional Information Space . . . . . . . . 41 8. Diagnostic Notation . . . . . . . . . . . . . . . . . . . . . 42 8.1. Encoding Indicators . . . . . . . . . . . . . . . . . . . 43 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 9.1. Simple Values Registry . . . . . . . . . . . . . . . . . 44 9.2. Tags Registry . . . . . . . . . . . . . . . . . . . . . . 44 9.3. Media Type ("MIME Type") . . . . . . . . . . . . . . . . 45 - 9.4. CoAP Content-Format . . . . . . . . . . . . . . . . . . . 46 + 9.4. CoAP Content-Format . . . . . . . . . . . . . . . . . . . 45 9.5. The +cbor Structured Syntax Suffix Registration . . . . . 46 10. Security Considerations . . . . . . . . . . . . . . . . . . . 47 - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 - 11.1. Normative References . . . . . . . . . . . . . . . . . . 49 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 + 11.1. Normative References . . . . . . . . . . . . . . . . . . 48 11.2. Informative References . . . . . . . . . . . . . . . . . 50 - Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 53 - Appendix B. Jump Table . . . . . . . . . . . . . . . . . . . . . 57 - Appendix C. Pseudocode . . . . . . . . . . . . . . . . . . . . . 60 - Appendix D. Half-Precision . . . . . . . . . . . . . . . . . . . 62 + Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 51 + Appendix B. Jump Table . . . . . . . . . . . . . . . . . . . . . 55 + Appendix C. Pseudocode . . . . . . . . . . . . . . . . . . . . . 58 + Appendix D. Half-Precision . . . . . . . . . . . . . . . . . . . 61 Appendix E. Comparison of Other Binary Formats to CBOR's Design - Objectives . . . . . . . . . . . . . . . . . . . . . 63 - E.1. ASN.1 DER, BER, and PER . . . . . . . . . . . . . . . . . 64 - E.2. MessagePack . . . . . . . . . . . . . . . . . . . . . . . 64 - E.3. BSON . . . . . . . . . . . . . . . . . . . . . . . . . . 65 - E.4. MSDTP: RFC 713 . . . . . . . . . . . . . . . . . . . . . 65 - E.5. Conciseness on the Wire . . . . . . . . . . . . . . . . . 65 - Appendix F. Changes from RFC 7049 . . . . . . . . . . . . . . . 66 - Appendix G. Well-formedness errors and examples . . . . . . . . 66 - G.1. Examples for CBOR data items that are not well-formed . . 67 - Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 69 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 70 + Objectives . . . . . . . . . . . . . . . . . . . . . . . 62 + E.1. ASN.1 DER, BER, and PER . . . . . . . . . . . . . . . . . 63 + E.2. MessagePack . . . . . . . . . . . . . . . . . . . . . . . 63 + E.3. BSON . . . . . . . . . . . . . . . . . . . . . . . . . . 64 + E.4. MSDTP: RFC 713 . . . . . . . . . . . . . . . . . . . . . 64 + E.5. Conciseness on the Wire . . . . . . . . . . . . . . . . . 64 + Appendix F. Changes from RFC 7049 . . . . . . . . . . . . . . . 65 + Appendix G. Well-formedness errors and examples . . . . . . . . 65 + G.1. Examples for CBOR data items that are not well-formed . . 66 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 68 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 69 1. Introduction There are hundreds of standardized formats for binary representation of structured data (also known as binary serialization formats). Of those, some are for specific domains of information, while others are generalized for arbitrary data. In the IETF, probably the best-known formats in the latter category are ASN.1's BER and DER [ASN.1]. The format defined here follows some specific design goals that are @@ -172,83 +171,83 @@ of the format. 1.1. Objectives The objectives of CBOR, roughly in decreasing order of importance, are: 1. The representation must be able to unambiguously encode most common data formats used in Internet standards. - - It must represent a reasonable set of basic data types and + * It must represent a reasonable set of basic data types and structures using binary encoding. "Reasonable" here is largely influenced by the capabilities of JSON, with the major addition of binary byte strings. The structures supported are limited to arrays and trees; loops and lattice-style graphs are not supported. - - There is no requirement that all data formats be uniquely + * There is no requirement that all data formats be uniquely encoded; that is, it is acceptable that the number "7" might be encoded in multiple different ways. 2. The code for an encoder or decoder must be able to be compact in order to support systems with very limited memory, processor power, and instruction sets. - - An encoder and a decoder need to be implementable in a very + * An encoder and a decoder need to be implementable in a very small amount of code (for example, in class 1 constrained nodes as defined in [RFC7228]). - - The format should use contemporary machine representations of + * The format should use contemporary machine representations of data (for example, not requiring binary-to-decimal conversion). 3. Data must be able to be decoded without a schema description. - - Similar to JSON, encoded data should be self-describing so + * Similar to JSON, encoded data should be self-describing so that a generic decoder can be written. 4. The serialization must be reasonably compact, but data compactness is secondary to code compactness for the encoder and decoder. - - "Reasonable" here is bounded by JSON as an upper bound in + * "Reasonable" here is bounded by JSON as an upper bound in size, and by implementation complexity maintaining a lower bound. Using either general compression schemes or extensive bit-fiddling violates the complexity goals. 5. The format must be applicable to both constrained nodes and high- volume applications. - - This means it must be reasonably frugal in CPU usage for both + * This means it must be reasonably frugal in CPU usage for both encoding and decoding. This is relevant both for constrained nodes and for potential usage in applications with a very high volume of data. 6. The format must support all JSON data types for conversion to and from JSON. - - It must support a reasonable level of conversion as long as + * It must support a reasonable level of conversion as long as the data represented is within the capabilities of JSON. It must be possible to define a unidirectional mapping towards JSON for all types of data. 7. The format must be extensible, and the extended data must be decodable by earlier decoders. - - The format is designed for decades of use. + * The format is designed for decades of use. - - The format must support a form of extensibility that allows + * The format must support a form of extensibility that allows fallback so that a decoder that does not understand an extension can still decode the message. - - The format must be able to be extended in the future by later + * The format must be able to be extended in the future by later IETF standards. 1.2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. @@ -556,39 +555,40 @@ In major types 6 and 7, many of the possible values are reserved for future specification. See Section 9 for more information on these values. Table 1 summarizes the major types defined by CBOR, ignoring the next section for now. The number N in this table stands for the argument, mt for the major type. +----+-----------------------+---------------------------------+ | mt | Meaning | Content | - +----+-----------------------+---------------------------------+ + +====+=======================+=================================+ | 0 | unsigned integer N | - | - | | | | + +----+-----------------------+---------------------------------+ | 1 | negative integer -1-N | - | - | | | | + +----+-----------------------+---------------------------------+ | 2 | byte string | N bytes | - | | | | + +----+-----------------------+---------------------------------+ | 3 | text string | N bytes (UTF-8 text) | - | | | | + +----+-----------------------+---------------------------------+ | 4 | array | N data items (elements) | - | | | | + +----+-----------------------+---------------------------------+ | 5 | map | 2N data items (key/value pairs) | - | | | | + +----+-----------------------+---------------------------------+ | 6 | tag of number N | 1 data item | - | | | | + +----+-----------------------+---------------------------------+ | 7 | simple/float | - | +----+-----------------------+---------------------------------+ - Table 1: Overview over CBOR major types (definite length encoded) + Table 1: Overview over CBOR major types (definite length + encoded) 3.2. Indefinite Lengths for Some Major Types Four CBOR items (arrays, maps, byte strings, and text strings) can be encoded with an indefinite length using additional information value 31. This is useful if the encoding of the item needs to begin before the number of items inside the array or map, or the total length of the string, is known. (The application of this is often referred to as "streaming" within a data item.) @@ -738,65 +738,64 @@ 3.3. Floating-Point Numbers and Values with No Content Major type 7 is for two types of data: floating-point numbers and "simple values" that do not need any content. Each value of the 5-bit additional information in the initial byte has its own separate meaning, as defined in Table 2. Like the major types for integers, items of this major type do not carry content data; all the information is in the initial bytes. - +------------+------------------------------------------------------+ - | 5-Bit | Semantics | - | Value | | - +------------+------------------------------------------------------+ + +-------------+---------------------------------------------------+ + | 5-Bit Value | Semantics | + +=============+===================================================+ | 0..23 | Simple value (value 0..23) | - | | | + +-------------+---------------------------------------------------+ | 24 | Simple value (value 32..255 in following byte) | - | | | + +-------------+---------------------------------------------------+ | 25 | IEEE 754 Half-Precision Float (16 bits follow) | - | | | + +-------------+---------------------------------------------------+ | 26 | IEEE 754 Single-Precision Float (32 bits follow) | - | | | + +-------------+---------------------------------------------------+ | 27 | IEEE 754 Double-Precision Float (64 bits follow) | - | | | + +-------------+---------------------------------------------------+ | 28-30 | Reserved, not well-formed in the present document | - | | | + +-------------+---------------------------------------------------+ | 31 | "break" stop code for indefinite-length items | | | (Section 3.2.1) | - +------------+------------------------------------------------------+ + +-------------+---------------------------------------------------+ Table 2: Values for Additional Information in Major Type 7 As with all other major types, the 5-bit value 24 signifies a single- byte extension: it is followed by an additional byte to represent the simple value. (To minimize confusion, only the values 32 to 255 are used.) This maintains the structure of the initial bytes: as for the other major types, the length of these always depends on the additional information in the first byte. Table 3 lists the values assigned and available for simple types. +---------+-----------------+ | Value | Semantics | - +---------+-----------------+ + +=========+=================+ | 0..19 | (Unassigned) | - | | | + +---------+-----------------+ | 20 | False | - | | | + +---------+-----------------+ | 21 | True | - | | | + +---------+-----------------+ | 22 | Null | - | | | + +---------+-----------------+ | 23 | Undefined value | - | | | + +---------+-----------------+ | 24..31 | (Reserved) | - | | | + +---------+-----------------+ | 32..255 | (Unassigned) | +---------+-----------------+ Table 3: Simple Values An encoder MUST NOT issue two-byte sequences that start with 0xf8 (major type = 7, additional information = 24) and continue with a byte less than 0x20 (32 decimal). Such sequences are not well- formed. (This implies that an encoder cannot encode false, true, null, or undefined in two-byte sequences, only the one-byte variants @@ -846,68 +845,67 @@ of the tag (the enclosed data item) is the data item (the value) that is being tagged. IANA maintains a registry of tag numbers as described in Section 9.2. Table 4 provides a list of tag numbers that were defined in [RFC7049], with definitions in the rest of this section. Note that many other tag numbers have been defined since the publication of [RFC7049]; see the registry described at Section 9.2 for the complete list. - +----------+----------+---------------------------------------------+ - | Tag | Data | Semantics | - | Number | Item | | - +----------+----------+---------------------------------------------+ - | 0 | text | Standard date/time string; see | - | | string | Section 3.4.1 | - | | | | - | 1 | multiple | Epoch-based date/time; see Section 3.4.2 | - | | | | - | 2 | byte | Positive bignum; see Section 3.4.3 | - | | string | | - | | | | - | 3 | byte | Negative bignum; see Section 3.4.3 | - | | string | | - | | | | - | 4 | array | Decimal fraction; see Section 3.4.4 | - | | | | + +------------+-------------+----------------------------------+ + | Tag Number | Data Item | Semantics | + +============+=============+==================================+ + | 0 | text string | Standard date/time string; see | + | | | Section 3.4.1 | + +------------+-------------+----------------------------------+ + | 1 | multiple | Epoch-based date/time; see | + | | | Section 3.4.2 | + +------------+-------------+----------------------------------+ + | 2 | byte string | Positive bignum; see | + | | | Section 3.4.3 | + +------------+-------------+----------------------------------+ + | 3 | byte string | Negative bignum; see | + | | | Section 3.4.3 | + +------------+-------------+----------------------------------+ + | 4 | array | Decimal fraction; see | + | | | Section 3.4.4 | + +------------+-------------+----------------------------------+ | 5 | array | Bigfloat; see Section 3.4.4 | - | | | | - | 21 | multiple | Expected conversion to base64url encoding; | - | | | see Section 3.4.5.2 | - | | | | - | 22 | multiple | Expected conversion to base64 encoding; see | - | | | Section 3.4.5.2 | - | | | | - | 23 | multiple | Expected conversion to base16 encoding; see | - | | | Section 3.4.5.2 | - | | | | - | 24 | byte | Encoded CBOR data item; see Section 3.4.5.1 | - | | string | | - | | | | - | 32 | text | URI; see Section 3.4.5.3 | - | | string | | - | | | | - | 33 | text | base64url; see Section 3.4.5.3 | - | | string | | - | | | | - | 34 | text | base64; see Section 3.4.5.3 | - | | string | | - | | | | - | 35 | text | Regular expression; see Section 3.4.5.3 | - | | string | | - | | | | - | 36 | text | MIME message; see Section 3.4.5.3 | - | | string | | - | | | | - | 55799 | multiple | Self-described CBOR; see Section 3.4.6 | - +----------+----------+---------------------------------------------+ + +------------+-------------+----------------------------------+ + | 21 | multiple | Expected conversion to base64url | + | | | encoding; see Section 3.4.5.2 | + +------------+-------------+----------------------------------+ + | 22 | multiple | Expected conversion to base64 | + | | | encoding; see Section 3.4.5.2 | + +------------+-------------+----------------------------------+ + | 23 | multiple | Expected conversion to base16 | + | | | encoding; see Section 3.4.5.2 | + +------------+-------------+----------------------------------+ + | 24 | byte string | Encoded CBOR data item; see | + | | | Section 3.4.5.1 | + +------------+-------------+----------------------------------+ + | 32 | text string | URI; see Section 3.4.5.3 | + +------------+-------------+----------------------------------+ + | 33 | text string | base64url; see Section 3.4.5.3 | + +------------+-------------+----------------------------------+ + | 34 | text string | base64; see Section 3.4.5.3 | + +------------+-------------+----------------------------------+ + | 35 | text string | Regular expression; see | + | | | Section 3.4.5.3 | + +------------+-------------+----------------------------------+ + | 36 | text string | MIME message; see | + | | | Section 3.4.5.3 | + +------------+-------------+----------------------------------+ + | 55799 | multiple | Self-described CBOR; see | + | | | Section 3.4.6 | + +------------+-------------+----------------------------------+ Table 4: Tag numbers defined in RFC 7049 Conceptually, tags are interpreted in the generic data model, not at (de-)serialization time. A small number of tags (specifically, tag number 25 and tag number 29) have been registered with semantics that may require processing at (de-)serialization time: The decoder needs to be aware and the encoder needs to be in control of the exact sequence in which data items are encoded into the CBOR data stream. This means these tags cannot be implemented on top of every generic @@ -2302,40 +2300,41 @@ [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [TIME_T] The Open Group Base Specifications, "Vol. 1: Base - Definitions, Issue 7", Section 4.15 'Seconds Since the - Epoch', IEEE Std 1003.1, 2013 Edition, 2013, + Definitions, Issue 7", 2013 Edition, IEEE Std 1003.1, + Section 4.15 'Seconds Since the Epoch', 2013, . 11.2. Informative References [ASN.1] International Telecommunication Union, "Information Technology -- ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, 1994. [BSON] Various, "BSON - Binary JSON", 2013, . [I-D.ietf-cbor-sequence] Bormann, C., "Concise Binary Object Representation (CBOR) - Sequences", draft-ietf-cbor-sequence-02 (work in - progress), September 2019. + Sequences", Work in Progress, Internet-Draft, draft-ietf- + cbor-sequence-02, 25 September 2019, . [IANA.cbor-simple-values] IANA, "Concise Binary Object Representation (CBOR) Simple Values", . [IANA.cbor-tags] IANA, "Concise Binary Object Representation (CBOR) Tags", . @@ -2371,24 +2370,25 @@ Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC8618] Dickinson, J., Hague, J., Dickinson, S., Manderson, T., and J. Bond, "Compacted-DNS (C-DNS): A Format for DNS Packet Capture", RFC 8618, DOI 10.17487/RFC8618, September 2019, . [SIPHASH] Aumasson, J. and D. Bernstein, "SipHash: A Fast Short- - Input PRF", Lecture Notes in Computer Science pp. 489-508, - DOI 10.1007/978-3-642-34931-7_28, 2012. + Input PRF", DOI 10.1007/978-3-642-34931-7_28, Lecture + Notes in Computer Science pp. 489-508, 2012, + . - [YAML] Ben-Kiki, O., Evans, C., and I. Net, "YAML Ain't Markup + [YAML] Ben-Kiki, O., Evans, C., and I.d. Net, "YAML Ain't Markup Language (YAML[TM]) Version 1.2", 3rd Edition, October 2009, . Appendix A. Examples The following table provides some CBOR-encoded values in hexadecimal (right column), together with diagnostic notation for these values (left column). Note that the string "\u00fc" is one form of diagnostic notation for a UTF-8 string containing the single Unicode character U+00FC, LATIN SMALL LETTER U WITH DIAERESIS (u umlaut). @@ -2399,350 +2399,352 @@ ATTIC FIFTY STATERS). (Note that all these single-character strings could also be represented in native UTF-8 in diagnostic notation, just not in an ASCII-only specification like the present one.) In the diagnostic notation provided for bignums, their intended numeric value is shown as a decimal number (such as 18446744073709551616) instead of showing a tagged byte string (such as 2(h'010000000000000000')). +------------------------------+------------------------------------+ | Diagnostic | Encoded | - +------------------------------+------------------------------------+ + +==============================+====================================+ | 0 | 0x00 | - | | | + +------------------------------+------------------------------------+ | 1 | 0x01 | - | | | + +------------------------------+------------------------------------+ | 10 | 0x0a | - | | | + +------------------------------+------------------------------------+ | 23 | 0x17 | - | | | + +------------------------------+------------------------------------+ | 24 | 0x1818 | - | | | + +------------------------------+------------------------------------+ | 25 | 0x1819 | - | | | + +------------------------------+------------------------------------+ | 100 | 0x1864 | - | | | + +------------------------------+------------------------------------+ | 1000 | 0x1903e8 | - | | | + +------------------------------+------------------------------------+ | 1000000 | 0x1a000f4240 | - | | | + +------------------------------+------------------------------------+ | 1000000000000 | 0x1b000000e8d4a51000 | - | | | + +------------------------------+------------------------------------+ | 18446744073709551615 | 0x1bffffffffffffffff | - | | | + +------------------------------+------------------------------------+ | 18446744073709551616 | 0xc249010000000000000000 | - | | | + +------------------------------+------------------------------------+ | -18446744073709551616 | 0x3bffffffffffffffff | - | | | + +------------------------------+------------------------------------+ | -18446744073709551617 | 0xc349010000000000000000 | - | | | + +------------------------------+------------------------------------+ | -1 | 0x20 | - | | | + +------------------------------+------------------------------------+ | -10 | 0x29 | - | | | + +------------------------------+------------------------------------+ | -100 | 0x3863 | - | | | + +------------------------------+------------------------------------+ | -1000 | 0x3903e7 | - | | | + +------------------------------+------------------------------------+ | 0.0 | 0xf90000 | - | | | + +------------------------------+------------------------------------+ | -0.0 | 0xf98000 | - | | | + +------------------------------+------------------------------------+ | 1.0 | 0xf93c00 | - | | | + +------------------------------+------------------------------------+ | 1.1 | 0xfb3ff199999999999a | - | | | + +------------------------------+------------------------------------+ | 1.5 | 0xf93e00 | - | | | + +------------------------------+------------------------------------+ | 65504.0 | 0xf97bff | - | | | + +------------------------------+------------------------------------+ | 100000.0 | 0xfa47c35000 | - | | | + +------------------------------+------------------------------------+ | 3.4028234663852886e+38 | 0xfa7f7fffff | - | | | + +------------------------------+------------------------------------+ | 1.0e+300 | 0xfb7e37e43c8800759c | - | | | + +------------------------------+------------------------------------+ | 5.960464477539063e-8 | 0xf90001 | - | | | + +------------------------------+------------------------------------+ | 0.00006103515625 | 0xf90400 | - | | | + +------------------------------+------------------------------------+ | -4.0 | 0xf9c400 | - | | | + +------------------------------+------------------------------------+ | -4.1 | 0xfbc010666666666666 | - | | | + +------------------------------+------------------------------------+ | Infinity | 0xf97c00 | - | | | + +------------------------------+------------------------------------+ | NaN | 0xf97e00 | - | | | + +------------------------------+------------------------------------+ | -Infinity | 0xf9fc00 | - | | | + +------------------------------+------------------------------------+ | Infinity | 0xfa7f800000 | - | | | + +------------------------------+------------------------------------+ | NaN | 0xfa7fc00000 | - | | | + +------------------------------+------------------------------------+ | -Infinity | 0xfaff800000 | - | | | + +------------------------------+------------------------------------+ | Infinity | 0xfb7ff0000000000000 | - | | | + +------------------------------+------------------------------------+ | NaN | 0xfb7ff8000000000000 | - | | | + +------------------------------+------------------------------------+ | -Infinity | 0xfbfff0000000000000 | - | | | + +------------------------------+------------------------------------+ | false | 0xf4 | - | | | + +------------------------------+------------------------------------+ | true | 0xf5 | - | | | + +------------------------------+------------------------------------+ | null | 0xf6 | - | | | + +------------------------------+------------------------------------+ | undefined | 0xf7 | - | | | + +------------------------------+------------------------------------+ | simple(16) | 0xf0 | - | | | + +------------------------------+------------------------------------+ | simple(255) | 0xf8ff | - | | | + +------------------------------+------------------------------------+ | 0("2013-03-21T20:04:00Z") | 0xc074323031332d30332d32315432303a | | | 30343a30305a | - | | | + +------------------------------+------------------------------------+ | 1(1363896240) | 0xc11a514b67b0 | - | | | + +------------------------------+------------------------------------+ | 1(1363896240.5) | 0xc1fb41d452d9ec200000 | - | | | + +------------------------------+------------------------------------+ | 23(h'01020304') | 0xd74401020304 | - | | | + +------------------------------+------------------------------------+ | 24(h'6449455446') | 0xd818456449455446 | - | | | + +------------------------------+------------------------------------+ | 32("http://www.example.com") | 0xd82076687474703a2f2f7777772e6578 | | | 616d706c652e636f6d | - | | | + +------------------------------+------------------------------------+ | h'' | 0x40 | - | | | + +------------------------------+------------------------------------+ | h'01020304' | 0x4401020304 | - | | | + +------------------------------+------------------------------------+ | "" | 0x60 | - | | | + +------------------------------+------------------------------------+ | "a" | 0x6161 | - | | | + +------------------------------+------------------------------------+ | "IETF" | 0x6449455446 | - | | | + +------------------------------+------------------------------------+ | "\"\\" | 0x62225c | - | | | + +------------------------------+------------------------------------+ | "\u00fc" | 0x62c3bc | - | | | + +------------------------------+------------------------------------+ | "\u6c34" | 0x63e6b0b4 | - | | | + +------------------------------+------------------------------------+ | "\ud800\udd51" | 0x64f0908591 | - | | | + +------------------------------+------------------------------------+ | [] | 0x80 | - | | | + +------------------------------+------------------------------------+ | [1, 2, 3] | 0x83010203 | - | | | + +------------------------------+------------------------------------+ | [1, [2, 3], [4, 5]] | 0x8301820203820405 | - | | | + +------------------------------+------------------------------------+ | [1, 2, 3, 4, 5, 6, 7, 8, 9, | 0x98190102030405060708090a0b0c0d0e | | 10, 11, 12, 13, 14, 15, 16, | 0f101112131415161718181819 | | 17, 18, 19, 20, 21, 22, 23, | | | 24, 25] | | - | | | + +------------------------------+------------------------------------+ | {} | 0xa0 | - | | | + +------------------------------+------------------------------------+ | {1: 2, 3: 4} | 0xa201020304 | - | | | + +------------------------------+------------------------------------+ | {"a": 1, "b": [2, 3]} | 0xa26161016162820203 | - | | | + +------------------------------+------------------------------------+ | ["a", {"b": "c"}] | 0x826161a161626163 | - | | | - | {"a": "A", "b": "B", "c": | 0xa5616161416162614261636143616461 | - | "C", "d": "D", "e": "E"} | 4461656145 | - | | | + +------------------------------+------------------------------------+ + |{"a": "A", "b": "B", "c": "C",| 0xa5616161416162614261636143616461 | + | "d": "D", "e": "E"} | 4461656145 | + +------------------------------+------------------------------------+ | (_ h'0102', h'030405') | 0x5f42010243030405ff | - | | | + +------------------------------+------------------------------------+ | (_ "strea", "ming") | 0x7f657374726561646d696e67ff | - | | | + +------------------------------+------------------------------------+ | [_ ] | 0x9fff | - | | | + +------------------------------+------------------------------------+ | [_ 1, [2, 3], [_ 4, 5]] | 0x9f018202039f0405ffff | - | | | + +------------------------------+------------------------------------+ | [_ 1, [2, 3], [4, 5]] | 0x9f01820203820405ff | - | | | + +------------------------------+------------------------------------+ | [1, [2, 3], [_ 4, 5]] | 0x83018202039f0405ff | - | | | + +------------------------------+------------------------------------+ | [1, [_ 2, 3], [4, 5]] | 0x83019f0203ff820405 | - | | | - | [_ 1, 2, 3, 4, 5, 6, 7, 8, | 0x9f0102030405060708090a0b0c0d0e0f | - | 9, 10, 11, 12, 13, 14, 15, | 101112131415161718181819ff | - | 16, 17, 18, 19, 20, 21, 22, | | - | 23, 24, 25] | | - | | | + +------------------------------+------------------------------------+ + |[_ 1, 2, 3, 4, 5, 6, 7, 8, 9, | 0x9f0102030405060708090a0b0c0d0e0f | + | 10, 11, 12, 13, 14, 15, 16, | 101112131415161718181819ff | + | 17, 18, 19, 20, 21, 22, 23, | | + | 24, 25] | | + +------------------------------+------------------------------------+ | {_ "a": 1, "b": [_ 2, 3]} | 0xbf61610161629f0203ffff | - | | | + +------------------------------+------------------------------------+ | ["a", {_ "b": "c"}] | 0x826161bf61626163ff | - | | | + +------------------------------+------------------------------------+ | {_ "Fun": true, "Amt": -2} | 0xbf6346756ef563416d7421ff | +------------------------------+------------------------------------+ Table 5: Examples of Encoded CBOR Data Items Appendix B. Jump Table For brevity, this jump table does not show initial bytes that are reserved for future extension. It also only shows a selection of the initial bytes that can be used for optional features. (All unsigned integers are in network byte order.) - +------------+------------------------------------------------------+ + +------------+------------------------------------------------+ | Byte | Structure/Semantics | - +------------+------------------------------------------------------+ + +============+================================================+ | 0x00..0x17 | Unsigned integer 0x00..0x17 (0..23) | - | | | + +------------+------------------------------------------------+ | 0x18 | Unsigned integer (one-byte uint8_t follows) | - | | | + +------------+------------------------------------------------+ | 0x19 | Unsigned integer (two-byte uint16_t follows) | - | | | + +------------+------------------------------------------------+ | 0x1a | Unsigned integer (four-byte uint32_t follows) | - | | | + +------------+------------------------------------------------+ | 0x1b | Unsigned integer (eight-byte uint64_t follows) | - | | | + +------------+------------------------------------------------+ | 0x20..0x37 | Negative integer -1-0x00..-1-0x17 (-1..-24) | - | | | + +------------+------------------------------------------------+ | 0x38 | Negative integer -1-n (one-byte uint8_t for n | | | follows) | - | | | + +------------+------------------------------------------------+ | 0x39 | Negative integer -1-n (two-byte uint16_t for n | | | follows) | - | | | - | 0x3a | Negative integer -1-n (four-byte uint32_t for n | - | | follows) | - | | | - | 0x3b | Negative integer -1-n (eight-byte uint64_t for n | - | | follows) | - | | | + +------------+------------------------------------------------+ + | 0x3a | Negative integer -1-n (four-byte uint32_t for | + | | n follows) | + +------------+------------------------------------------------+ + | 0x3b | Negative integer -1-n (eight-byte uint64_t for | + | | n follows) | + +------------+------------------------------------------------+ | 0x40..0x57 | byte string (0x00..0x17 bytes follow) | - | | | - | 0x58 | byte string (one-byte uint8_t for n, and then n | - | | bytes follow) | - | | | - | 0x59 | byte string (two-byte uint16_t for n, and then n | - | | bytes follow) | - | | | - | 0x5a | byte string (four-byte uint32_t for n, and then n | - | | bytes follow) | - | | | - | 0x5b | byte string (eight-byte uint64_t for n, and then n | - | | bytes follow) | - | | | - | 0x5f | byte string, byte strings follow, terminated by | - | | "break" | - | | | + +------------+------------------------------------------------+ + | 0x58 | byte string (one-byte uint8_t for n, and then | + | | n bytes follow) | + +------------+------------------------------------------------+ + | 0x59 | byte string (two-byte uint16_t for n, and then | + | | n bytes follow) | + +------------+------------------------------------------------+ + | 0x5a | byte string (four-byte uint32_t for n, and | + | | then n bytes follow) | + +------------+------------------------------------------------+ + | 0x5b | byte string (eight-byte uint64_t for n, and | + | | then n bytes follow) | + +------------+------------------------------------------------+ + | 0x5f | byte string, byte strings follow, terminated | + | | by "break" | + +------------+------------------------------------------------+ | 0x60..0x77 | UTF-8 string (0x00..0x17 bytes follow) | - | | | - | 0x78 | UTF-8 string (one-byte uint8_t for n, and then n | - | | bytes follow) | - | | | - | 0x79 | UTF-8 string (two-byte uint16_t for n, and then n | - | | bytes follow) | - | | | - | 0x7a | UTF-8 string (four-byte uint32_t for n, and then n | - | | bytes follow) | - | | | - | 0x7b | UTF-8 string (eight-byte uint64_t for n, and then n | - | | bytes follow) | - | | | - | 0x7f | UTF-8 string, UTF-8 strings follow, terminated by | - | | "break" | - | | | + +------------+------------------------------------------------+ + | 0x78 | UTF-8 string (one-byte uint8_t for n, and then | + | | n bytes follow) | + +------------+------------------------------------------------+ + | 0x79 | UTF-8 string (two-byte uint16_t for n, and | + | | then n bytes follow) | + +------------+------------------------------------------------+ + | 0x7a | UTF-8 string (four-byte uint32_t for n, and | + | | then n bytes follow) | + +------------+------------------------------------------------+ + | 0x7b | UTF-8 string (eight-byte uint64_t for n, and | + | | then n bytes follow) | + +------------+------------------------------------------------+ + | 0x7f | UTF-8 string, UTF-8 strings follow, terminated | + | | by "break" | + +------------+------------------------------------------------+ | 0x80..0x97 | array (0x00..0x17 data items follow) | - | | | - | 0x98 | array (one-byte uint8_t for n, and then n data items | - | | follow) | - | | | - | 0x99 | array (two-byte uint16_t for n, and then n data | - | | items follow) | - | | | - | 0x9a | array (four-byte uint32_t for n, and then n data | - | | items follow) | - | | | - | 0x9b | array (eight-byte uint64_t for n, and then n data | + +------------+------------------------------------------------+ + | 0x98 | array (one-byte uint8_t for n, and then n data | | | items follow) | - | | | - | 0x9f | array, data items follow, terminated by "break" | - | | | - | 0xa0..0xb7 | map (0x00..0x17 pairs of data items follow) | - | | | - | 0xb8 | map (one-byte uint8_t for n, and then n pairs of | - | | data items follow) | - | | | - | 0xb9 | map (two-byte uint16_t for n, and then n pairs of | + +------------+------------------------------------------------+ + | 0x99 | array (two-byte uint16_t for n, and then n | | | data items follow) | - | | | - | 0xba | map (four-byte uint32_t for n, and then n pairs of | + +------------+------------------------------------------------+ + | 0x9a | array (four-byte uint32_t for n, and then n | | | data items follow) | - | | | - | 0xbb | map (eight-byte uint64_t for n, and then n pairs of | + +------------+------------------------------------------------+ + | 0x9b | array (eight-byte uint64_t for n, and then n | | | data items follow) | - | | | + +------------+------------------------------------------------+ + | 0x9f | array, data items follow, terminated by | + | | "break" | + +------------+------------------------------------------------+ + | 0xa0..0xb7 | map (0x00..0x17 pairs of data items follow) | + +------------+------------------------------------------------+ + | 0xb8 | map (one-byte uint8_t for n, and then n pairs | + | | of data items follow) | + +------------+------------------------------------------------+ + | 0xb9 | map (two-byte uint16_t for n, and then n pairs | + | | of data items follow) | + +------------+------------------------------------------------+ + | 0xba | map (four-byte uint32_t for n, and then n | + | | pairs of data items follow) | + +------------+------------------------------------------------+ + | 0xbb | map (eight-byte uint64_t for n, and then n | + | | pairs of data items follow) | + +------------+------------------------------------------------+ | 0xbf | map, pairs of data items follow, terminated by | | | "break" | - | | | + +------------+------------------------------------------------+ | 0xc0 | Text-based date/time (data item follows; see | | | Section 3.4.1) | - | | | + +------------+------------------------------------------------+ | 0xc1 | Epoch-based date/time (data item follows; see | | | Section 3.4.2) | - | | | - | 0xc2 | Positive bignum (data item "byte string" follows) | - | | | - | 0xc3 | Negative bignum (data item "byte string" follows) | - | | | - | 0xc4 | Decimal Fraction (data item "array" follows; see | - | | Section 3.4.4) | - | | | + +------------+------------------------------------------------+ + | 0xc2 | Positive bignum (data item "byte string" | + | | follows) | + +------------+------------------------------------------------+ + | 0xc3 | Negative bignum (data item "byte string" | + | | follows) | + +------------+------------------------------------------------+ + | 0xc4 | Decimal Fraction (data item "array" follows; | + | | see Section 3.4.4) | + +------------+------------------------------------------------+ | 0xc5 | Bigfloat (data item "array" follows; see | | | Section 3.4.4) | - | | | + +------------+------------------------------------------------+ | 0xc6..0xd4 | (tag) | - | | | + +------------+------------------------------------------------+ | 0xd5..0xd7 | Expected Conversion (data item follows; see | | | Section 3.4.5.2) | - | | | + +------------+------------------------------------------------+ | 0xd8..0xdb | (more tags, 1/2/4/8 bytes and then a data item | | | follow) | - | | | + +------------+------------------------------------------------+ | 0xe0..0xf3 | (simple value) | - | | | + +------------+------------------------------------------------+ | 0xf4 | False | - | | | + +------------+------------------------------------------------+ | 0xf5 | True | - | | | + +------------+------------------------------------------------+ | 0xf6 | Null | - | | | + +------------+------------------------------------------------+ | 0xf7 | Undefined | - | | | + +------------+------------------------------------------------+ | 0xf8 | (simple value, one byte follows) | - | | | + +------------+------------------------------------------------+ | 0xf9 | Half-Precision Float (two-byte IEEE 754) | - | | | + +------------+------------------------------------------------+ | 0xfa | Single-Precision Float (four-byte IEEE 754) | - | | | + +------------+------------------------------------------------+ | 0xfb | Double-Precision Float (eight-byte IEEE 754) | - | | | + +------------+------------------------------------------------+ | 0xff | "break" stop code | - +------------+------------------------------------------------------+ + +------------+------------------------------------------------+ Table 6: Jump Table for Initial Byte Appendix C. Pseudocode The well-formedness of a CBOR item can be checked by the pseudocode in Figure 1. The data is well-formed if and only if: * the pseudocode does not "fail"; - * after execution of the pseudocode, no bytes are left in the input (except in streaming applications) The pseudocode has the following prerequisites: * take(n) reads n bytes from the input data and returns them as a byte string. If n bytes are no longer available, take(n) fails. * uint() converts a byte string into an unsigned integer by interpreting the byte string in network byte order. @@ -2968,38 +2970,39 @@ E.5. Conciseness on the Wire While CBOR's design objective of code compactness for encoders and decoders is a higher priority than its objective of conciseness on the wire, many people focus on the wire size. Table 7 shows some encoding examples for the simple nested array [1, [2, 3]]; where some form of indefinite-length encoding is supported by the encoding, [_ 1, [2, 3]] (indefinite length on the outer array) is also shown. - +-------------+--------------------------+--------------------------+ + +-------------+----------------------------+----------------+ | Format | [1, [2, 3]] | [_ 1, [2, 3]] | - +-------------+--------------------------+--------------------------+ + +=============+============================+================+ | RFC 713 | c2 05 81 c2 02 82 83 | | - | | | | - | ASN.1 BER | 30 0b 02 01 01 30 06 02 | 30 80 02 01 01 30 06 02 | - | | 01 02 02 01 03 | 01 02 02 01 03 00 00 | - | | | | + +-------------+----------------------------+----------------+ + | ASN.1 BER | 30 0b 02 01 01 30 06 02 01 | 30 80 02 01 01 | + | | 02 02 01 03 | 30 06 02 01 02 | + | | | 02 01 03 00 00 | + +-------------+----------------------------+----------------+ | MessagePack | 92 01 92 02 03 | | - | | | | - | BSON | 22 00 00 00 10 30 00 01 | | - | | 00 00 00 04 31 00 13 00 | | - | | 00 00 10 30 00 02 00 00 | | - | | 00 10 31 00 03 00 00 00 | | - | | 00 00 | | - | | | | - | CBOR | 82 01 82 02 03 | 9f 01 82 02 03 ff | - +-------------+--------------------------+--------------------------+ + +-------------+----------------------------+----------------+ + | BSON | 22 00 00 00 10 30 00 01 00 | | + | | 00 00 04 31 00 13 00 00 00 | | + | | 10 30 00 02 00 00 00 10 31 | | + | | 00 03 00 00 00 00 00 | | + +-------------+----------------------------+----------------+ + | CBOR | 82 01 82 02 03 | 9f 01 82 02 03 | + | | | ff | + +-------------+----------------------------+----------------+ Table 7: Examples for Different Levels of Conciseness Appendix F. Changes from RFC 7049 The following is a list of known changes from RFC 7049. This list is non-authoritative. It is meant to help reviewers see the significant differences. * Updated reference for [RFC4627] to [RFC8259] in many places @@ -3169,16 +3172,16 @@ Authors' Addresses Carsten Bormann Universitaet Bremen TZI Postfach 330440 D-28359 Bremen Germany Phone: +49-421-218-63921 - EMail: cabo@tzi.org + Email: cabo@tzi.org Paul Hoffman ICANN - EMail: paul.hoffman@icann.org + Email: paul.hoffman@icann.org