draft-ietf-cbor-array-tags-03.txt   draft-ietf-cbor-array-tags-04.txt 
Network Working Group J. Roatch Network Working Group C. Bormann, Ed.
Internet-Draft Internet-Draft Universitaet Bremen TZI
Intended status: Informational C. Bormann Intended status: Informational May 22, 2019
Expires: September 6, 2019 Universitaet Bremen TZI Expires: November 23, 2019
March 05, 2019
Concise Binary Object Representation (CBOR) Tags for Typed Arrays Concise Binary Object Representation (CBOR) Tags for Typed Arrays
draft-ietf-cbor-array-tags-03 draft-ietf-cbor-array-tags-04
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 40 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 September 6, 2019. This Internet-Draft will expire on November 23, 2019.
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 19 skipping to change at page 2, line 18
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 . . . . . . . . . . . . . . . . . . . . 3
3. Additional Array Tags . . . . . . . . . . . . . . . . . . . . 5 3. Additional Array Tags . . . . . . . . . . . . . . . . . . . . 5
3.1. Multi-dimensional Array . . . . . . . . . . . . . . . . . 5 3.1. Multi-dimensional Array . . . . . . . . . . . . . . . . . 5
3.2. Homogeneous Array . . . . . . . . . . . . . . . . . . . . 7 3.1.1. Row-major Order . . . . . . . . . . . . . . . . . . . 6
4. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.2. Column-Major order . . . . . . . . . . . . . . . . . 7
5. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. Homogeneous Array . . . . . . . . . . . . . . . . . . . . 8
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 4. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 9
7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 5. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 10
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
8.1. Normative References . . . . . . . . . . . . . . . . . . 13 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13
8.2. Informative References . . . . . . . . . . . . . . . . . 13 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
8.1. Normative References . . . . . . . . . . . . . . . . . . 14
8.2. Informative References . . . . . . . . . . . . . . . . . 14
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 14 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 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 have 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. conversion of each number in the array. This also can save space
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
considerable freedom in choosing variants, e.g., with respect to
endianness, embedded type (signed vs. unsigned), and number of bits
per element, or whether a tag defined in this specification is used
at all instead of more basic CBOR. In contrast to representation
variants of single CBOR numbers, there is no representation that
could be identified as "preferred". If deterministic encoding is
desired in a CBOR-based protocol making use of these tags, the
protocol has to define which of the encoding variants are used in
which case.
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
skipping to change at page 4, line 32 skipping to change at page 4, line 51
| 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 unsigned integer or float, 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 f and ll are the lsb of each nibble (4bit) in the byte.) (Notice that 0f and ll are the two least significant bits,
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 inversely to the previous formula from the length of the byte string
in bytes: "bytelength >> (f + ll)". in bytes: "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
big endian variant is used. The little endian variant of sint8 MUST big endian variant is used. The Tag that would signify the little
NOT be used, its tag is marked as reserved. As a special case, the endian variant of sint8 MUST NOT be used, its tag number is marked as
tag number that would have been the little endian variant of uint8 is reserved. As a special case, the Tag that would signify the little
used to signify that the numbers in the array are using clamped endian variant of uint8 is instead assigned to signify that the
conversion from integers, as described in more detail in Section 7.1 numbers in the array are using clamped conversion from integers, as
of [TypedArrayUpdate]. described in more detail in Section 7.1.11 ("ToUint8Clamp") of the
ES6 JavaScript specification [TypedArrayES6]; the assumption here is
that a program-internal representation of this array after decoding
would be marked this way for further processing, providing
"roundtripping" of JavaScript typed arrays through CBOR.
IEEE 754 binary floating numbers are always signed. Therefore, for
the float variants ("f" == 1), there is no need to distinguish
between signed and unsigned variants; the "s" bit is always zero.
3. Additional Array Tags 3. Additional Array Tags
This specification defines three additional array tags. The Multi- This specification defines three additional array tags. The Multi-
dimensional Array tags can be combined with classical CBOR arrays as dimensional Array tags can be combined with classical CBOR arrays as
well as with Typed Arrays in order to build multi-dimensional arrays well as with Typed Arrays in order to build multi-dimensional arrays
with constant numbers of elements in the sub-arrays. The Homogeneous with constant numbers of elements in the sub-arrays. The Homogeneous
Array tag can be used to facilitate the ingestion of homogeneous Array tag can be used to facilitate the ingestion of homogeneous
classical CBOR arrays, providing performance advantages even when a classical CBOR arrays, providing performance advantages even when a
Typed Array does not apply. Typed Array does not apply.
3.1. Multi-dimensional Array 3.1. Multi-dimensional Array
Tag: 40
Data Item: array (major type 4) of two arrays, one array (major type
4) of dimensions, and one array (major type 4, a Typed Array, or a
Homogeneous Array) of elements
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. Data in the Typed Array byte string consists of of the Typed Array.
consecutive values where the last dimension is considered contiguous
(row-major order). Two tags are defined by this document, one for elements arranged in
row-major order, and one for column-major order.
3.1.1. Row-major Order
Tag: 40
Data Item: array (major type 4) of two arrays, one array (major type
4) of dimensions, which are unsigned integers distinct from zero,
and one array (either a CBOR array of major type 4, or a Typed
Array, or a Homogeneous Array) of elements
Data in the second array consists of consecutive values where the
last dimension is considered contiguous (row-major order).
Figure 1 shows a declaration of a two-dimensional array in the C Figure 1 shows a declaration of a two-dimensional array in the C
language, a representation of that in CBOR using both a language, a representation of that in CBOR using both a
multidimensional array tag and a typed array tag. multidimensional array tag and a typed array tag.
uint16_t a[2][3] = { uint16_t a[2][3] = {
{2, 4, 8}, /* row 0 */ {2, 4, 8}, /* row 0 */
{4, 16, 256}, {4, 16, 256},
}; };
skipping to change at page 6, line 46 skipping to change at page 7, line 20
86 # array(6) 86 # array(6)
02 # unsigned(2) 02 # unsigned(2)
04 # unsigned(4) 04 # unsigned(4)
08 # unsigned(8) 08 # unsigned(8)
04 # unsigned(4) 04 # unsigned(4)
10 # unsigned(16) 10 # unsigned(16)
19 0100 # unsigned(256) 19 0100 # unsigned(256)
Figure 2: Multi-dimensional array using basic CBOR array Figure 2: Multi-dimensional array using basic CBOR array
Tag: 1040 3.1.2. Column-Major order
Data Item: as with tag 40 The multidimensional arrays specified in the previous sub-subsection
are in "row major" order, which is the preferred order for the
purposes of this specification. An analogous representation that
uses "column major" order arrays is provided in this subsection under
the tag 1040, as illustrated in Figure 3.
Note that above arrays are in "row major" order, which is the Tag: 1040
preferred order for the purposes of this specification. An analogous
representation that uses "column major" order arrays is provided Data Item: as with tag 40, except that the data in the second array
under the tag 1040, as illustrated in Figure 3. consists of consecutive values where the first dimension is
considered contiguous (column-major order).
<Tag 1040> # multi-dimensional array tag, column major order <Tag 1040> # multi-dimensional array tag, column major order
82 # array(2) 82 # array(2)
82 # array(2) 82 # array(2)
02 # unsigned(2) 1st Dimension 02 # unsigned(2) 1st Dimension
03 # unsigned(3) 2nd Dimension 03 # unsigned(3) 2nd Dimension
86 # array(6) 86 # array(6)
02 # unsigned(2) 02 # unsigned(2)
04 # unsigned(4) 04 # unsigned(4)
04 # unsigned(4) 04 # unsigned(4)
skipping to change at page 7, line 29 skipping to change at page 8, line 11
Figure 3: Multi-dimensional array using basic CBOR array, column Figure 3: Multi-dimensional array using basic CBOR array, column
major order major order
3.2. Homogeneous Array 3.2. Homogeneous Array
Tag: 41 Tag: 41
Data Item: array (major type 4) Data Item: array (major type 4)
This tag provides a hint to decoders that the array tagged by it has This tag provides a hint to decoders that the CBOR array (major type
elements that are all of the same application type. The element type 4, a one-dimensional array) tagged by it has elements that are all of
of the array is thus determined by the application type of the first the same application type. The element type of the array is thus
array element. This can be used by implementations in strongly typed determined by the application type of the first array element. This
languages while decoding to create native homogeneous arrays of can be used by implementations in strongly typed languages while
specific types instead of ordered lists. decoding to create native homogeneous arrays of specific types
instead of ordered lists.
Which CBOR data items constitute elements of the same application Which CBOR data items constitute elements of the same application
type is specific to the application. However, type systems of type is specific to the application. However, type systems of
programming languages have enough commonality that an application programming languages have enough commonality that an application
should be able to create portable homogeneous arrays. should be able to create portable homogeneous arrays.
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. and CBOR.
bool boolArray[2] = { true, false }; bool boolArray[2] = { true, false };
skipping to change at page 12, line 8 skipping to change at page 13, line 8
Table 3: Values for Tags Table 3: Values for Tags
*) 40 or 1040 data item: second element of outer array in data item *) 40 or 1040 data item: second element of outer array in data item
is native CBOR array (major type 4) or Typed Array (one of Tag is native CBOR array (major type 4) or Typed Array (one of Tag
64..87) 64..87)
7. Security Considerations 7. Security Considerations
The security considerations of RFC 7049 apply; special attention is The security considerations of RFC 7049 apply; special attention is
drawn to the second paragraph of Section 8 of RFC 7049. The tags drawn to the second paragraph of Section 8 of RFC 7049.
introduced here are not expected to raise security considerations
beyond those. The Tag for homogeneous arrays makes a promise about its tagged data
item that a maliciously constructed CBOR input can then choose to
ignore. As always, the decoder therefore has to ensure that it is
not driven into an undefined state by array elements that do not
fulfill the promise and that it does continue to fulfill its API
contract in this case as well.
8. References 8. References
8.1. Normative References 8.1. Normative References
[I-D.ietf-cbor-cddl] [I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to definition language (CDDL): a notational convention to
express CBOR and JSON data structures", draft-ietf-cbor- express CBOR and JSON data structures", draft-ietf-cbor-
cddl-07 (work in progress), February 2019. cddl-08 (work in progress), March 2019.
[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,
October 2013, <https://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
skipping to change at page 13, line 37 skipping to change at page 14, line 37
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>.
[TypedArray] [TypedArray]
Vukicevic, V. and K. Russell, "Typed Array Specification", Vukicevic, V. and K. Russell, "Typed Array Specification",
February 2011, February 2011.
<https://www.khronos.org/registry/typedarray/specs/1.0/>.
[TypedArrayES6] [TypedArrayES6]
"22.2 TypedArray Objects", in: ECMA-262 6th Edition, The "22.2 TypedArray Objects", in: ECMA-262 6th Edition, The
ECMAScript 2015 Language Specification, June 2015, ECMAScript 2015 Language Specification, June 2015,
<http://www.ecma-international.org/ <http://www.ecma-international.org/
ecma-262/6.0/#sec-typedarray-objects>. ecma-262/6.0/#sec-typedarray-objects>.
[TypedArrayUpdate]
Herman, D. and K. Russell, "Typed Array Specification",
July 2013,
<https://www.khronos.org/registry/typedarray/specs/
latest/>.
Contributors Contributors
The initial draft for this specification was written by Johnathan
Roatch (roatch@gmail.com). Many thanks for getting this ball
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 reminded us that column-major order still is in use. IANA Jim Schaad reminded us that column-major order still is in use. IANA
helped correct an error in a previous version. helped correct an error in a previous version.
Authors' Addresses Author's Address
Johnathan Roatch
Email: jroatch@gmail.com
Carsten Bormann 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
Email: cabo@tzi.org Email: cabo@tzi.org
 End of changes. 22 change blocks. 
65 lines changed or deleted 97 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/