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