draft-ietf-cbor-array-tags-07.txt   draft-ietf-cbor-array-tags-08.txt 
Network Working Group C. Bormann, Ed. Network Working Group C. Bormann, Ed.
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Intended status: Standards Track August 22, 2019 Intended status: Standards Track October 08, 2019
Expires: February 23, 2020 Expires: April 10, 2020
Concise Binary Object Representation (CBOR) Tags for Typed Arrays Concise Binary Object Representation (CBOR) Tags for Typed Arrays
draft-ietf-cbor-array-tags-07 draft-ietf-cbor-array-tags-08
Abstract Abstract
The Concise Binary Object Representation (CBOR, RFC 7049) is a data The Concise Binary Object Representation (CBOR, RFC 7049) is a data
format whose design goals include the possibility of extremely small format whose design goals include the possibility of extremely small
code size, fairly small message size, and extensibility without the code size, fairly small message size, and extensibility without the
need for version negotiation. need for version negotiation.
The present document makes use of this extensibility to define a The present document makes use of this extensibility to define a
number of CBOR tags for typed arrays of numeric data, as well as two number of CBOR tags for typed arrays of numeric data, as well as two
skipping to change at page 1, line 39 skipping to change at page 1, line 39
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 February 23, 2020. This Internet-Draft will expire on April 10, 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/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 15 skipping to change at page 2, line 15
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Typed Arrays . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Typed Arrays . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Types of numbers . . . . . . . . . . . . . . . . . . . . 3 2.1. Types of numbers . . . . . . . . . . . . . . . . . . . . 4
3. Additional Array Tags . . . . . . . . . . . . . . . . . . . . 5 3. Additional Array Tags . . . . . . . . . . . . . . . . . . . . 5
3.1. Multi-dimensional Array . . . . . . . . . . . . . . . . . 5 3.1. Multi-dimensional Array . . . . . . . . . . . . . . . . . 6
3.1.1. Row-major Order . . . . . . . . . . . . . . . . . . . 6 3.1.1. Row-major Order . . . . . . . . . . . . . . . . . . . 6
3.1.2. Column-Major order . . . . . . . . . . . . . . . . . 7 3.1.2. Column-Major order . . . . . . . . . . . . . . . . . 7
3.2. Homogeneous Array . . . . . . . . . . . . . . . . . . . . 8 3.2. Homogeneous Array . . . . . . . . . . . . . . . . . . . . 8
4. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 9 4. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 10 5. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
8.1. Normative References . . . . . . . . . . . . . . . . . . 14 8.1. Normative References . . . . . . . . . . . . . . . . . . 14
8.2. Informative References . . . . . . . . . . . . . . . . . 14 8.2. Informative References . . . . . . . . . . . . . . . . . 14
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction 1. Introduction
The Concise Binary Object Representation (CBOR, [RFC7049]) provides The Concise Binary Object Representation (CBOR, [RFC7049]) provides
for the interchange of structured data without a requirement for a for the interchange of structured data without a requirement for a
pre-agreed schema. RFC 7049 defines a basic set of data types, as pre-agreed schema. RFC 7049 defines a basic set of data types, as
well as a tagging mechanism that enables extending the set of data well as a tagging mechanism that enables extending the set of data
types supported via an IANA registry. types supported via an IANA registry.
Recently, a simple form of typed arrays of numeric data have received Recently, a simple form of typed arrays of numeric data has received
interest both in the Web graphics community [TypedArray] and in the interest both in the Web graphics community [TypedArray] and in the
JavaScript specification [TypedArrayES6], as well as in corresponding JavaScript specification [TypedArrayES6], as well as in corresponding
implementations [ArrayBuffer]. implementations [ArrayBuffer].
Since these typed arrays may carry significant amounts of data, there Since these typed arrays may carry significant amounts of data, there
is interest in interchanging them in CBOR without the need of lengthy is interest in interchanging them in CBOR without the need of lengthy
conversion of each number in the array. This also can save space conversion of each number in the array. This can also save space
overhead with encoding a type for each element of an array. overhead with encoding a type for each element of an array.
This document defines a number of interrelated CBOR tags that cover This document defines a number of interrelated CBOR tags that cover
these typed arrays, as well as two additional tags for multi- these typed arrays, as well as two additional tags for multi-
dimensional and homogeneous arrays. It is intended as the reference dimensional and homogeneous arrays. It is intended as the reference
document for the IANA registration of the tags defined. document for the IANA registration of the tags defined.
Note that an application that generates CBOR with these tags has Note that an application that generates CBOR with these tags has
considerable freedom in choosing variants, e.g., with respect to considerable freedom in choosing variants, e.g., with respect to
endianness, embedded type (signed vs. unsigned), and number of bits endianness, embedded type (signed vs. unsigned), and number of bits
skipping to change at page 3, line 28 skipping to change at page 3, line 28
1.1. Terminology 1.1. 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.
The term "byte" is used in its now customary sense as a synonym for The term "byte" is used in its now customary sense as a synonym for
"octet". Where bit arithmetic is explained, this document uses the "octet". Where bit arithmetic is explained, this document uses the
notation familiar from the programming language C (including C++14's notation familiar from the programming language C [C] (including
0bnnn binary literals), except that the operator "**" stands for C++14's 0bnnn binary literals [Cplusplus]), except that the operator
exponentiation. "**" stands for exponentiation.
The term "array" is used in a general sense in this document, unless The term "array" is used in a general sense in this document, unless
further specified. The term "classical CBOR array" describes an further specified. The term "classical CBOR array" describes an
array represented with CBOR major type 4. A "homogeneous array" is array represented with CBOR major type 4. A "homogeneous array" is
an array of elements that are all of the same type (the term is an array of elements that are all of the same type (the term is
neutral whether that is a representation type or an application data neutral as to whether that is a representation type or an application
model type). data model type).
The terms "big endian" and "little endian" are used to indicate a
most significant byte first (MSB first) representation of integers,
and a least significant byte first (LSB first) representation,
respectively.
2. Typed Arrays 2. Typed Arrays
Typed arrays are homogeneous arrays of numbers, all of which are Typed arrays are homogeneous arrays of numbers, all of which are
encoded in a single form of binary representation. The concatenation encoded in a single form of binary representation. The concatenation
of these representations is encoded as a single CBOR byte string of these representations is encoded as a single CBOR byte string
(major type 2), enclosed by a single tag indicating the type and (major type 2), enclosed by a single tag indicating the type and
encoding of all the numbers represented in the byte string. encoding of all the numbers represented in the byte string.
2.1. Types of numbers 2.1. Types of numbers
skipping to change at page 4, line 44 skipping to change at page 5, line 10
of the tag: Tag values from 64 to 87. of the tag: Tag values from 64 to 87.
The value is split up into 5 bit fields: 0b010_f_s_e_ll, as detailed The value is split up into 5 bit fields: 0b010_f_s_e_ll, as detailed
in Table 2. in Table 2.
+-------+-------------------------------------------------------+ +-------+-------------------------------------------------------+
| Field | Use | | Field | Use |
+-------+-------------------------------------------------------+ +-------+-------------------------------------------------------+
| 0b010 | the constant bits 0, 1, 0 | | 0b010 | the constant bits 0, 1, 0 |
| f | 0 for integer, 1 for float | | f | 0 for integer, 1 for float |
| s | 0 for unsigned integer or float, 1 for signed integer | | s | 0 for float or unsigned integer, 1 for signed integer |
| e | 0 for big endian, 1 for little endian | | e | 0 for big endian, 1 for little endian |
| ll | A number for the length (Table 1). | | ll | A number for the length (Table 1). |
+-------+-------------------------------------------------------+ +-------+-------------------------------------------------------+
Table 2: Bit fields in the low 8 bits of the tag Table 2: Bit fields in the low 8 bits of the tag
The number of bytes in each array element can then be calculated by The number of bytes in each array element can then be calculated by
"2**(f + ll)" (or "1 << (f + ll)" in a typical programming language). "2**(f + ll)" (or "1 << (f + ll)" in a typical programming language).
(Notice that 0f and ll are the two least significant bits, (Notice that 0f and ll are the two least significant bits,
respectively, of each nibble (4bit) in the byte.) respectively, of each nibble (4bit) in the byte.)
In the CBOR representation, the total number of elements in the array In the CBOR representation, the total number of elements in the array
is not expressed explicitly, but implied from the length of the byte is not expressed explicitly, but implied from the length of the byte
string and the length of each representation. It can be computed string and the length of each representation. It can be computed
inversely to the previous formula from the length of the byte string from the length, in bytes, of the byte string comprising the
in bytes: "bytelength >> (f + ll)". representation of the array by inverting the previous formula:
"bytelength >> (f + ll)".
For the uint8/sint8 values, the endianness is redundant. Only the For the uint8/sint8 values, the endianness is redundant. Only the
tag for the big endian variant is used and assigned as such. The Tag tag for the big endian variant is used and assigned as such. The Tag
that would signify the little endian variant of sint8 MUST NOT be that would signify the little endian variant of sint8 MUST NOT be
used, its tag number is marked as reserved. As a special case, the used, its tag number is marked as reserved. As a special case, the
Tag that would signify the little endian variant of uint8 is instead Tag that would signify the little endian variant of uint8 is instead
assigned to signify that the numbers in the array are using clamped assigned to signify that the numbers in the array are using clamped
conversion from integers, as described in more detail in conversion from integers, as described in more detail in
Section 7.1.11 ("ToUint8Clamp") of the ES6 JavaScript specification Section 7.1.11 ("ToUint8Clamp") of the ES6 JavaScript specification
[TypedArrayES6]; the assumption here is that a program-internal [TypedArrayES6]; the assumption here is that a program-internal
skipping to change at page 6, line 8 skipping to change at page 6, line 21
A multi-dimensional array is represented as a tagged array that A multi-dimensional array is represented as a tagged array that
contains two (one-dimensional) arrays. The first array defines the contains two (one-dimensional) arrays. The first array defines the
dimensions of the multi-dimensional array (in the sequence of outer dimensions of the multi-dimensional array (in the sequence of outer
dimensions towards inner dimensions) while the second array dimensions towards inner dimensions) while the second array
represents the contents of the multi-dimensional array. If the represents the contents of the multi-dimensional array. If the
second array is itself tagged as a Typed Array then the element type second array is itself tagged as a Typed Array then the element type
of the multi-dimensional array is known to be the same type as that of the multi-dimensional array is known to be the same type as that
of the Typed Array. of the Typed Array.
Two tags are defined by this document, one for elements arranged in Two tags are defined by this document, one for elements arranged in
row-major order, and one for column-major order. row-major order, and one for column-major order [RowColMajor].
3.1.1. Row-major Order 3.1.1. Row-major Order
Tag: 40 Tag: 40
Data Item: array (major type 4) of two arrays, one array (major type Data Item: array (major type 4) of two arrays, one array (major type
4) of dimensions, which are unsigned integers distinct from zero, 4) of dimensions, which are unsigned integers distinct from zero,
and one array (either a CBOR array of major type 4, or a Typed and one array (either a CBOR array of major type 4, or a Typed
Array, or a Homogeneous Array) of elements Array, or a Homogeneous Array) of elements
skipping to change at page 8, line 25 skipping to change at page 8, line 47
type of the first array element. type of the first array element.
This can be used in application data models that apply specific This can be used in application data models that apply specific
semantics to homogeneous arrays. Also, in certain cases, semantics to homogeneous arrays. Also, in certain cases,
implementations in strongly typed languages may be able to create implementations in strongly typed languages may be able to create
native homogeneous arrays of specific types instead of ordered lists native homogeneous arrays of specific types instead of ordered lists
while decoding. Which CBOR data items constitute elements of the while decoding. Which CBOR data items constitute elements of the
same application type is specific to the application. same application type is specific to the application.
Figure 4 shows an example for a homogeneous array of booleans in C++ Figure 4 shows an example for a homogeneous array of booleans in C++
and CBOR. [Cplusplus] and CBOR.
bool boolArray[2] = { true, false }; bool boolArray[2] = { true, false };
<Tag 41> # Homogeneous Array Tag <Tag 41> # Homogeneous Array Tag
82 #array(2) 82 #array(2)
F5 # true F5 # true
F4 # false F4 # false
Figure 4: Homogeneous array in C++ and CBOR Figure 4: Homogeneous array in C++ and CBOR
skipping to change at page 14, line 9 skipping to change at page 14, line 9
Uint8ClampedArray for where the application expects a Uint8Array, or Uint8ClampedArray for where the application expects a Uint8Array, or
vice versa, potentially leading to very different (and unexpected) vice versa, potentially leading to very different (and unexpected)
processing semantics of the in-memory data structures constructed. processing semantics of the in-memory data structures constructed.
Applications that could be affected by this therefore will need to be Applications that could be affected by this therefore will need to be
careful about making this distinction in their input validation. careful about making this distinction in their input validation.
8. References 8. References
8.1. Normative References 8.1. Normative References
[C] "Information technology -- Programming languages -- C",
ISO/IEC 9899, 2018.
[Cplusplus]
"Programming languages -- C++", ISO/IEC 14882, 2017.
[IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE
Std 754-2008. Std 754-2008.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
skipping to change at page 14, line 31 skipping to change at page 14, line 37
[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>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>. June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[TypedArrayES6]
"22.2 TypedArray Objects", in: ECMA-262 6th Edition, The
ECMAScript 2015 Language Specification, June 2015,
<http://www.ecma-international.org/ecma-262/6.0/#sec-
typedarray-objects>.
8.2. Informative References 8.2. Informative References
[ArrayBuffer] [ArrayBuffer]
Mozilla Developer Network, "JavaScript typed arrays", Mozilla Developer Network, "JavaScript typed arrays",
2013, <https://developer.mozilla.org/en- 2013, <https://developer.mozilla.org/en-
US/docs/Web/JavaScript/Typed_arrays>. US/docs/Web/JavaScript/Typed_arrays>.
[RowColMajor]
Wikipedia, "Row- and column-major order", September 2019,
<https://en.wikipedia.org/w/index.php?title=Row-
_and_column-major_order&oldid=917905325>.
[TypedArray] [TypedArray]
Vukicevic, V. and K. Russell, "Typed Array Specification", Vukicevic, V. and K. Russell, "Typed Array Specification",
February 2011. February 2011,
<https://web.archive.org/web/20110207024413/
[TypedArrayES6] http://www.khronos.org/registry/typedarray/specs/latest/>.
"22.2 TypedArray Objects", in: ECMA-262 6th Edition, The
ECMAScript 2015 Language Specification, June 2015,
<http://www.ecma-international.org/
ecma-262/6.0/#sec-typedarray-objects>.
Contributors Contributors
The initial draft for this specification was written by Johnathan The initial draft for this specification was written by Johnathan
Roatch (roatch@gmail.com). Many thanks for getting this ball Roatch (roatch@gmail.com). Many thanks for getting this ball
rolling. rolling.
Glenn Engel suggested the tags for multi-dimensional arrays and Glenn Engel suggested the tags for multi-dimensional arrays and
homogeneous arrays. homogeneous arrays.
Acknowledgements Acknowledgements
Jim Schaad provided helpful comments and reminded us that column- Jim Schaad provided helpful comments and reminded us that column-
major order still is in use. Jeffrey Yaskin helped improve the major order still is in use. Jeffrey Yaskin helped improve the
definition of homogeneous arrays. IANA helped correct an error in a definition of homogeneous arrays. IANA helped correct an error in a
previous version. previous version. Francesca Palombini acted as a shepherd, and
Alexey Melnikov as responsible area director. Elwyn Davies as Gen-
ART reviewer and IESG members Martin Vigoureux, Adam Roach, Roman
Danyliw, and Benjamin Kaduk helped finding further improvements of
the text; thanks also to the other reviewers.
Author's Address Author's Address
Carsten Bormann (editor) Carsten Bormann (editor)
Universitaet Bremen TZI Universitaet Bremen TZI
Postfach 330440 Postfach 330440
Bremen D-28359 Bremen D-28359
Germany Germany
Phone: +49-421-218-63921 Phone: +49-421-218-63921
 End of changes. 19 change blocks. 
27 lines changed or deleted 50 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/