Internet-Draft Notable CBOR Tags February 2021
Bormann Expires 16 August 2021 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-bormann-cbor-notable-tags-03
Published:
Intended Status:
Informational
Expires:
Author:
C. Bormann
Universität Bremen TZI

Notable CBOR Tags

Abstract

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.

Note to Readers

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.

Status of This Memo

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.

Table of Contents

1. Introduction

(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].

1.1. Terminology

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.

2. RFC 7049 (CBOR)

[RFC7049] defines a number of tags that are listed here for convenience only.

Table 1: Tag numbers defined in RFC 7049
Tag number Tag content Short Description Section of RFC 7049
0 UTF-8 string Standard date/time string 2.4.1
1 multiple Epoch-based date/time 2.4.1
2 byte string Positive bignum 2.4.2
3 byte string Negative bignum 2.4.2
4 array Decimal fraction 2.4.3
5 array Bigfloat 2.4.3
21 multiple Expected conversion to base64url encoding 2.4.4.2
22 multiple Expected conversion to base64 encoding 2.4.4.2
23 multiple Expected conversion to base16 encoding 2.4.4.2
24 byte string Encoded CBOR data item 2.4.4.1
32 UTF-8 string URI 2.4.4.3
33 UTF-8 string base64url 2.4.4.3
34 UTF-8 string base64 2.4.4.3
35 UTF-8 string Regular expression 2.4.4.3
36 UTF-8 string MIME message 2.4.4.3
55799 multiple Self-describe CBOR 2.4.5

3. Security

A number of CBOR tags are defined in security specifications that make use of CBOR.

3.1. RFC 8152 (COSE)

[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].

Table 2: Tag numbers defined in RFC 8152, COSE
Tag number Tag content Short Description
16 COSE_Encrypt0 COSE Single Recipient Encrypted Data Object
17 COSE_Mac0 COSE Mac w/o Recipients Object
18 COSE_Sign1 COSE Single Signer Data Object
96 COSE_Encrypt COSE Encrypted Data Object
97 COSE_Mac COSE MACed Data Object
98 COSE_Sign COSE Signed Data Object

3.2. RFC 8392 (CWT)

[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.

Table 3: Tag number defined for RFC 8392 CBOR Web Token (CWT)
Tag number Tag content Short Description
61 CBOR Web Token (CWT) CBOR Web Token (CWT)

4. CBOR-based Representation Formats

Representation formats can be built on top of CBOR.

4.1. YANG-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.

Table 4: Tag number defined for YANG-CBOR
Tag number Tag content Short Description Section of YANG-CBOR
43 byte string YANG bits datatype 6.7
44 unsigned integer YANG enumeration datatype 6.6
45 unsigned integer or text string YANG identityref datatype 6.10
46 unsigned integer or text string or array YANG instance-identifier datatype 6.13
47 unsigned integer YANG Schema Item iDentifier (sid) 3.2

5. Protocols

Protocols may want to allocate CBOR tag numbers to identify specific protocol elements.

5.1. DOTS

DDoS Open Threat Signaling (DOTS) defines tag number 271 for the DOTS signal channel object in [RFC8782].

5.2. RAINS

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].

6. Datatypes

6.1. Advanced arithmetic

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.)

Table 5: Tags for advanced arithmetic
Tag number Tag content Short Description Reference
30 array Rational number rational.html
264 array Decimal fraction with arbitrary exponent bigfrac.html
265 array Bigfloat with arbitrary exponent bigfrac.html
268 array Extended decimal fraction extended.html
269 array Extended bigfloat extended.html
270 array Extended rational number extended.html

6.2. Variants of undefined

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.)

6.3. Typed and Homogeneous Arrays

[RFC8746] defines tags for various kinds of arrays. A summary is reproduced in Table 6.

Table 6: Tag numbers defined for Arrays
Tag Data Item Semantics
64 byte string uint8 Typed Array
65 byte string uint16, big endian, Typed Array
66 byte string uint32, big endian, Typed Array
67 byte string uint64, big endian, Typed Array
68 byte string uint8 Typed Array, clamped arithmetic
69 byte string uint16, little endian, Typed Array
70 byte string uint32, little endian, Typed Array
71 byte string uint64, little endian, Typed Array
72 byte string sint8 Typed Array
73 byte string sint16, big endian, Typed Array
74 byte string sint32, big endian, Typed Array
75 byte string sint64, big endian, Typed Array
76 byte string (reserved)
77 byte string sint16, little endian, Typed Array
78 byte string sint32, little endian, Typed Array
79 byte string sint64, little endian, Typed Array
80 byte string IEEE 754 binary16, big endian, Typed Array
81 byte string IEEE 754 binary32, big endian, Typed Array
82 byte string IEEE 754 binary64, big endian, Typed Array
83 byte string IEEE 754 binary128, big endian, Typed Array
84 byte string IEEE 754 binary16, little endian, Typed Array
85 byte string IEEE 754 binary32, little endian, Typed Array
86 byte string IEEE 754 binary64, little endian, Typed Array
87 byte string IEEE 754 binary128, little endian, Typed Array
40 array of two arrays* Multi-dimensional Array, row-major order
1040 array of two arrays* Multi-dimensional Array, column-major order
41 array Homogeneous Array

7. Domain-Specific

(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)

7.1. Extended Time Formats

Additional tag definitions have been provided for date and time values.

Table 7: Tag numbers for date and time
Tag Data Item Semantics Reference
100 integer date in number of days since epoch [RFC8943]
1004 text string RFC 3339 full-date string [RFC8943]
1001 map extended time [I-D.bormann-cbor-time-tag]
1002 map duration [I-D.bormann-cbor-time-tag]
1003 map period [I-D.bormann-cbor-time-tag]

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.

caldate = #6.100(int) ; calendar date as a number of days from 1970-01-01
tcaldate = #6.1004(tstr) ; calendar date as an RFC 3339 full-date string
Figure 1: CDDL for calendar date tags (RFC8943)

Tag 1001 extends tag 1 by additional information (such as picosecond resolution) and allows the use of Decimal and Bigfloat numbers for the time.

8. Platform-oriented

8.1. Perl

(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.)

Table 8: Tag numbers that aid the Perl platform
Tag Data Item Semantics Reference
256 multiple mark value as having string references stringref
25 unsigned integer reference the nth previously seen string stringref
26 array Serialised Perl object with classname and constructor arguments perl-object
27 array Serialised language-independent object with type name and constructor arguments generic-object
28 multiple mark value as (potentially) shared value-sharing
29 unsigned integer reference nth marked value value-sharing
22098 multiple hint that indicates an additional level of indirection indirection

8.2. JSON

(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).

8.3. Weird text encodings

(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).

Table 9: Tag numbers for UTF-8 variants
Tag Number Data Item Semantics
272 byte string Non-UTF-8 CESU-8 string
273 byte string Non-UTF-8 WTF-8 string
274 byte string Non-UTF-8 MUTF-8 string

9. Application-specific

(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()`)

10. Implementation aids

10.1. Invalid Tag

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.

11. IANA Considerations

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.

Table 10: Values for Tags
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

12. Security Considerations

The security considerations of [RFC8949] apply; the tags discussed here may also have specific security considerations that are mentioned in their specific sections above.

13. References

13.1. Normative References

[I-D.ietf-core-yang-cbor]
Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of Data Modeled with YANG", Work in Progress, Internet-Draft, draft-ietf-core-yang-cbor-15, , <http://www.ietf.org/internet-drafts/draft-ietf-core-yang-cbor-15.txt>.
[IANA.cbor-tags]
IANA, "Concise Binary Object Representation (CBOR) Tags", <http://www.iana.org/assignments/cbor-tags>.
[RFC8152]
Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, , <https://www.rfc-editor.org/info/rfc8152>.
[RFC8392]
Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, , <https://www.rfc-editor.org/info/rfc8392>.
[RFC8610]
Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, , <https://www.rfc-editor.org/info/rfc8610>.
[RFC8746]
Bormann, C., Ed., "Concise Binary Object Representation (CBOR) Tags for Typed Arrays", RFC 8746, DOI 10.17487/RFC8746, , <https://www.rfc-editor.org/info/rfc8746>.
[RFC8782]
Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., Mortensen, A., and N. Teague, "Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal Channel Specification", RFC 8782, DOI 10.17487/RFC8782, , <https://www.rfc-editor.org/info/rfc8782>.
[RFC8949]
Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, , <https://www.rfc-editor.org/info/rfc8949>.

13.2. Informative References

[I-D.bormann-cbor-time-tag]
Bormann, C., Gamari, B., and H. Birkholz, "Concise Binary Object Representation (CBOR) Tags for Time, Duration, and Period", Work in Progress, Internet-Draft, draft-bormann-cbor-time-tag-03, , <http://www.ietf.org/internet-drafts/draft-bormann-cbor-time-tag-03.txt>.
[I-D.ietf-cose-rfc8152bis-algs]
Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", Work in Progress, Internet-Draft, draft-ietf-cose-rfc8152bis-algs-12, , <http://www.ietf.org/internet-drafts/draft-ietf-cose-rfc8152bis-algs-12.txt>.
[I-D.ietf-cose-rfc8152bis-struct]
Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", Work in Progress, Internet-Draft, draft-ietf-cose-rfc8152bis-struct-14, , <http://www.ietf.org/internet-drafts/draft-ietf-cose-rfc8152bis-struct-14.txt>.
[I-D.trammell-rains-protocol]
Trammell, B. and C. Fehlmann, "RAINS (Another Internet Naming Service) Protocol Specification", Work in Progress, Internet-Draft, draft-trammell-rains-protocol-05, , <http://www.ietf.org/internet-drafts/draft-trammell-rains-protocol-05.txt>.
[RFC2045]
Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, DOI 10.17487/RFC2045, , <https://www.rfc-editor.org/info/rfc2045>.
[RFC4122]
Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, , <https://www.rfc-editor.org/info/rfc4122>.
[RFC6241]
Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, , <https://www.rfc-editor.org/info/rfc6241>.
[RFC7049]
Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, , <https://www.rfc-editor.org/info/rfc7049>.
[RFC7322]
Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, DOI 10.17487/RFC7322, , <https://www.rfc-editor.org/info/rfc7322>.
[RFC7519]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/info/rfc7519>.
[RFC7950]
Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, , <https://www.rfc-editor.org/info/rfc7950>.
[RFC7951]
Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, , <https://www.rfc-editor.org/info/rfc7951>.
[RFC8259]
Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/info/rfc8259>.
[RFC8742]
Bormann, C., "Concise Binary Object Representation (CBOR) Sequences", RFC 8742, DOI 10.17487/RFC8742, , <https://www.rfc-editor.org/info/rfc8742>.
[RFC8943]
Jones, M., Nadalin, A., and J. Richter, "Concise Binary Object Representation (CBOR) Tags for Date", RFC 8943, DOI 10.17487/RFC8943, , <https://www.rfc-editor.org/info/rfc8943>.

Acknowledgements

Contributors

Peter Occil
Many More
To do

Author's Address

Carsten Bormann
Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany