idnits 2.17.1 draft-bormann-cbor-sequence-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 23, 2019) is 1769 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Standards Track June 23, 2019 5 Expires: December 25, 2019 7 Concise Binary Object Representation (CBOR) Sequences 8 draft-bormann-cbor-sequence-01 10 Abstract 12 This document describes the Concise Binary Object Representation 13 (CBOR) Sequence format and associated media type "application/cbor- 14 seq". A CBOR Sequence consists of any number of encoded CBOR data 15 items, simply concatenated in sequence. 17 Structured syntax suffixes for media types allow other media types to 18 build on them and make it explicit that they are built on an existing 19 media type as their foundation. This specification defines and 20 registers "+cbor-seq" as a structured syntax suffix for CBOR 21 Sequences. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on December 25, 2019. 40 Copyright Notice 42 Copyright (c) 2019 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Conventions Used in This Document . . . . . . . . . . . . 3 59 2. CBOR Sequence Format . . . . . . . . . . . . . . . . . . . . 3 60 3. The "+cbor-seq" Structured Syntax Suffix . . . . . . . . . . 4 61 4. Practical Considerations . . . . . . . . . . . . . . . . . . 4 62 4.1. Specifying CBOR Sequences in CDDL . . . . . . . . . . . . 4 63 4.2. Optimizing CBOR Sequences for Skipping Elements . . . . . 5 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 5 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 66 6.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 5 67 6.2. CoAP Content-Format Registration . . . . . . . . . . . . 6 68 6.3. Structured Syntax Suffix . . . . . . . . . . . . . . . . 7 69 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 71 7.2. Informative References . . . . . . . . . . . . . . . . . 9 72 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 75 1. Introduction 77 The Concise Binary Object Representation (CBOR) [RFC7049] can be used 78 for serialization of data in the JSON [RFC8259] data model or in its 79 own, somewhat expanded data model. When serializing a sequence of 80 such values, it is sometimes convenient to have a format where these 81 sequences can simply be concatenated to obtain a serialization of the 82 concatenated sequence of values, or to encode a sequence of values 83 that might grow at the end by just appending further CBOR data items. 85 This document describes the concept and format of "CBOR Sequences", 86 which are composed of zero or more encoded CBOR data items. CBOR 87 Sequences can be consumed (and produced) incrementally without 88 requiring a streaming CBOR parser that is able to deliver 89 substructures of a data item incrementally (or a streaming encoder 90 able to encode from substructures incrementally). 92 This document defines and registers the "application/cbor-seq" media 93 type in the media type registry. Media type structured syntax 94 suffixes [RFC6838] were introduced as a way for a media type to 95 signal that it is based on another media type as its foundation. 96 CBOR [RFC7049] defines the "+cbor" structured syntax suffix. This 97 document defines and registers the "+cbor-seq" structured syntax 98 suffix in the "Structured Syntax Suffix Registry". 100 1.1. Conventions Used in This Document 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in 105 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 In this specification, the term "byte" is used in its now-customary 109 sense as a synonym for "octet". 111 2. CBOR Sequence Format 113 Formally, a CBOR Sequence is a sequence of bytes that is recursively 114 defined as either 116 o an empty (zero-length) sequence of bytes 118 o the sequence of bytes making up an encoded CBOR data item 119 [RFC7049], followed by a CBOR Sequence. 121 In short, concatenating zero or more encoded CBOR data items 122 generates a CBOR Sequence. 124 There is no end of sequence indicator. (If one is desired, CBOR- 125 encoding an array of the CBOR data model values being encoded -- 126 employing either a definite or an indefinite length encoding -- as a 127 single CBOR data item may actually be the more appropriate 128 representation.) 130 This specification makes use of the fact that CBOR data items are 131 self-delimiting (there is no delimiter used between items, as there 132 is in JSON Text Sequences [RFC7464]). 134 Decoding a CBOR Sequence works as follows: 136 o If the CBOR Sequence is an empty sequence of bytes, the result is 137 an empty sequence of CBOR data model values. 139 o Otherwise, decode a single CBOR data item from the bytes of the 140 CBOR sequence, and insert the resulting CBOR data model value at 141 the start of the result of decoding the rest of the bytes as a 142 CBOR sequence. (A streaming decoder would therefore simply 143 deliver a sequence of CBOR data model values, each of which as 144 soon as the bytes making it up are available.) 146 This means that if any data item in the sequence is not well-formed, 147 it is not possible to reliably decode the rest of the sequence. (An 148 implementation may be able to recover from some errors in a sequence 149 of bytes that is almost, but not entirely a well-formed encoded CBOR 150 data item. Handling malformed data is outside the scope of this 151 specification.) 153 This also means that the CBOR Sequence format can reliably detect 154 truncation of the bytes making up the last CBOR data item in the 155 sequence, but not entirely missing CBOR data items at the end. A 156 CBOR Sequence decoder that is used for consuming streaming CBOR 157 Sequence data may simply pause for more data (e.g., by suspending and 158 later resuming decoding) in case a truncated final item is being 159 received. 161 3. The "+cbor-seq" Structured Syntax Suffix 163 The use case for the "+cbor-seq" structured syntax suffix is the same 164 as for "+cbor": It SHOULD be used by a media type when parsing the 165 bytes of the media type object as a CBOR Sequence leads to a 166 meaningful result that is at least sometimes not just a single CBOR 167 data item. (Without the qualification at the end, this sentence is 168 trivially true for any +cbor media type, which of course should 169 continue to use the "+cbor" structured syntax suffix.) 171 Applications encountering a "+cbor-seq" media type can then either 172 simply use generic processing if all they need is a generic view of 173 the CBOR Sequence, or they can use generic CBOR Sequence tools for 174 initial parsing and then implement their own specific processing on 175 top of that generic parsing tool. 177 4. Practical Considerations 179 4.1. Specifying CBOR Sequences in CDDL 181 In CDDL [RFC8610], CBOR sequences are already supported as contents 182 of byte strings using the ".cborseq" control operator (Section 3.8.4 183 of [RFC8610]), by employing an array as the controller type: 185 my-embedded-cbor-seq = bytes .cborseq my-array 186 my-array = [* my-element] 187 my-element = my-foo / my-bar 189 CDDL currently does not provide for unadorned CBOR sequences as a 190 top-level subject of a specification. For now, the suggestion is to 191 use an array, as for the ".cborseq" control operator, for the top- 192 level rule and add English text that explains that the specification 193 is really about a CBOR sequence with the elements of the array: 195 ; This defines an array, the elements of which are to be used 196 ; in a CBOR sequence: 197 my-sequence = [* my-element] 198 my-element = my-foo / my-bar 200 (Future versions of CDDL may provide a notation for top-level CBOR 201 sequences, e.g. by using a group as the top-level rule in a CDDL 202 specification.) 204 4.2. Optimizing CBOR Sequences for Skipping Elements 206 In certain applications, being able to efficiently skip an element 207 without the need for decoding its substructure, or efficiently 208 fanning out elements to multi-threaded decoding processes, is of the 209 utmost importance. For these applications, byte strings (which carry 210 length information in bytes) containing embedded CBOR can be used as 211 the elements of a CBOR sequence: 213 ; This defines an array of CBOR byte strings, the elements of which 214 ; are to be used in a CBOR sequence: 215 my-sequence = [* my-element] 216 my-element = bytes .cbor my-element-structure 217 my-element-structure = my-foo / my-bar 219 Within limits, this may also enable recovering from elements that 220 internally are not well-formed -- the limitation is that the sequence 221 of byte strings does need to be well-formed as such. 223 5. Security Considerations 225 The security considerations of CBOR [RFC7049] apply. This format 226 provides no cryptographic integrity protection of any kind, but can 227 be combined with security specifications such as COSE [RFC8152] to do 228 so. 230 As usual, decoders must operate on input that is assumed to be 231 untrusted. This means that decoders must fail gracefully in the face 232 of malicious inputs. 234 6. IANA Considerations 236 6.1. Media Type 238 Media types are registered in the media types registry 239 [IANA.media-types]. IANA is requested to register the MIME media 240 type for CBOR Sequence, application/cbor-seq, as follows: 242 Type name: application 243 Subtype name: cbor-seq 245 Required parameters: N/A 247 Optional parameters: N/A 249 Encoding considerations: binary 251 Security considerations: See RFCthis, Section 5. 253 Interoperability considerations: Described herein. 255 Published specification: RFCthis. 257 Applications that use this media type: Data serialization and 258 deserialization. 260 Fragment identifier considerations: N/A 262 Additional information: 264 o Deprecated alias names for this type: N/A 266 o Magic number(s): N/A 268 o File extension(s): N/A 270 o Macintosh file type code(s): N/A 272 Person & email address to contact for further information: 273 cbor@ietf.org 275 Intended usage: COMMON 277 Author: Carsten Bormann (cabo@tzi.org) 279 Change controller: IETF 281 6.2. CoAP Content-Format Registration 283 IANA is requested to assign a CoAP Content-Format ID for the media 284 type "application/cbor-seq", in the CoAP Content-Formats subregistry 285 of the core-parameter registry [IANA.core-parameters], from the 286 "Expert Review" (0-255) range. The assigned ID is shown in Table 1. 288 +----------------------+----------+-------+-----------+ 289 | Media type | Encoding | ID | Reference | 290 +----------------------+----------+-------+-----------+ 291 | application/cbor-seq | - | TBD63 | RFCthis | 292 +----------------------+----------+-------+-----------+ 294 Table 1: CoAP Content-Format ID 296 RFC editor: Please replace TBD63 by the number actually assigned and 297 delete this paragraph. 299 6.3. Structured Syntax Suffix 301 Structured Syntax Suffixes are registered within the "Structured 302 Syntax Suffix Registry" maintained at 303 [IANA.media-type-structured-suffix]. IANA is requested to register 304 the "+cbor-seq" structured syntax suffix in accordance with 305 [RFC6838], as follows: 307 Name: CBOR Sequence 309 +suffix: +cbor-seq 311 References: RFCthis 313 Encoding considerations: binary 315 Fragment identifier considerations: The syntax and semantics of 316 fragment identifiers specified for +cbor-seq SHOULD be as 317 specified for "application/cbor-seq". (At publication of this 318 document, there is no fragment identification syntax defined for 319 "application/cbor-seq".) 321 The syntax and semantics for fragment identifiers for a 322 specific "xxx/yyy+cbor-seq" SHOULD be processed as follows: 324 For cases defined in +cbor-seq, where the fragment 325 identifier resolves per the +cbor-seq rules, then process as 326 specified in +cbor-seq. 328 For cases defined in +cbor-seq, where the fragment 329 identifier does not resolve per the +cbor-seq rules, then 330 process as specified in "xxx/yyy+cbor-seq". 332 For cases not defined in +cbor-seq, then process as 333 specified in "xxx/yyy+cbor-seq". 335 Interoperability considerations: n/a 337 Security considerations: See RFCthis, Section 5 339 Contact: CBOR WG mailing list (cbor@ietf.org), or any IESG- 340 designated successor. 342 Author/Change controller: IETF 344 7. References 346 7.1. Normative References 348 [IANA.core-parameters] 349 IANA, "Constrained RESTful Environments (CoRE) 350 Parameters", 351 . 353 [IANA.media-type-structured-suffix] 354 IANA, "Structured Syntax Suffix Registry", 355 . 358 [IANA.media-types] 359 IANA, "Media Types", 360 . 362 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 363 Requirement Levels", BCP 14, RFC 2119, 364 DOI 10.17487/RFC2119, March 1997, 365 . 367 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 368 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 369 October 2013, . 371 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 372 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 373 May 2017, . 375 7.2. Informative References 377 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 378 Specifications and Registration Procedures", BCP 13, 379 RFC 6838, DOI 10.17487/RFC6838, January 2013, 380 . 382 [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text 383 Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, 384 . 386 [RFC8091] Wilde, E., "A Media Type Structured Syntax Suffix for JSON 387 Text Sequences", RFC 8091, DOI 10.17487/RFC8091, February 388 2017, . 390 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 391 RFC 8152, DOI 10.17487/RFC8152, July 2017, 392 . 394 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 395 Interchange Format", STD 90, RFC 8259, 396 DOI 10.17487/RFC8259, December 2017, 397 . 399 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 400 Definition Language (CDDL): A Notational Convention to 401 Express Concise Binary Object Representation (CBOR) and 402 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 403 June 2019, . 405 Acknowledgements 407 This draft has mostly been generated from [RFC7464] by Nico Williams 408 and [RFC8091] by Erik Wilde, which do a similar, but slightly more 409 complicated exercise for JSON [RFC8259]. Laurence Lundblade raised 410 an issue on the CBOR mailing list that pointed out the need for this 411 document. 413 Author's Address 414 Carsten Bormann 415 Universitaet Bremen TZI 416 Postfach 330440 417 Bremen D-28359 418 Germany 420 Phone: +49-421-218-63921 421 Email: cabo@tzi.org