idnits 2.17.1 draft-li-core-coap-size-option-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 (October 21, 2011) is 4570 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) == Unused Reference: 'I-D.ietf-core-block' is defined on line 331, but no explicit reference was found in the text == Outdated reference: A later version (-21) exists of draft-ietf-core-block-04 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-07 == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-07 Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 core K. Li 3 Internet-Draft L. Tian 4 Intended status: Standards Track B. Leiba 5 Expires: April 23, 2012 Huawei Technologies 6 October 21, 2011 8 CoAP Option Extension : Size 9 draft-li-core-coap-size-option-02 11 Abstract 13 This document defines an extension to the Constrained Application 14 Protocol (CoAP) to add a new option Size, which is used to indicate 15 the resource size in a PUT/POST request or in a GET response. 17 Note 19 Discussion and suggestions for improvement are requested, and should 20 be sent to core@ietf.org. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on April 23, 2012. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Justification . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 59 2. Size Option Extension . . . . . . . . . . . . . . . . . . . . . 4 60 2.1. Size Option Definition . . . . . . . . . . . . . . . . . . 4 61 2.2. Using the Size Option . . . . . . . . . . . . . . . . . . . 4 62 3. Interaction with Block option . . . . . . . . . . . . . . . . . 5 63 3.1. Usage in POST/PUT Request . . . . . . . . . . . . . . . . . 5 64 3.2. Usage in GET Response . . . . . . . . . . . . . . . . . . . 5 65 4. How to merge into Block draft . . . . . . . . . . . . . . . . . 5 66 4.1. The Size option . . . . . . . . . . . . . . . . . . . . . . 5 67 4.2. Using the Size option . . . . . . . . . . . . . . . . . . . 6 68 4.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 71 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 72 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8 73 9. Normative References . . . . . . . . . . . . . . . . . . . . . 8 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 76 1. Introduction 78 This specification adds a new option Size to the Constrained 79 Application Protocol (CoAP). The main purpose is to indicate the 80 resource size in a PUT/POST request, or in a GET response. 82 1.1. Justification 84 If the requester wants to retrieve large resource data using a GET 85 request, it is better to know in advance the size of the resource 86 data. Currently in the Link Format [I-D.ietf-core-link-format] 87 specification, the maximum size estimate attribute "sz" is defined to 88 give an indication of the estimated maximum size of the resource 89 data. By using this, the requester is able to know whether it is 90 capable to accept the resource data. However it is not possible for 91 the requester to know exactly how many blocks will be transmitted, 92 therefore, concurrent GET can't be supported. 94 Also in a POST/PUT request (for example, a firmware update), it is 95 not possible for the recipient to know in advance what is the size of 96 the data to be transmitted. According to the current CoAP 97 [I-D.ietf-core-coap] specification, when transmitting large data, the 98 recipient will return an error code 4.13 (Request Entity Too Large) 99 to the requester when the data size is too big to be accepted by the 100 recipient. In this case the whole transmission has failed, and the 101 previous received data will be useless. This is a waste of 102 transmission resources. 104 This document adds the new Size Option to provide the capability to 105 indicate the accurate size in a GET response or in a POST/PUT 106 request. 108 By using the Size Option in a GET response, the CoAP Server can let 109 the requester know the actual size of the resource in advance. This 110 is especially useful for large resources, and can facilitate the 111 requester to allocate enough buffer space before transmission. Also, 112 using the block size, the requester can calculate the total number of 113 blocks and can use concurrent GET requests to retrieve resource data 114 using the Block Option. Finally, the recipient can check the 115 resource size after the data transmission has been completed. 117 By using the Size Option in a PUT/POST request, the requester can 118 indicate the resource size in the first Block Option message, to let 119 the recipient know the resource data size in advance. If the 120 recipient is not able to receive the data with the indicated size, 121 the recipient can tell the requester in a response code, avoiding the 122 cost of the actual data transmission. 124 1.2. Terminology 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 128 document are to be interpreted as described in [RFC2119]. 130 2. Size Option Extension 132 2.1. Size Option Definition 134 +------+-----+-------+-----------+--------+---------------+ 135 | Type | C/E | Name | Data type | Length | Default | 136 +------+-----+-------+-----------+--------+---------------+ 137 | 18 | E | Size | uint | 0-4 B | | 138 +------+-----+-------+-----------+--------+---------------+ 140 2.2. Using the Size Option 142 The Size Option is used to indicate the size of the resource data 143 measured in bytes. 145 The GET request including Size=0 is treated as a request to get the 146 size of the resource representation (but not the resource payload). 148 The GET request including an empty Size option is treated as a 149 request to get the size of the resource representation with the 150 resource payload. 152 The Size option MUST be included in the GET response, if the Size 153 option is present in the request. 155 Also it SHOULD be used in a POST/PUT request in the first Block 156 Option message. 158 The Size option SHOULD be included for resources larger than a single 159 PDU, if the Size information is available. And it MAY be included 160 for resources smaller than a single MTU. 162 In the absence of the option, the size of the resource data is 163 calculated after the data has been transmitted to the recipient, 164 either from the CoAP payload length or based on number of blocks and 165 block size. 167 If the Size option is specified it SHOULD be accurate at that time, 168 and SHOULD NOT be an estimate. 170 But due to the dynamic change of the resource data, the Size may not 171 be accurate. If the value of Size option is not the same as the 172 actual transmitted data, the recipient MUST take the size of the 173 actual transmitted data as accurate, and ignore the Size option. In 174 case that the recipient gets all the data but it is still smaller 175 than the announced Size, the recipient SHOULD stop the transmission. 176 If the recipient finds out the transmitted data reaches the Size 177 limit, and there's more data left, the recipient SHOULD continue to 178 transmit the remaining data. 180 This option is "Elective". It MUST NOT occur more than once. 182 3. Interaction with Block option 184 3.1. Usage in POST/PUT Request 186 In a PUT/POST request for large resource data, the requester SHOULD 187 use the Size option to indicate the size of the resource. If the 188 recipient is not capable to receive the data with the indicated size, 189 the recipient MUST return a 4.13 (Request Entity Too Large) response 190 code to the requester, and the data transmission is avoided, so that 191 the cost of the actual data transmission is saved. 193 3.2. Usage in GET Response 195 In a GET response for large resource data, the CoAP Server SHOULD use 196 the Size option to indicate the resource size and return the first 197 block data. The requester can calculate the number of blocks to be 198 transferred based on the block size and the resource size, and use 199 concurrent GET requests to retrieve resource data. Also, when the 200 client determines it cannot process data of this Size, it MAY choose 201 to abort and not to send subsequent GETs. 203 4. How to merge into Block draft 205 This section introduces how to merge the Size option draft into Block 206 draft with the minimum functionalities. 208 4.1. The Size option 210 This section will work as section 2.3 in Block draft. 212 +------+-----+-------+-----------+--------+---------------+ 213 | Type | C/E | Name | Data type | Length | Default | 214 +------+-----+-------+-----------+--------+---------------+ 215 | 18 | E | Size | uint | 1-4 B | | 216 +------+-----+-------+-----------+--------+---------------+ 218 4.2. Using the Size option 220 This section will work as section 2.4 in Block draft. 222 The Size Option is used to indicate the size of the resource data 223 measured in bytes. 225 The Size option SHOULD be used in a POST/PUT request in the first 226 Block Option message. If the recipient is not capable to receive the 227 data with the indicated size, the recipient MUST return a 4.13 228 (Request Entity Too Large) response code to the requester, and the 229 data transmission is avoided, so that the cost of the actual data 230 transmission is saved. 232 For a GET request, if it includes an empty Size option, the Size 233 option MUST be included in the response. If the GET request includes 234 a Block option, the Size option SHOULD be included in the first Block 235 response. In other cases the GET response MAY contain a Size option. 237 If the Size option is specified, it SHOULD be accurate at that time, 238 and SHOULD NOT be an estimate. 240 The option is "Elective". It MUST NOT occur more than once. 242 4.3. Example 244 Example as indicated as Figure 2 in this draft can be added in 245 section 3 in the Block draft. 247 5. Examples 249 This section gives a number of short examples with message flows to 250 illustrate the use of Size option in a GET response, or in a PUT/POST 251 request. 253 The first example (Figure 1) shows that the requester does not know 254 the resource data size, and sends the GET request, the recipient can 255 send back the resource size using the Size option and the first 256 block. In the subsequent GET request, the requester can calculate 257 the number of blocks and use concurrent GET requests to retrieve the 258 resource data. 260 CLIENT SERVER 261 | | 262 | CON [MID=1234], GET, /status ------> | 263 | | 264 | <------ ACK [MID=1234], 2.00 OK, 0/1/128, Size: 5000 | 265 | | 266 | CON [MID=1235], GET, /status, 1/0/128 ------> | 267 | | 268 | <------ ACK [MID=1235], 2.00 OK, 1/1/128 | 269 | | 270 | ... ... | 271 | | 272 | CON [MID=1280], GET, /status, 40/0/128 ------> | 273 | | 274 | <------ ACK [MID=1280], 2.00 OK, 40/0/128 | 275 | | 277 Figure 1: Size Option in a GET response 279 The second example (Figure 2) shows the requester sending a PUT 280 request with the Size option to indicate the resource data size, and 281 since the recipient determines that the resource data is too large to 282 be accepted, it sends back a 4.13 (Request Entity Too Large) response 283 code. 285 CLIENT SERVER 286 | | 287 | CON [MID=1234], PUT, /options, 1/0/128, Size: 5000 ----> | 288 | | 289 | <------ ACK [MID=1234], 4.13 Request Entity Too Large | 290 | | 292 Figure 2: Size Option in a PUT request 294 6. Security Considerations 296 As the size option is used to determine whether or not the reciepient 297 will accept the data, lying about it can cause the recipient to make 298 a wrong decision. For example, an attacker might reduce the reported 299 size such that the recipient will accept, even when it cannot process 300 the complete data. 302 Related is another attack, where the attacker changes the reported 303 size to a higher value, leading to the recipient rejecting even when 304 it has the capability to receive. 306 The latter attack is similar to an attack where the attacker blocks 307 the packets altogether; although it is more efficient since the 308 attacker only needs to modify one message. The former attack needs 309 serious consideration at implementation level, especially concerning 310 possible buffer overflows that might lead to data leaking into the 311 code. 313 7. IANA Considerations 315 The IANA is requested to add the following Option Number entry. 317 +--------+---------------+----------------+ 318 | Number | Name | Reference | 319 +--------+---------------+----------------+ 320 | 18 | Size | Section 2 | 321 +--------+---------------+----------------+ 323 8. Acknowledgements 325 The authors of this draft would like to thank the participants of the 326 email discussion on this issue. Thanks to Bert Greevenbosch, Charles 327 Palmer and Carsten Bormann for the detailed reviews and suggestions. 329 9. Normative References 331 [I-D.ietf-core-block] 332 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 333 draft-ietf-core-block-04 (work in progress), July 2011. 335 [I-D.ietf-core-coap] 336 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 337 "Constrained Application Protocol (CoAP)", 338 draft-ietf-core-coap-07 (work in progress), July 2011. 340 [I-D.ietf-core-link-format] 341 Shelby, Z., "CoRE Link Format", 342 draft-ietf-core-link-format-07 (work in progress), 343 July 2011. 345 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 346 Requirement Levels", BCP 14, RFC 2119, March 1997. 348 Authors' Addresses 350 Kepeng Li 351 Huawei Technologies 352 Huawei Base, Bantian, Longgang District 353 Shenzhen, Guangdong 518129 354 P. R. China 356 Phone: +86-755-28974289 357 Email: likepeng@huawei.com 359 Linyi Tian 360 Huawei Technologies 361 Huawei Base, Bantian, Longgang District 362 Shenzhen, Guangdong 518129 363 P. R. China 365 Phone: +86-755-28978078 366 Email: tianlinyi@huawei.com 368 Barry Leiba 369 Huawei Technologies 371 Phone: +1 646 827 0648 372 Email: barryleiba@computer.org 373 URI: http://internetmessagingtechnology.org/