Internet-Draft | Notable CBOR Tags | February 2021 |
Bormann | Expires 16 August 2021 | [Page] |
The Concise Binary Object Representation (CBOR, RFC 7049) 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 7049 and its revision 7049bis define 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 16 August 2021.¶
Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
(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 at [IANA.cbor-tags].¶
The definitions of [RFC8949] apply. The term "byte" is used in its now customary sense as a synonym for "octet". Where bit arithmetic is explained, this document uses the notation familiar from the programming language C (including C++14's 0bnnn binary literals), except that the operator "**" stands for exponentiation.¶
[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 [RFC8782].¶
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].¶
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 is given in Table 5.¶
(TO DO: Obtain permission to copy the definitions here.)¶
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; create proper table.)¶
37 byte string Binary UUID ([RFC4122] section [https://github.com/lucas-clemente/cbor-specs/blob/master/uuid.md][Lucas_Clemente] 4.1.2) 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 [http://www.employees.org/~ravir/cbor-network.txt][Ravi_Raju] MAC Address) map Network Address Prefix (IPv4 or 261 (IPAddress + IPv6 Address + Mask Length) [https://github.com/toravir/CBOR-Tag-Specs/blob/master/networkPrefix.md][Ravi_Raju] Mask Length) 263 byte string Hexadecimal string [https://github.com/toravir/CBOR-Tag-Specs/blob/master/hexString.md][Ravi_Raju] 266 text string Internationalized resource [https://peteroupc.github.io/CBOR/iri.html][Peter_Occil] identifier (IRI) Internationalized resource 267 text string identifier reference (IRI [https://peteroupc.github.io/CBOR/iri.html][Peter_Occil] reference)¶
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 1 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 [RFC8949].)¶
These are all documented under http://cbor.schmorp.de/
; the
last pathname component is given in Table 8.¶
(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; create proper table.)¶
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 [draft-clarke-cbor-crs] System WKT or EPSG number 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] Map datatype with key-value 259 map operations (e.g. [https://github.com/shanewholloway/js-cbor-codec/blob/master/docs/CBOR-259-spec--explicit-maps.md][Shane_Holloway] `.get()/.set()/.delete()`)¶
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 [IANA.cbor-tags], IANA has allocated the first to third tag in Table 10 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 [RFC8949] apply; the tags discussed here may also have specific security considerations that are mentioned in their specific sections above.¶