idnits 2.17.1 draft-fossati-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 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The Medium encoding uses exactly two bytes. The two upper bits of the first byte are set to 1 and 0 respectively. The following 14 bits are used to represent an unsigned integer in range [128, 16383]. Values outside this range MUST not be encoded using the Medium format. -- The document date (October 14, 2013) is 3839 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 113 -- Looks like a reference, but probably isn't: '0' on line 151 -- Looks like a reference, but probably isn't: '127' on line 151 -- Looks like a reference, but probably isn't: '128' on line 162 -- Looks like a reference, but probably isn't: '16383' on line 162 == Outdated reference: A later version (-03) exists of draft-fossati-core-publish-option-00 -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force T. Fossati 3 Internet-Draft KoanLogic 4 Intended status: Standards Track October 14, 2013 5 Expires: April 17, 2014 7 Multipart Content-Format Encoding for CoAP 8 draft-fossati-core-multipart-ct-03 10 Abstract 12 This memo defines Multipart, an "anonymous" Content-Format that can 13 be used to combine (even recursively) several different media types 14 into a single CoAP message-body with minimal framing overhead. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on April 17, 2014. 33 Copyright Notice 35 Copyright (c) 2013 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2 52 2. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 2 53 3. Multipart Content-Format Encoding . . . . . . . . . . . . . . 3 54 4. Length Encoding . . . . . . . . . . . . . . . . . . . . . . . 3 55 4.1. Small . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 4.2. Medium . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4.3. Large . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 59 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 60 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 61 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 8.1. Normative References . . . . . . . . . . . . . . . . . . 5 63 8.2. Informative References . . . . . . . . . . . . . . . . . 6 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 66 1. Introduction 68 This memo defines Multipart, an "anonymous" Content-Format that can 69 be used to combine (even recursively) several different media types 70 into a single CoAP message-body with minimal framing overhead. 72 This simple and pretty efficient binary framing mechanism can be 73 employed as an alternative to fully fledged marshalling mechanisms 74 (e.g. JSON [RFC4627], or CBOR [I-D.bormann-cbor]), to create 75 application specific formats which build on already existing types by 76 assigning to them the appropriate semantics. 78 Applications using the Multipart Content-Format are supposed to 79 define the internal structure of the Multipart representation, as 80 well as registering its outermost type -- typically one in range 81 10000-64999. 83 Specific sub-types in a Multipart container are always found at the 84 same fixed position, corresponding to their implicit name. Thus, the 85 way to allow for optional parts is to carry them as zero-length 86 values for their respective types. 88 1.1. Requirements Language 90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 92 document are to be interpreted as described in [RFC2119]. 94 2. Use Cases 95 Multipart originated from the need to atomically and compactly 96 publish a resource's data and meta-data (in form of its link-format 97 attributes) via the Publish Option [I-D.fossati-core-publish-option]. 99 Another plausible use-case for Multipart would be that of a CoAP 100 proxy which has to aggregate the many responses to a multicast 101 request into a single PDU back to the original requester. 103 3. Multipart Content-Format Encoding 105 Multipart encoding uses multiple adjacent frames each of which 106 represents a single media. Every frame can be broken down into three 107 logical pieces: the type of the framed media (T), its length in bytes 108 (L), and the media payload itself (V) as depicted in the following 109 figure. 111 ,------------------ Multipart ------------------. 112 +------+------+------+ +------+------+------+ 113 | T[1] | L[1] | V[1] | ... | T[n] | L[n] | V[n] | 114 +------+------+------+ +------+------+------+ 115 `------ part 1 ------' `------ part n ------' 117 The syntax and semantics associated to the TLV frames is as follows: 119 T: is one of the numeric content format identifiers defined in the 120 CoAP Content-Format Registry (Section 12.3 of 121 [I-D.ietf-core-coap]), and is encoded as a 16-bit unsigned 122 integer. 124 L: is the length in bytes of the following V frame, encoded as 125 defined in Section 4. It determines the offset of the next part, 126 or the end of the multipart representation when applied to the 127 last part. 129 V: is the media, encoded as implied by the preceding T field, yet 130 opaquely to the Multipart encoder/decoder. 132 The T and L fields are in network byte order. 134 4. Length Encoding 136 Three different encodings are defined for the L value depending on 137 the actual size of the corresponding V: Small for V whose size in 138 bytes is in range [0, 127], Medium for sizes in [128, 16383], and 139 Large to cover the [16384, 2^63 - 1] range. 141 An encoder MUST always use the most compact encoding, i.e. Small for 142 size less than 128 bytes, Medium for size less then 16384 bytes, and 143 Large in all other cases. A decoder MAY discard a received Multipart 144 payload if any of its L fields does not use the most compact encoding 145 for the given size. 147 4.1. Small 149 The Small encoding uses exactly one byte. The MSB is set to 0, and 150 the next 7 bits are used to represent an unsigned integer in range 151 [0, 127]. 153 0 1 2 3 4 5 6 7 154 +-+ +-+-+-+-+-+-+-+ 155 |0| | 0x00 - 0x7F | 156 +-+ +-+-+-+-+-+-+-+ 158 4.2. Medium 160 The Medium encoding uses exactly two bytes. The two upper bits of 161 the first byte are set to 1 and 0 respectively. The following 14 162 bits are used to represent an unsigned integer in range [128, 16383]. 163 Values outside this range MUST not be encoded using the Medium 164 format. 166 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 167 +-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 168 |1 0| | 0x0080 - 0x3FFF | 169 +-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 171 4.3. Large 173 The Large encoding uses a variable number of bytes (at least three) 174 and is logically split into two parts. The first part is exactly one 175 byte with the two upper bits set to 1. The lower 6 bits of the first 176 byte encode the length's length (LL) as an unsigned integer which 177 MUST NOT be less than 2. The actual length of V (L) -- which 178 consumes at least 2 other bytes -- follows, encoded using as many 179 bytes as declared by the preceding LL. 181 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 182 +-+-+ +-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 183 |1 1| |0x02 - 0x3F| | (at least 2 bytes) | (possibly more) 184 +-+-+ +-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 185 LL L 187 When LL is 0x02, then the length MUST NOT be less than 0x4000. 189 5. IANA Considerations 191 Applications using the Multipart Content-Format are supposed to 192 define the internal structure of the Multipart representation, as 193 well as registering its outermost type (typically one in range 194 10000-64999) in the "CoAP Content-Formats" sub-registry, within the 195 "CoRE Parameters" registry. 197 6. Security Considerations 199 The Large encoding may trigger insanely huge buffer allocations on 200 the receiving party. Receivers of Multipart SHOULD put a cap on the 201 maximum allowed size of the whole Multipart. A CoAP server MAY 202 respond with a 4.13 (Request Entity Too Large) status code to such 203 requests, and refuse to proceed further (i.e. processing remaining 204 parts). 206 A CoAP client can't tell whether a 4.15 (Unsupported Content-Format) 207 status code applies to the whole Multipart or just to one of its sub- 208 types. An attacker may leverage on this ambiguity to craft 209 application specific attacks (e.g. to cause downgraded behaviour). 210 Applications built on top of Multipart need to handle such 211 eventuality in a safe way. 213 7. Acknowledgements 215 Thanks to Carsten Bormann for the interesting discussions, and for 216 providing the multicast aggregation use-case. 218 8. References 220 8.1. Normative References 222 [I-D.ietf-core-coap] 223 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 224 Application Protocol (CoAP)", draft-ietf-core-coap-18 225 (work in progress), June 2013. 227 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 228 Requirement Levels", BCP 14, RFC 2119, March 1997. 230 8.2. Informative References 232 [I-D.bormann-cbor] 233 Bormann, C. and P. Hoffman, "Concise Binary Object 234 Representation (CBOR)", draft-bormann-cbor-09 (work in 235 progress), September 2013. 237 [I-D.fossati-core-publish-option] 238 Fossati, T., Giacomin, P., and S. Loreto, "Publish Option 239 for CoAP", draft-fossati-core-publish-option-00 (work in 240 progress), July 2012. 242 [RFC4627] Crockford, D., "The application/json Media Type for 243 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 245 Author's Address 247 Thomas Fossati 248 KoanLogic 250 Email: tho@koanlogic.com