Internet-Draft | Notable CBOR Tags | February 2022 |
Bormann | Expires 17 August 2022 | [Page] |
The Concise Binary Object Representation (CBOR, RFC 8949) 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.¶
In CBOR, one point of extensibility is the definition of CBOR tags. RFC 8949's original edition, RFC 7049, defined a basic set of tags as well as a registry that can be used to contribute additional tag definitions [IANA.cbor-tags]. Since RFC 7049 was published, some 80 tag definitions have been added to that registry.¶
The present document provides a roadmap to a large subset of these tag definitions. Where applicable, it points to a IETF standards or standard development document that specifies the tag. Where no such document exists, the intention is to collect specification information from the sources of the registrations. After some more development, the present document is intended to be useful as a reference document for the IANA registrations of the CBOR tags the definitions of which have been collected.¶
This is an individual submission to the CBOR working group of the IETF, https://datatracker.ietf.org/wg/cbor/about/. Discussion currently takes places on the github repository https://github.com/cabo/notable-tags. If the CBOR WG believes this is a useful document, discussion is likely to move to the CBOR WG mailing list and a github repository at the CBOR WG github organization, https://github.com/cbor-wg.¶
The current version is true work in progress; some of the sections haven't been filled in yet, and in particular, permission has not been obtained from tag definition authors to copy over their text.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 17 August 2022.¶
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
(TO DO, expand on text from abstract here; move references here and neuter them in the abstract as per Section 4.3 of [RFC7322].)¶
The selection of the tags presented here is somewhat arbitrary; considerations such as how wide the scope and area of application of a tag definition is combine with an assessment how "ready to use" the tag definition is (i.e., is the tag specification in a state where it can be used).¶
This document can only be a snapshot of a subset of the current registrations. The most up to date set of registrations is always available in the registry "CBOR Tags" [IANA.cbor-tags].¶
The definitions of [STD94] apply.
Specifically: The term "byte" is used in its now customary sense as a synonym for
"octet"; "byte strings" are CBOR data items carrying a sequence of
zero or more (binary) bytes, while "text strings" are CBOR data items carrying a
sequence of zero or more Unicode code points, encoded in UTF-8 [STD63].
Where bit arithmetic is explained, this document uses the notation
familiar from the programming language C ([C], including C++14's 0bnnn
binary literals [Cplusplus20]), except that superscript notation
(example for two to the power of 64: 264) denotes exponentiation; in
the plain text version of this document, superscript notation is
rendered in paragraph text by C-incompatible surrogate notation as
seen in this example.
Ranges expressed using ..
are inclusive of the limits given.
Type names such as "int", "bigint" or "decfrac" are taken from
Appendix D of [RFC8610], the Concise Data Definition Language (CDDL).¶
[RFC7049] defines a number of tags that are listed here for convenience only.¶
A number of CBOR tags are defined in security specifications that make use of CBOR.¶
[RFC8152] defines CBOR Object Signing and Encryption (COSE). A revision is in process that splits this specification into the data structure definitions [I-D.ietf-cose-rfc8152bis-struct], which will define another tag for COSE standalone counter signature, and the algorithms employed [I-D.ietf-cose-rfc8152bis-algs].¶
[RFC8392] defines the CBOR Web Token (CWT), making use of COSE to define a CBOR variant of the JOSE Web Token (JWT), [RFC7519], a standardized security token that has found use in the area of web applications, but is not technically limited to those.¶
Representation formats can be built on top of CBOR.¶
YANG [RFC7950] is a data modeling language originally designed in the context of the Network Configuration Protocol (NETCONF) [RFC6241], now widely used for modeling management and configuration information. [RFC7950] defines an XML-based representation format, and [RFC7951] defines a JSON-based [RFC8259] representation format for YANG.¶
YANG-CBOR [I-D.ietf-core-yang-cbor] is a representation format for YANG data in CBOR.¶
Protocols may want to allocate CBOR tag numbers to identify specific protocol elements.¶
DDoS Open Threat Signaling (DOTS) defines tag number 271 for the DOTS signal channel object in [RFC9132].¶
As an example for how experimental protocols can make use of CBOR tag definitions, the RAINS (Another Internet Naming Service) Protocol Specification defines tag number 15309736 for a RAINS Message [I-D.trammell-rains-protocol]. (The seemingly random tag number was chosen so that, when represented as an encoded CBOR tag argument, it contains the Unicode character "雨" (U+96E8) in UTF-8, which represents rain in a number of languages.)¶
A number of tags have been registered for arithmetic representations
beyond those built into CBOR and defined by tags in [RFC7049].
These are all documented under http://peteroupc.github.io/CBOR/
; the
last pathname component for the URL is given in Table 5.¶
CBOR's basic generic data model (Section 2 of [STD94]) has a number system with limited-range integers (major types 0 and 1: -264..264-1) and floating point numbers that cover binary16, binary32, and binary64 (including non-finites) from [IEEE754]. With the tags defined with [RFC7049], the extended generic data model (Section 2.1 of [STD94]) adds unlimited-range integers (tag numbers 2 and 3, "bigint" in CDDL) as well as floating point values using the bases 2 (tag number 5, "bigfloat") and 10 (tag number 4, "decfrac").¶
This pre-defined number system has a number of limitations that are addressed in three of the tags discussed here:¶
Tag number 30 allows the representation of rational numbers as a ratio of two integers: a numerator (usually written as the top part of a fraction), and a denominator (the bottom part), where both integers can be limited-range basic and unlimited-range integers. The mathematical value of a rational number is the numerator divided by the denominator. This tag can express all numbers that the extended generic data model of [RFC7049] can express, except for non-finites [IEEE754]; it also can express rational numbers that cannot be expressed with denominators that are a power of 2 or a power of 10.¶
For example, the rational number 1/3 is encoded:¶
d8 1e ---- Tag 30 82 ---- Array length 2 01 ---- 1 03 ---- 3¶
Many programming languages have built-in support for rational numbers or support for them is included in their standard libraries; tag number 30 is a way for these platforms to interchange these rational numbers in CBOR.¶
The tag numbers 268..270 extend these tags further by providing a way to express non-finites within a tag with this number. This does not increase the expressiveness of the data model (the non-finites can already be expressed using major type 7 floating point numbers), but does allow both finite and non-finite values to carry the same tag. In most applications, a choice that includes some of the three tags 30, 264, 265 for finite values and major type 7 floating point values for non-finites (as well as possibly other parts of the CBOR number system) will be the preferred solution.¶
This document suggests using the CDDL typenames defined in Figure 1 for the three most useful tag numbers in this section.¶
https://github.com/svaarala/cbor-specs/blob/master/cbor-absent-tag.rst
defines tag 31 to be applied to the CBOR value Undefined (0xf7),
slightly modifying its semantics to stand for an absent value in a
CBOR Array.¶
(TO DO: Obtain permission to copy the definitions here.)¶
[RFC8746] defines tags for various kinds of arrays. A summary is reproduced in Table 6.¶
(TO DO: Obtain permission to copy the definitions here; explain how tags 52 and 54 essentially obsolete 260/261.)¶
Tag number | Tag content | Short Description | Reference | Author |
---|---|---|---|---|
37 | byte string | Binary UUID (Section 4.1.2 of [RFC4122]) | https://github.com/lucas-clemente/cbor-specs/blob/master/uuid.md | Lucas Clemente |
38 | array | Language-tagged string | http://peteroupc.github.io/CBOR/langtags.html | Peter Occil |
257 | byte string | Binary MIME message | http://peteroupc.github.io/CBOR/binarymime.html | Peter Occil |
260 | byte string | Network Address (IPv4 or IPv6 or MAC Address) | http://www.employees.org/~ravir/cbor-network.txt | Ravi Raju |
261 | map | Network Address Prefix (IPv4 or IPv6 Address + Mask Length) | https://github.com/toravir/CBOR-Tag-Specs/blob/master/networkPrefix.md | Ravi Raju |
263 | byte string | Hexadecimal string | https://github.com/toravir/CBOR-Tag-Specs/blob/master/hexString.md | Ravi Raju |
266 | text string | Internationalized resource identifier (IRI) | https://peteroupc.github.io/CBOR/iri.html | Peter Occil |
267 | text string | Internationalized resource identifier reference (IRI reference) | https://peteroupc.github.io/CBOR/iri.html | Peter Occil |
Additional tag definitions have been provided for date and time values.¶
Note that tags 100 and 1004 are for calendar dates that are not anchored to a specific time zone; they are meant to specify calendar dates as perceived by humans, e.g. for use in personal identification documents. Converting such a calendar date into a specific point in time needs the addition of a time-of-day (for which a CBOR tag is outstanding) and timezone information (also outstanding). Alternatively, a calendar date plus timezone information can be converted into a time period (range of time values given by the starting and the ending time); note that these time periods are not always exactly 24 h (86400 s) long.¶
[RFC8943] does not suggest CDDL [RFC8610] type names for the two tags. We suggest copying the definitions in Figure 2 into application-specific CDDL as needed.¶
Tag 1001 extends tag 1 by additional information (such as picosecond resolution) and allows the use of Decimal and Bigfloat numbers for the time.¶
(These are actually not as Perl-specific as the title of this section suggests. See also the penultimate paragraph of Section 3.4 of [STD94].)¶
These are all documented under http://cbor.schmorp.de/
; the
last pathname component is given in Table 9.¶
(TO DO: Obtain permission to copy the definitions here.)¶
(TO DO: Obtain permission to copy the definitions here.)¶
Tag number 262 has been registered to identify byte strings that carry embedded
JSON text (https://github.com/toravir/CBOR-Tag-Specs/blob/master/embeddedJSON.md
).¶
Tag number 275 can be used to identify maps that contain keys that are
all of type Text String, as they would occur in JSON
(https://github.com/ecorm/cbor-tag-text-key-map
).¶
(TO DO: Obtain permission to copy the definitions here.)¶
Some variants of UTF-8 are in use in specific areas of application.
Tags have been registered to be able to carry around strings in these
variants in case they are not also valid UTF-8 and can therefore not
be represented as a CBOR text string
(https://github.com/svaarala/cbor-specs/blob/master/cbor-nonutf8-string-tags.rst
).¶
(TO DO: Obtain permission to copy the definitions here.)¶
Tag number | Tag content | Short Description | Reference | Author |
---|---|---|---|---|
39 | multiple | Identifier | [https://github.com/lucas-clemente/cbor-specs/blob/master/id.md | Lucas Clemente |
42 | byte string | IPLD content identifier | [https://github.com/ipld/cid-cbor/ | Volker Mische |
103 | array | Geographic Coordinates | [https://github.com/allthingstalk/cbor/blob/master/CBOR-Tag103-Geographic-Coordinates.md | Danilo Vidovic |
104 | multiple | Geographic Coordinate Reference System WKT or EPSG number | [I-D.clarke-cbor-crs] | |
120 | multiple | Internet of Things Data Point | [https://github.com/allthingstalk/cbor/blob/master/CBOR-Tag120-Internet-of-Things-Data-Points.md | Danilo Vidovic |
258 | array | Mathematical finite set | [https://github.com/input-output-hk/cbor-sets-spec/blob/master/CBOR_SETS.md | Alfredo Di Napoli |
259 | map | Map datatype with key-value operations (e.g. .get ()/.set()/.delete() ) |
[https://github.com/shanewholloway/js-cbor-codec/blob/master/docs/CBOR-259-spec--explicit-maps.md | Shane Holloway |
The present document registers tag numbers 65535, 4294967295, and 18446744073709551615 (16-bit 0xffff, 32-bit 0xffffffff, and 64-bit 0xffffffffffffffff) as Invalid Tags, tags that are always invalid, independent of the tag content provided. The purpose of these tag number registrations is to enable the tag numbers to be reserved for internal use by implementations to note the absence of a tag on a data item where a tag could also be expected with that data item as tag content.¶
The Invalid Tags are not intended to ever occur in interchanged CBOR data items. Generic CBOR decoder implementations are encouraged to raise an error if an Invalid Tag occurs in a CBOR data item even if there is no validity checking implemented otherwise.¶
In the registry "CBOR Tags" [IANA.cbor-tags], IANA has allocated the first to third tag in Table 12 from the FCFS space, with the present document as the specification reference. IANA has allocated the fourth tag from the Specification Required space, with the present document as the specification reference.¶
Tag | Data Item | Semantics | Reference |
---|---|---|---|
65535 | (none valid) | always invalid | draft-bormann-cbor-notable-tags, Section 10.1 |
4294967295 | (none valid) | always invalid | draft-bormann-cbor-notable-tags, Section 10.1 |
18446744073709551615 | (none valid) | always invalid | draft-bormann-cbor-notable-tags, Section 10.1 |
63 | byte string | Encoded CBOR Sequence [RFC8742] | draft-bormann-cbor-notable-tags, Section 2.1 |
The security considerations of [STD94] apply; the tags discussed here may also have specific security considerations that are mentioned in their specific sections above.¶
(Many, TBD)¶
Peter Occil registered tags 30, 264, 265, 268-270 (Section 6.1), 38, 257, 266 and 267 (Section 7), and contributed much of the text about these tags in this document.¶
Further contributors will be listed here as text is added.¶
Plase stay tuned.¶