idnits 2.17.1 draft-ietf-cbor-sequence-02.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 (September 25, 2019) is 1673 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) -- Looks like a reference, but probably isn't: '1' on line 224 -- Looks like a reference, but probably isn't: '2' on line 224 -- Looks like a reference, but probably isn't: '3' on line 224 ** 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 (==), 5 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 September 25, 2019 5 Expires: March 28, 2020 7 Concise Binary Object Representation (CBOR) Sequences 8 draft-ietf-cbor-sequence-02 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 March 28, 2020. 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. Diagnostic Notation . . . . . . . . . . . . . . . . . . . 5 64 4.3. Optimizing CBOR Sequences for Skipping Elements . . . . . 5 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 66 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 67 6.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 6 68 6.2. CoAP Content-Format Registration . . . . . . . . . . . . 7 69 6.3. Structured Syntax Suffix . . . . . . . . . . . . . . . . 7 70 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 72 7.2. Informative References . . . . . . . . . . . . . . . . . 9 73 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 10 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 76 1. Introduction 78 The Concise Binary Object Representation (CBOR) [RFC7049] can be used 79 for serialization of data in the JSON [RFC8259] data model or in its 80 own, somewhat expanded data model. When serializing a sequence of 81 such values, it is sometimes convenient to have a format where these 82 sequences can simply be concatenated to obtain a serialization of the 83 concatenated sequence of values, or to encode a sequence of values 84 that might grow at the end by just appending further CBOR data items. 86 This document describes the concept and format of "CBOR Sequences", 87 which are composed of zero or more encoded CBOR data items. CBOR 88 Sequences can be consumed (and produced) incrementally without 89 requiring a streaming CBOR parser that is able to deliver 90 substructures of a data item incrementally (or a streaming encoder 91 able to encode from substructures incrementally). 93 This document defines and registers the "application/cbor-seq" media 94 type in the media type registry, along with a CoAP Content-Format 95 identifier. Media type structured syntax suffixes [RFC6838] were 96 introduced as a way for a media type to signal that it is based on 97 another media type as its foundation. CBOR [RFC7049] defines the 98 "+cbor" structured syntax suffix. This document defines and 99 registers the "+cbor-seq" structured syntax suffix in the "Structured 100 Syntax Suffix Registry". 102 1.1. Conventions Used in This Document 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 106 "OPTIONAL" in this document are to be interpreted as described in 107 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 108 capitals, as shown here. 110 In this specification, the term "byte" is used in its now-customary 111 sense as a synonym for "octet". 113 2. CBOR Sequence Format 115 Formally, a CBOR Sequence is a sequence of bytes that is recursively 116 defined as either 118 o an empty (zero-length) sequence of bytes 120 o the sequence of bytes making up an encoded CBOR data item 121 [RFC7049], followed by a CBOR Sequence. 123 In short, concatenating zero or more encoded CBOR data items 124 generates a CBOR Sequence. (Consequently, concatenating zero or more 125 CBOR Sequences also results in a CBOR Sequence.) 127 There is no end of sequence indicator. (If one is desired, CBOR- 128 encoding an array of the CBOR data model values being encoded -- 129 employing either a definite or an indefinite length encoding -- as a 130 single CBOR data item may actually be the more appropriate 131 representation.) 133 CBOR Sequences, unlike JSON Text Sequences [RFC7464], do not use a 134 marker between items. This is possible because CBOR encoded data 135 items are self-delimiting and the end can always be calculated. 136 (Note that, while the early object/array-only form of JSON was self- 137 delimiting as well, this stopped being the case when simple values 138 such as single numbers were made valid JSON documents.) 140 Decoding a CBOR Sequence works as follows: 142 o If the CBOR Sequence is an empty sequence of bytes, the result is 143 an empty sequence of CBOR data model values. 145 o Otherwise, decode a single CBOR data item from the bytes of the 146 CBOR sequence, and insert the resulting CBOR data model value at 147 the start of the result of repeating this decoding process 148 recursively with the remaining bytes. (A streaming decoder would 149 therefore simply deliver zero or more CBOR data model values, each 150 as soon as the bytes making it up are available.) 152 This means that if any data item in the sequence is not well-formed, 153 it is not possible to reliably decode the rest of the sequence. (An 154 implementation may be able to recover from some errors in a sequence 155 of bytes that is almost, but not entirely a well-formed encoded CBOR 156 data item. Handling malformed data is outside the scope of this 157 specification.) 159 This also means that the CBOR Sequence format can reliably detect 160 truncation of the bytes making up the last CBOR data item in the 161 sequence, but not entirely missing CBOR data items at the end. A 162 CBOR Sequence decoder that is used for consuming streaming CBOR 163 Sequence data may simply pause for more data (e.g., by suspending and 164 later resuming decoding) in case a truncated final item is being 165 received. 167 3. The "+cbor-seq" Structured Syntax Suffix 169 The use case for the "+cbor-seq" structured syntax suffix is 170 analogous to that for "+cbor": It SHOULD be used by a media type when 171 parsing the bytes of the media type object as a CBOR Sequence leads 172 to a meaningful result that is at least sometimes not just a single 173 CBOR data item. (Without the qualification at the end, this sentence 174 is trivially true for any +cbor media type, which of course should 175 continue to use the "+cbor" structured syntax suffix.) 177 Applications encountering a "+cbor-seq" media type can then either 178 simply use generic processing if all they need is a generic view of 179 the CBOR Sequence, or they can use generic CBOR Sequence tools for 180 initial parsing and then implement their own specific processing on 181 top of that generic parsing tool. 183 4. Practical Considerations 185 4.1. Specifying CBOR Sequences in CDDL 187 In CDDL [RFC8610], CBOR sequences are already supported as contents 188 of byte strings using the ".cborseq" control operator (Section 3.8.4 189 of [RFC8610]), by employing an array as the controller type: 191 my-embedded-cbor-seq = bytes .cborseq my-array 192 my-array = [* my-element] 193 my-element = my-foo / my-bar 195 CDDL currently does not provide for unadorned CBOR sequences as a 196 top-level subject of a specification. For now, the suggestion is to 197 use an array, as for the ".cborseq" control operator, for the top- 198 level rule and add English text that explains that the specification 199 is really about a CBOR sequence with the elements of the array: 201 ; This defines an array, the elements of which are to be used 202 ; in a CBOR sequence: 203 my-sequence = [* my-element] 204 my-element = my-foo / my-bar 206 (Future versions of CDDL may provide a notation for top-level CBOR 207 sequences, e.g. by using a group as the top-level rule in a CDDL 208 specification.) 210 4.2. Diagnostic Notation 212 CBOR diagnostic notation (see Section 6 of [RFC7049]) or extended 213 diagnostic notation (Appendix G of [RFC8610]) also does not provide 214 for unadorned CBOR Sequences at this time (the latter does provide 215 for CBOR Sequences embedded in a byte string in Appendix G.3 of 216 [RFC8610]). 218 In a similar spirit to the recommendation for CDDL above, this 219 specification recommends enclosing the CBOR data items in an array. 220 In a more informal setting, where the boundaries within which the 221 notation is used are obvious, it is also possible to leave off the 222 outer brackets for this array, as shown in these two examples: 224 [1, 2, 3] 226 1, 2, 3 228 Note that it is somewhat difficult to discuss zero-length CBOR 229 Sequences in the latter form. 231 4.3. Optimizing CBOR Sequences for Skipping Elements 233 In certain applications, being able to efficiently skip an element 234 without the need for decoding its substructure, or efficiently 235 fanning out elements to multi-threaded decoding processes, is of the 236 utmost importance. For these applications, byte strings (which carry 237 length information in bytes) containing embedded CBOR can be used as 238 the elements of a CBOR sequence: 240 ; This defines an array of CBOR byte strings, the elements of which 241 ; are to be used in a CBOR sequence: 242 my-sequence = [* my-element] 243 my-element = bytes .cbor my-element-structure 244 my-element-structure = my-foo / my-bar 246 Within limits, this may also enable recovering from elements that 247 internally are not well-formed -- the limitation is that the sequence 248 of byte strings does need to be well-formed as such. 250 5. Security Considerations 252 The security considerations of CBOR [RFC7049] apply. This format 253 provides no cryptographic integrity protection of any kind, but can 254 be combined with security specifications such as COSE [RFC8152] to do 255 so. (COSE protections can be applied to an entire CBOR sequence or 256 to each of the elements of the sequence independently; in the latter 257 case, additional effort may be required if there is a need to protect 258 the relationship of the elements in the sequence.) 260 As usual, decoders must operate on input that is assumed to be 261 untrusted. This means that decoders MUST fail gracefully in the face 262 of malicious inputs. 264 6. IANA Considerations 266 6.1. Media Type 268 Media types are registered in the media types registry 269 [IANA.media-types]. IANA is requested to register the MIME media 270 type for CBOR Sequence, application/cbor-seq, as follows: 272 Type name: application 274 Subtype name: cbor-seq 276 Required parameters: N/A 278 Optional parameters: N/A 280 Encoding considerations: binary 282 Security considerations: See RFCthis, Section 5. 284 Interoperability considerations: Described herein. 286 Published specification: RFCthis. 288 Applications that use this media type: Data serialization and 289 deserialization. 291 Fragment identifier considerations: N/A 293 Additional information: 295 o Deprecated alias names for this type: N/A 297 o Magic number(s): N/A 299 o File extension(s): N/A 301 o Macintosh file type code(s): N/A 303 Person & email address to contact for further information: 304 cbor@ietf.org 306 Intended usage: COMMON 308 Author: Carsten Bormann (cabo@tzi.org) 310 Change controller: IETF 312 6.2. CoAP Content-Format Registration 314 IANA is requested to assign a CoAP Content-Format ID for the media 315 type "application/cbor-seq", in the CoAP Content-Formats subregistry 316 of the core-parameter registry [IANA.core-parameters], from the 317 "Expert Review" (0-255) range. The assigned ID is shown in Table 1. 319 +----------------------+----------+-------+-----------+ 320 | Media type | Encoding | ID | Reference | 321 +----------------------+----------+-------+-----------+ 322 | application/cbor-seq | - | TBD63 | RFCthis | 323 +----------------------+----------+-------+-----------+ 325 Table 1: CoAP Content-Format ID 327 RFC editor: Please replace TBD63 by the number actually assigned and 328 delete this paragraph. 330 6.3. Structured Syntax Suffix 332 Structured Syntax Suffixes are registered within the "Structured 333 Syntax Suffix Registry" maintained at 334 [IANA.media-type-structured-suffix]. IANA is requested to register 335 the "+cbor-seq" structured syntax suffix in accordance with 336 [RFC6838], as follows: 338 Name: CBOR Sequence 340 +suffix: +cbor-seq 342 References: RFCthis 344 Encoding considerations: binary 346 Fragment identifier considerations: The syntax and semantics of 347 fragment identifiers specified for +cbor-seq SHOULD be as 348 specified for "application/cbor-seq". (At publication of this 349 document, there is no fragment identification syntax defined for 350 "application/cbor-seq".) 352 The syntax and semantics for fragment identifiers for a 353 specific "xxx/yyy+cbor-seq" SHOULD be processed as follows: 355 For cases defined in +cbor-seq, where the fragment 356 identifier resolves per the +cbor-seq rules, then process as 357 specified in +cbor-seq. 359 For cases defined in +cbor-seq, where the fragment 360 identifier does not resolve per the +cbor-seq rules, then 361 process as specified in "xxx/yyy+cbor-seq". 363 For cases not defined in +cbor-seq, then process as 364 specified in "xxx/yyy+cbor-seq". 366 Interoperability considerations: n/a 368 Security considerations: See RFCthis, Section 5 369 Contact: CBOR WG mailing list (cbor@ietf.org), or any IESG- 370 designated successor. 372 Author/Change controller: IETF 374 7. References 376 7.1. Normative References 378 [IANA.core-parameters] 379 IANA, "Constrained RESTful Environments (CoRE) 380 Parameters", 381 . 383 [IANA.media-type-structured-suffix] 384 IANA, "Structured Syntax Suffix Registry", 385 . 388 [IANA.media-types] 389 IANA, "Media Types", 390 . 392 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 393 Requirement Levels", BCP 14, RFC 2119, 394 DOI 10.17487/RFC2119, March 1997, 395 . 397 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 398 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 399 October 2013, . 401 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 402 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 403 May 2017, . 405 7.2. Informative References 407 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 408 Specifications and Registration Procedures", BCP 13, 409 RFC 6838, DOI 10.17487/RFC6838, January 2013, 410 . 412 [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text 413 Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, 414 . 416 [RFC8091] Wilde, E., "A Media Type Structured Syntax Suffix for JSON 417 Text Sequences", RFC 8091, DOI 10.17487/RFC8091, February 418 2017, . 420 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 421 RFC 8152, DOI 10.17487/RFC8152, July 2017, 422 . 424 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 425 Interchange Format", STD 90, RFC 8259, 426 DOI 10.17487/RFC8259, December 2017, 427 . 429 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 430 Definition Language (CDDL): A Notational Convention to 431 Express Concise Binary Object Representation (CBOR) and 432 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 433 June 2019, . 435 Acknowledgements 437 This draft has mostly been generated from [RFC7464] by Nico Williams 438 and [RFC8091] by Erik Wilde, which do a similar, but slightly more 439 complicated exercise for JSON [RFC8259]. Laurence Lundblade raised 440 an issue on the CBOR mailing list that pointed out the need for this 441 document. Jim Schaad and John Mattsson provided helpful comments. 443 Author's Address 445 Carsten Bormann 446 Universitaet Bremen TZI 447 Postfach 330440 448 Bremen D-28359 449 Germany 451 Phone: +49-421-218-63921 452 Email: cabo@tzi.org