idnits 2.17.1 draft-ietf-core-multipart-ct-03.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 (March 08, 2019) is 1875 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-10 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-07 Summary: 1 error (**), 0 flaws (~~), 3 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: September 9, 2019 Ericsson 6 C. Bormann 7 Universitaet Bremen TZI 8 March 08, 2019 10 Multipart Content-Format for CoAP 11 draft-ietf-core-multipart-ct-03 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 September 9, 2019. 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 . . . . . . . . . . . . . . 3 58 3. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.1. Observing Resources . . . . . . . . . . . . . . . . . . . 4 60 4. Implementation hints . . . . . . . . . . . . . . . . . . . . 4 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 62 5.1. Registration of media type application/multipart-core . . 5 63 5.2. Registration of a Content-Format identifier for 64 application/multipart-core . . . . . . . . . . . . . . . 7 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 66 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 68 7.2. Informative References . . . . . . . . . . . . . . . . . 7 69 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 8 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 72 1. Introduction 74 This memo defines application/multipart-core, an application- 75 independent media-type that can be used to combine representations of 76 zero or more different media types into a single message, such as a 77 CoAP [RFC7252] request or response body, with minimal framing 78 overhead, each along with a CoAP Content-Format identifier. 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 The individual representations in an application/multipart-core body 85 occur in a sequence, which may be employed by an application where 86 such a sequence is natural, e.g. for a number of audio snippets in 87 different formats to be played out in that sequence. 89 In other cases, an application may be more interested in a bag of 90 representations, which are distinguished by their Content-Format 91 identifier, such as an audio snippet and a text representation 92 accompanying it. In such a case, the sequence in which these occur 93 may not be relevant to the application. This specification allows to 94 indicate that an optional part is not present by substituting a null 95 value for the representation of the part. 97 A third situation that is common only ever has a single 98 representation in the sequence, which is one of a set of formats 99 possible. This kind of union of formats may also make the presence 100 of the actual representation optional, the omission of which leads to 101 a zero-length array. 103 Where these rules are not sufficient for an application, it might 104 still use the general format defined here, but register a new media 105 type and an associated Content-Format identifier to associate the 106 representation with these more specific semantics instead of using 107 application/multipart-core. 109 1.1. Requirements Language 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 113 "OPTIONAL" in this document are to be interpreted as described in 114 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 115 capitals, as shown here. 117 2. Multipart Content-Format Encoding 119 A representation of media-type application/multipart-core contains a 120 collection of zero or more representations, each along with their 121 respective content format. 123 The collection is encoded as a CBOR [RFC7049] array with an even 124 number of elements. The second, fourth, sixth, etc. element is a 125 byte string containing a representation, or the value "null" if an 126 optional part is indicated as not given. The first, third, fifth, 127 etc. element is an unsigned integer specifying the content format ID 128 of the representation following it. 130 For example, a collection containing two representations, one with 131 content format ID 42 and one with content format ID 0, looks like 132 this in CBOR diagnostic notation: 134 [42, h'0123456789abcdef', 0, h'3031323334'] 136 For illustration, the structure of an application/multipart-core 137 representation can be described by the CDDL [I-D.ietf-cbor-cddl] 138 specification in Figure 1: 140 multipart-core = [* multipart-part] 141 multipart-part = (type: uint .size 2, part: bytes / null) 143 Figure 1: CDDL for application/multipart-core 145 This format is intended as a strict specification: An implementation 146 MUST stop processing the representation if there is a CBOR well- 147 formedness error, a deviation from the structure defined above, or 148 any residual data left after processing the CBOR data item. (This 149 generally means the representation is not processed at all except if 150 some streaming processing has already happened.) 152 3. Usage Examples 154 3.1. Observing Resources 156 When a client registers to observe a resource [RFC7641] for which no 157 representation is available yet, the server may send one or more 2.05 158 (Content) notifications before sending the first actual 2.05 159 (Content) or 2.03 (Valid) notification. The possible resulting 160 sequence of notifications is shown in Figure 1. 162 __________ __________ __________ 163 | | | | | | 164 ---->| 2.05 |---->| 2.05 / |---->| 4.xx / | 165 | Pending | | 2.03 | | 5.xx | 166 |__________| |__________| |__________| 167 ^ \ \ ^ \ ^ 168 \__/ \ \___/ / 169 \_______________________/ 171 Figure 2: Sequence of Notifications: 173 The specification of the Observe option requires that all 174 notifications carry the same Content-Format. The application/ 175 multipart-core media type can be used to provide that Content-Format: 176 e.g., carrying an empty list of representations in the case marked as 177 "Pending" in Figure 2, and carrying a single representation specified 178 as the target content-format in the case in the middle of the figure. 180 4. Implementation hints 182 This section describes the serialization for readers that may be new 183 to CBOR. It does not contain any new information. 185 An application/multipart-core representation carrying no 186 representations is represented by an empty CBOR array, which is 187 serialized as a single byte with the value 0x80. 189 An application/multipart-core representation carrying a single 190 representation is represented by a two-element CBOR array, which is 191 serialized as 0x82 followed by the two elements. The first element 192 is an unsigned integer for the Content-Format value, which is 193 represented as described in Table 1. The second element is the 194 object as a byte string, which is represented as a length as 195 described in Table 2 followed by the bytes of the object. 197 +----------------+------------+ 198 | Serialization | Value | 199 +----------------+------------+ 200 | 0x00..0x17 | 0..23 | 201 | 0x18 0xnn | 24..255 | 202 | 0x19 0xnn 0xnn | 256..65535 | 203 +----------------+------------+ 205 Table 1: Serialization of content-format 207 +-----------------------------+-------------------+ 208 | Serialization | Length | 209 +-----------------------------+-------------------+ 210 | 0x40..0x57 | 0..23 | 211 | 0x58 0xnn | 24..255 | 212 | 0x59 0xnn 0xnn | 256..65535 | 213 | 0x5a 0xnn 0xnn 0xnn 0xnn | 65536..4294967295 | 214 | 0x5b 0xnn .. 0xnn (8 bytes) | 4294967296.. | 215 +-----------------------------+-------------------+ 217 Table 2: Serialization of object length 219 For example, a single text/plain object (content-format 0) of value 220 "Hello World" (11 characters) would be serialized as 222 0x82 0x00 0x4b H e l l o 0x20 w o r l d 224 In effect, the serialization for a single object is done by prefixing 225 the object with information that there is one object (here: 0x82), 226 about its content-format (here: 0x00) and its length (here: 0x4b). 228 For more than one representation included in an application/ 229 multipart-core representation, the head of the CBOR array is adjusted 230 (0x84 for two representations, 0x86 for three, ...) and the sequences 231 of content-format and embedded representations follow. 233 5. IANA Considerations 235 5.1. Registration of media type application/multipart-core 237 IANA is requested to register the following media type [RFC6838]: 239 Type name: application 240 Subtype name: multipart-core 242 Required parameters: N/A 244 Optional parameters: N/A 246 Encoding considerations: binary 248 Security considerations: See the Security Considerations Section of 249 RFCthis 251 Interoperability considerations: N/A 253 Published specification: RFCthis 255 Applications that use this media type: Applications that need to 256 combine representations of zero or more different media types into 257 one, e.g., EST-CoAP [I-D.ietf-ace-coap-est] 259 Fragment identifier considerations: The syntax and semantics of 260 fragment identifiers specified for "application/multipart-core" is 261 as specified for "application/cbor". (At publication of this 262 document, there is no fragment identification syntax defined for 263 "application/cbor".) 265 Additional information: 267 Deprecated alias names for this type: N/A 269 Magic number(s): N/A 271 File extension(s): N/A 273 Macintosh file type code(s): N/A 275 Person & email address to contact for further information: 276 iesg&ietf.org 278 Intended usage: COMMON 280 Restrictions on usage: N/A 282 Author: CoRE WG 284 Change controller: IESG 286 Provisional registration? (standards tree only): no 288 5.2. Registration of a Content-Format identifier for application/ 289 multipart-core 291 IANA is requested to register the following Content-Format to the 292 "CoAP Content-Formats" subregistry, within the "Constrained RESTful 293 Environments (CoRE) Parameters" registry, from the Expert Review 294 space (0..255): 296 +----------------------------+----------+------+-----------+ 297 | Media Type | Encoding | ID | Reference | 298 +----------------------------+----------+------+-----------+ 299 | application/multipart-core | -- | TBD1 | RFCthis | 300 +----------------------------+----------+------+-----------+ 302 6. Security Considerations 304 The security considerations of [RFC7049] apply. In particular, 305 resource exhaustion attacks may employ large values for the byte 306 string size fields, or deeply nested structures of recursively 307 embedded application/multipart-core representations. 309 7. References 311 7.1. Normative References 313 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 314 Requirement Levels", BCP 14, RFC 2119, 315 DOI 10.17487/RFC2119, March 1997, 316 . 318 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 319 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 320 October 2013, . 322 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 323 Application Protocol (CoAP)", RFC 7252, 324 DOI 10.17487/RFC7252, June 2014, 325 . 327 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 328 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 329 May 2017, . 331 7.2. Informative References 333 [I-D.ietf-ace-coap-est] 334 Stok, P., Kampanakis, P., Richardson, M., and S. Raza, 335 "EST over secure CoAP (EST-coaps)", draft-ietf-ace-coap- 336 est-10 (work in progress), March 2019. 338 [I-D.ietf-cbor-cddl] 339 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 340 definition language (CDDL): a notational convention to 341 express CBOR and JSON data structures", draft-ietf-cbor- 342 cddl-07 (work in progress), February 2019. 344 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 345 Specifications and Registration Procedures", BCP 13, 346 RFC 6838, DOI 10.17487/RFC6838, January 2013, 347 . 349 [RFC7641] Hartke, K., "Observing Resources in the Constrained 350 Application Protocol (CoAP)", RFC 7641, 351 DOI 10.17487/RFC7641, September 2015, 352 . 354 Acknowledgements 356 Most of the text in this draft is from earlier contributions by two 357 of the authors, Thomas Fossati and Klaus Hartke. The re-mix in this 358 document is based on the requirements in [I-D.ietf-ace-coap-est], 359 based on discussions with Michael Richardson, Panos Kampanis and 360 Peter van der Stok. 362 Authors' Addresses 364 Thomas Fossati 365 ARM 367 Email: thomas.fossati@arm.com 369 Klaus Hartke 370 Ericsson 371 Torshamnsgatan 23 372 Stockholm SE-16483 373 Sweden 375 Email: klaus.hartke@ericsson.com 376 Carsten Bormann 377 Universitaet Bremen TZI 378 Postfach 330440 379 Bremen D-28359 380 Germany 382 Phone: +49-421-218-63921 383 Email: cabo@tzi.org