idnits 2.17.1 draft-ietf-core-multipart-ct-04.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 (August 21, 2019) is 1702 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) == Outdated reference: A later version (-18) exists of draft-ietf-ace-coap-est-12 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE T. Fossati 3 Internet-Draft ARM 4 Intended status: Standards Track K. Hartke 5 Expires: February 22, 2020 Ericsson 6 C. Bormann 7 Universitaet Bremen TZI 8 August 21, 2019 10 Multipart Content-Format for CoAP 11 draft-ietf-core-multipart-ct-04 13 Abstract 15 This memo defines application/multipart-core, an application- 16 independent media-type that can be used to combine representations of 17 zero or more different media types into a single message, such as a 18 CoAP request or response body, with minimal framing overhead, each 19 along with a CoAP Content-Format identifier. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on February 22, 2020. 38 Copyright Notice 40 Copyright (c) 2019 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 57 2. Multipart Content-Format Encoding . . . . . . . . . . . . . . 4 58 3. Usage Example: Observing Resources . . . . . . . . . . . . . 4 59 4. Implementation Hints . . . . . . . . . . . . . . . . . . . . 5 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 61 5.1. Registration of media type application/multipart-core . . 6 62 5.2. Registration of a Content-Format identifier for 63 application/multipart-core . . . . . . . . . . . . . . . 7 64 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 65 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 67 7.2. Informative References . . . . . . . . . . . . . . . . . 8 68 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 71 1. Introduction 73 This memo defines application/multipart-core, an application- 74 independent media-type that can be used to combine representations of 75 zero or more different media types, each along with a CoAP Content- 76 Format identifier, into a single representation, with minimal framing 77 overhead. This combined representation may then be carried in a 78 single message, such as a CoAP [RFC7252] request or response body. 80 This simple and efficient binary framing mechanism can be employed to 81 create application specific request and response bodies which build 82 on multiple already existing media types. 84 As the name of the media-type suggests, it is inspired by the 85 multipart media types that started to be defined with the original 86 set of MIME specifications [RFC2046]. However, while those needed to 87 focus on the syntactic aspects of integrating multiple 88 representations into one e-mail, transfer protocols providing full 89 data transparency such as CoAP as well as readily available encoding 90 formats such as the Concise Binary Object Representation (CBOR) 91 [RFC7049] shift the focus towards the intended use of the combined 92 representations. In this respect, the basic intent of the 93 application/multipart-core media type is like that of multipart/mixed 94 (Section 5.1.3 of [RFC2046]). The detailed semantics of the 95 representations are refined by the context established by the 96 application in the accompanying request parameters, e.g., the 97 resource URI and any further options (header fields), but three usage 98 scenarios are envisioned: 100 The individual representations in an application/multipart-core body 101 occur in a sequence, which may be employed by an application where 102 such a sequence is natural, e.g. for a number of audio snippets in 103 various formats to be played out in that sequence, or search results 104 returned in order of relevance. 106 In other cases, an application may be more interested in a bag of 107 representations, which are distinguished by their Content-Format 108 identifier, such as an audio snippet and a text representation 109 accompanying it. In such a case, the sequence in which these occur 110 may not be relevant to the application. This specification adds the 111 option of substituting a null value for the representation of an 112 optional part, which indicates that the part is not present. 114 A third situation that is common only ever has a single 115 representation in the sequence, where the sender already selects just 116 one of a set of formats possible for this situation. This kind of 117 union "type" of formats may also make the presence of the actual 118 representation optional, the omission of which leads to a zero-length 119 array. 121 Where these rules are not sufficient for an application, it might 122 still use the general format defined here, but register a new media 123 type and an associated Content-Format identifier to associate the 124 representation with these more specific semantics instead of using 125 the application/multipart-core media type. 127 Also, future specifications might want to define rough equivalents 128 for other multipart media types with specific semantics not covered 129 by the present specification, such as multipart/alternative 130 (Section 5.1.4 of [RFC2046]), where several alternative 131 representations are provided in the message, but only one of those is 132 to be selected by the recipient for its use (this is less likely to 133 be useful in a constrained environment that has facilities for pre- 134 flight discovery). 136 1.1. Requirements Language 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in 141 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 142 capitals, as shown here. 144 2. Multipart Content-Format Encoding 146 A representation of media-type application/multipart-core contains a 147 collection of zero or more representations, each along with their 148 respective content format. 150 The collection is encoded as a CBOR [RFC7049] array with an even 151 number of elements. Counting from zero, the odd-numbered elements 152 are a byte string containing a representation, or the value "null" if 153 an optional part is indicated as not given. The (even-numbered) 154 element preceding each of these is an unsigned integer specifying the 155 content format ID of the representation following it. 157 For example, a collection containing two representations, one with 158 content format ID 42 and one with content format ID 0, looks like 159 this in CBOR diagnostic notation: 161 [42, h'0123456789abcdef', 0, h'3031323334'] 163 For illustration, the structure of an application/multipart-core 164 representation can be described by the CDDL [RFC8610] specification 165 in Figure 1: 167 multipart-core = [* multipart-part] 168 multipart-part = (type: uint .size 2, part: bytes / null) 170 Figure 1: CDDL for application/multipart-core 172 This format is intended as a strict specification: An implementation 173 MUST stop processing the representation if there is a CBOR well- 174 formedness error, a deviation from the structure defined above, or 175 any residual data left after processing the CBOR data item. (This 176 generally means the representation is not processed at all except if 177 some streaming processing has already happened.) 179 3. Usage Example: Observing Resources 181 This section illustrates one less obvious example for using 182 application/multipart-core: combining it with observing a resource 183 [RFC7641] to handle pending results. 185 When a client registers to observe a resource for which no 186 representation is available yet, the server may send one or more 2.05 187 (Content) notifications before sending the first actual 2.05 188 (Content) or 2.03 (Valid) notification. A diagram depicting possible 189 resulting sequences of notifications, identified by their respective 190 response code, is shown in Figure 2. 192 __________ __________ __________ 193 | | | | | | 194 ---->| 2.05 |---->| 2.05 / |---->| 4.xx / | 195 | Pending | | 2.03 | | 5.xx | 196 |__________| |__________| |__________| 197 ^ \ \ ^ \ ^ 198 \__/ \ \___/ / 199 \_______________________/ 201 Figure 2: Sequence of Notifications 203 The specification of the Observe option requires that all 204 notifications carry the same Content-Format. The application/ 205 multipart-core media type can be used to provide that Content-Format: 206 e.g., carrying an empty list of representations in the case marked as 207 "Pending" in Figure 2, and carrying a single representation specified 208 as the target content-format in the case in the middle of the figure. 210 4. Implementation Hints 212 This section describes the serialization for readers that may be new 213 to CBOR. It does not contain any new information. 215 An application/multipart-core representation carrying no 216 representations is represented by an empty CBOR array, which is 217 serialized as a single byte with the value 0x80. 219 An application/multipart-core representation carrying a single 220 representation is represented by a two-element CBOR array, which is 221 serialized as 0x82 followed by the two elements. The first element 222 is an unsigned integer for the Content-Format value, which is 223 represented as described in Table 1. The second element is the 224 object as a byte string, which is represented as a length as 225 described in Table 2 followed by the bytes of the object. 227 +----------------+------------+ 228 | Serialization | Value | 229 +----------------+------------+ 230 | 0x00..0x17 | 0..23 | 231 | 0x18 0xnn | 24..255 | 232 | 0x19 0xnn 0xnn | 256..65535 | 233 +----------------+------------+ 235 Table 1: Serialization of content-format 237 +-----------------------------+-------------------+ 238 | Serialization | Length | 239 +-----------------------------+-------------------+ 240 | 0x40..0x57 | 0..23 | 241 | 0x58 0xnn | 24..255 | 242 | 0x59 0xnn 0xnn | 256..65535 | 243 | 0x5a 0xnn 0xnn 0xnn 0xnn | 65536..4294967295 | 244 | 0x5b 0xnn .. 0xnn (8 bytes) | 4294967296.. | 245 +-----------------------------+-------------------+ 247 Table 2: Serialization of object length 249 For example, a single text/plain object (content-format 0) of value 250 "Hello World" (11 characters) would be serialized as 252 0x82 0x00 0x4b H e l l o 0x20 W o r l d 254 In effect, the serialization for a single object is done by prefixing 255 the object with information that there is one object (here: 0x82), 256 about its content-format (here: 0x00) and its length (here: 0x4b). 258 For more than one representation included in an application/ 259 multipart-core representation, the head of the CBOR array is adjusted 260 (0x84 for two representations, 0x86 for three, ...) and the sequences 261 of content-format and embedded representations follow. 263 For instance, the example from Section 2 would be serialized as: 265 0x84 (*) 0x182A 0x48 0x0123456789ABCDEF (+) 0x00 0x45 0x3031323334 267 where (*) marks the start of the information about the first 268 representation (content-format 42, byte string length 8) and, (+), of 269 the second representation (content-format 0, byte string length 5). 271 5. IANA Considerations 273 5.1. Registration of media type application/multipart-core 275 IANA is requested to register the following media type [RFC6838]: 277 Type name: application 279 Subtype name: multipart-core 281 Required parameters: N/A 283 Optional parameters: N/A 284 Encoding considerations: binary 286 Security considerations: See the Security Considerations Section of 287 RFCthis 289 Interoperability considerations: N/A 291 Published specification: RFCthis 293 Applications that use this media type: Applications that need to 294 combine representations of zero or more different media types into 295 one, e.g., EST-CoAP [I-D.ietf-ace-coap-est] 297 Fragment identifier considerations: The syntax and semantics of 298 fragment identifiers specified for "application/multipart-core" is 299 as specified for "application/cbor". (At publication of this 300 document, there is no fragment identification syntax defined for 301 "application/cbor".) 303 Additional information: 305 Deprecated alias names for this type: N/A 307 Magic number(s): N/A 309 File extension(s): N/A 311 Macintosh file type code(s): N/A 313 Person & email address to contact for further information: 314 iesg&ietf.org 316 Intended usage: COMMON 318 Restrictions on usage: N/A 320 Author: CoRE WG 322 Change controller: IESG 324 Provisional registration? (standards tree only): no 326 5.2. Registration of a Content-Format identifier for application/ 327 multipart-core 329 IANA is requested to register the following Content-Format to the 330 "CoAP Content-Formats" subregistry, within the "Constrained RESTful 331 Environments (CoRE) Parameters" registry, from the Expert Review 332 space (0..255): 334 +----------------------------+----------+------+-----------+ 335 | Media Type | Encoding | ID | Reference | 336 +----------------------------+----------+------+-----------+ 337 | application/multipart-core | -- | TBD1 | RFCthis | 338 +----------------------------+----------+------+-----------+ 340 6. Security Considerations 342 The security considerations of [RFC7049] apply. In particular, 343 resource exhaustion attacks may employ large values for the byte 344 string size fields, or deeply nested structures of recursively 345 embedded application/multipart-core representations. 347 7. References 349 7.1. Normative References 351 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 352 Requirement Levels", BCP 14, RFC 2119, 353 DOI 10.17487/RFC2119, March 1997, 354 . 356 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 357 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 358 October 2013, . 360 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 361 Application Protocol (CoAP)", RFC 7252, 362 DOI 10.17487/RFC7252, June 2014, 363 . 365 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 366 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 367 May 2017, . 369 7.2. Informative References 371 [I-D.ietf-ace-coap-est] 372 Stok, P., Kampanakis, P., Richardson, M., and S. Raza, 373 "EST over secure CoAP (EST-coaps)", draft-ietf-ace-coap- 374 est-12 (work in progress), June 2019. 376 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 377 Extensions (MIME) Part Two: Media Types", RFC 2046, 378 DOI 10.17487/RFC2046, November 1996, 379 . 381 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 382 Specifications and Registration Procedures", BCP 13, 383 RFC 6838, DOI 10.17487/RFC6838, January 2013, 384 . 386 [RFC7641] Hartke, K., "Observing Resources in the Constrained 387 Application Protocol (CoAP)", RFC 7641, 388 DOI 10.17487/RFC7641, September 2015, 389 . 391 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 392 Definition Language (CDDL): A Notational Convention to 393 Express Concise Binary Object Representation (CBOR) and 394 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 395 June 2019, . 397 Acknowledgements 399 Most of the text in this draft is from earlier contributions by two 400 of the authors, Thomas Fossati and Klaus Hartke. The re-mix in this 401 document is based on the requirements in [I-D.ietf-ace-coap-est], 402 based on discussions with Michael Richardson, Panos Kampanis and 403 Peter van der Stok. 405 Authors' Addresses 407 Thomas Fossati 408 ARM 410 Email: thomas.fossati@arm.com 412 Klaus Hartke 413 Ericsson 414 Torshamnsgatan 23 415 Stockholm SE-16483 416 Sweden 418 Email: klaus.hartke@ericsson.com 419 Carsten Bormann 420 Universitaet Bremen TZI 421 Postfach 330440 422 Bremen D-28359 423 Germany 425 Phone: +49-421-218-63921 426 Email: cabo@tzi.org