idnits 2.17.1 draft-ietf-core-multipart-ct-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 (August 07, 2018) is 2089 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-05 == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-03 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 Nokia 4 Intended status: Standards Track K. Hartke 5 Expires: February 8, 2019 Ericsson 6 C. Bormann 7 Universitaet Bremen TZI 8 August 07, 2018 10 Multipart Content-Format for CoAP 11 draft-ietf-core-multipart-ct-02 13 Abstract 15 This memo defines application/multipart-core, an application- 16 independent media-type that can be used to combine representations of 17 several different media types into a single CoAP message-body with 18 minimal framing overhead, each along with a CoAP Content-Format 19 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 8, 2019. 38 Copyright Notice 40 Copyright (c) 2018 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 2. Multipart Content-Format Encoding . . . . . . . . . . . . . . 3 57 3. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . 3 58 3.1. Observing Resources . . . . . . . . . . . . . . . . . . . 3 59 3.2. Implementation hints . . . . . . . . . . . . . . . . . . 4 60 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 61 4.1. Registration of media type application/multipart-core . . 5 62 4.2. Registration of a Content-Format identifier for 63 application/multipart-core . . . . . . . . . . . . . . . 6 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 65 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 67 6.2. Informative References . . . . . . . . . . . . . . . . . 7 68 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 7 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 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 several different media types into a single CoAP [RFC7252] message- 76 body with minimal framing overhead, each along with a CoAP Content- 77 Format identifier. 79 This simple and efficient binary framing mechanism can be employed to 80 create application specific request and response bodies which build 81 on multiple already existing media types. 83 Applications using the application/multipart-core Content-Format 84 define the internal structure of the application/multipart-core 85 representation. 87 For example, one way to structure the sub-types specific to an 88 application/multipart-core container is to always include them at the 89 same fixed position. This specification allows to indicate that an 90 optional part is not present by substituting a null value for the 91 representation of the part. 93 Optionally, an application might use the general format defined here, 94 but also register a new media type and an associated Content-Format 95 identifier -- typically one in the range 10000-64999 -- instead of 96 using application/multipart-core. 98 2. Multipart Content-Format Encoding 100 A representation of media-type application/multipart-core contains a 101 collection of zero or more representations, each along with their 102 respective content format. 104 The collection is encoded as a CBOR [RFC7049] array with an even 105 number of elements. The second, fourth, sixth, etc. element is a 106 byte string containing a representation, or the value "null" if an 107 optional part is indicated as not given. The first, third, fifth, 108 etc. element is an unsigned integer specifying the content format ID 109 of the representation following it. (Future extensions might want to 110 include additional alternative ways of specifying the media type of a 111 representation in such a position.) 113 For example, a collection containing two representations, one with 114 content format ID 42 and one with content format ID 0, looks like 115 this in CBOR diagnostic notation: 117 [42, h'0123456789abcdef', 0, h'3031323334'] 119 For illustration, the structure of an application/multipart-core 120 representation can be described by the CDDL [I-D.ietf-cbor-cddl] 121 specification in Figure 1: 123 multipart-core = [* multipart-part] 124 multipart-part = (type: uint .size 2, part: bytes / null) 126 Figure 1: CDDL for application/multipart-core 128 3. Usage Examples 130 3.1. Observing Resources 132 When a client registers to observe a resource [RFC7641] for which no 133 representation is available yet, the server may send one or more 2.05 134 (Content) notifications before sending the first actual 2.05 135 (Content) or 2.03 (Valid) notification. The possible resulting 136 sequence of notifications is shown in Figure 1. 138 __________ __________ __________ 139 | | | | | | 140 ---->| 2.05 |---->| 2.05 / |---->| 4.xx / | 141 | Pending | | 2.03 | | 5.xx | 142 |__________| |__________| |__________| 143 ^ \ \ ^ \ ^ 144 \__/ \ \___/ / 145 \_______________________/ 147 Figure 2: Sequence of Notifications: 149 The specification of the Observe option requires that all 150 notifications carry the same Content-Format. The application/ 151 multipart-core media type can be used to provide that Content-Format: 152 e.g., carrying an empty list of representations in the case marked as 153 "Pending" in Figure 2, and carrying a single representation specified 154 as the target content-format in the case in the middle of the figure. 156 3.2. Implementation hints 158 This section describes the serialization for readers that may be new 159 to CBOR. It does not contain any new information. 161 An application/multipart-core representation carrying no 162 representations is represented by an empty CBOR array, which is 163 serialized as a single byte with the value 0x80. 165 An application/multipart-core representation carrying a single 166 representation is represented by a two-element CBOR array, which is 167 serialized as 0x82 followed by the two elements. The first element 168 is an unsigned integer for the Content-Format value, which is 169 represented as described in Table 1. The second element is the 170 object as a byte string, which is represented as a length as 171 described in Table 2 followed by the bytes of the object. 173 +----------------+------------+ 174 | Serialization | Value | 175 +----------------+------------+ 176 | 0x00..0x17 | 0..23 | 177 | 0x18 0xnn | 24..255 | 178 | 0x19 0xnn 0xnn | 256..66535 | 179 +----------------+------------+ 181 Table 1: Serialization of content-format 183 +-----------------------------+-------------------+ 184 | Serialization | Length | 185 +-----------------------------+-------------------+ 186 | 0x40..0x57 | 0..23 | 187 | 0x58 0xnn | 24..255 | 188 | 0x59 0xnn 0xnn | 256..66535 | 189 | 0x5a 0xnn 0xnn 0xnn 0xnn | 66536..4294967295 | 190 | 0x5b 0xnn .. 0xnn (8 bytes) | 4294967296.. | 191 +-----------------------------+-------------------+ 193 Table 2: Serialization of object length 195 For example, a single text/plain object (content-format 0) of value 196 "Hello World" (11 characters) would be serialized as 198 0x82 0x00 0x4b H e l l o 0x20 w o r l d 200 In effect, the serialization for a single object is done by prefixing 201 the object with information about its content-format (here: 0x82 202 0x00) and its length (here: 0x4b). 204 For more than one representation included in an application/ 205 multipart-core representation, the head of the CBOR array is adjusted 206 (0x84 for two representations, 0x86 for three, ...) and the sequences 207 of content-format and embedded representations follow. 209 4. IANA Considerations 211 4.1. Registration of media type application/multipart-core 213 IANA is requested to register the following media type [RFC6838]: 215 Type name: application 217 Subtype name: multipart-core 219 Required parameters: N/A 221 Optional parameters: N/A 223 Encoding considerations: binary 225 Security considerations: See the Security Considerations Section of 226 RFCthis 228 Interoperability considerations: N/A 230 Published specification: RFCthis 231 Applications that use this media type: Applications that need to 232 combine representations of potentially several media types into 233 one, e.g., EST-CoAP [I-D.ietf-ace-coap-est] 235 Fragment identifier considerations: N/A 237 Additional information: 239 Deprecated alias names for this type: N/A 241 Magic number(s): N/A 243 File extension(s): N/A 245 Macintosh file type code(s): N/A 247 Person & email address to contact for further information: 248 iesg&ietf.org 250 Intended usage: COMMON 252 Restrictions on usage: N/A 254 Author: CoRE WG 256 Change controller: IESG 258 Provisional registration? (standards tree only): no 260 4.2. Registration of a Content-Format identifier for application/ 261 multipart-core 263 IANA is requested to register the following Content-Format to the 264 "CoAP Content-Formats" subregistry, within the "Constrained RESTful 265 Environments (CoRE) Parameters" registry, from the Expert Review 266 space (0..255): 268 +----------------------------+----------+------+-----------+ 269 | Media Type | Encoding | ID | Reference | 270 +----------------------------+----------+------+-----------+ 271 | application/multipart-core | -- | TBD1 | RFCthis | 272 +----------------------------+----------+------+-----------+ 274 5. Security Considerations 276 The security considerations of [RFC7049] apply. In particular, 277 resource exhaustion attacks may employ large values for the byte 278 string size fields, or deeply nested structures of recursively 279 embedded application/multipart-core representations. 281 6. References 283 6.1. Normative References 285 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 286 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 287 October 2013, . 289 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 290 Application Protocol (CoAP)", RFC 7252, 291 DOI 10.17487/RFC7252, June 2014, 292 . 294 [RFC7641] Hartke, K., "Observing Resources in the Constrained 295 Application Protocol (CoAP)", RFC 7641, 296 DOI 10.17487/RFC7641, September 2015, 297 . 299 6.2. Informative References 301 [I-D.ietf-ace-coap-est] 302 Stok, P., Kampanakis, P., Kumar, S., Richardson, M., 303 Furuhed, M., and S. Raza, "EST over secure CoAP (EST- 304 coaps)", draft-ietf-ace-coap-est-05 (work in progress), 305 July 2018. 307 [I-D.ietf-cbor-cddl] 308 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 309 definition language (CDDL): a notational convention to 310 express CBOR data structures", draft-ietf-cbor-cddl-03 311 (work in progress), July 2018. 313 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 314 Specifications and Registration Procedures", BCP 13, 315 RFC 6838, DOI 10.17487/RFC6838, January 2013, 316 . 318 Acknowledgements 320 Most of the text in this draft is from earlier contributions by two 321 of the authors, Thomas Fossati and Klaus Hartke. The re-mix in this 322 document is based on the requirements in [I-D.ietf-ace-coap-est], 323 based on discussions with Michael Richardson, Panos Kampanis and 324 Peter van der Stok. 326 Authors' Addresses 328 Thomas Fossati 329 Nokia 331 Email: thomas.fossati@nokia.com 333 Klaus Hartke 334 Ericsson 335 Torshamnsgatan 23 336 Stockholm SE-16483 337 Sweden 339 Email: klaus.hartke@ericsson.com 341 Carsten Bormann 342 Universitaet Bremen TZI 343 Postfach 330440 344 Bremen D-28359 345 Germany 347 Phone: +49-421-218-63921 348 Email: cabo@tzi.org