idnits 2.17.00 (12 Aug 2021) /tmp/idnits48841/draft-li-core-coap-size-option-01.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 (May 16, 2011) is 4022 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) == Outdated reference: draft-ietf-core-block has been published as RFC 7959 == Outdated reference: draft-ietf-core-coap has been published as RFC 7252 == Outdated reference: draft-ietf-core-link-format has been published as RFC 6690 Summary: 0 errors (**), 0 flaws (~~), 4 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: November 17, 2011 Huawei Technologies 6 May 16, 2011 8 CoAP Option Extension : Size 9 draft-li-core-coap-size-option-01 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 November 17, 2011. 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. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 68 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 69 8. Normative References . . . . . . . . . . . . . . . . . . . . . 7 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 72 1. Introduction 74 This specification adds a new option Size to the Constrained 75 Application Protocol (CoAP). The main purpose is to indicate the 76 resource size in a Put/Post request, or in a Get response. 78 1.1. Justification 80 If the requester wants to retrieve large resource data using a Get 81 request, it is better to know in advance the size of the resource 82 data. Currently in the Link Format [I-D.ietf-core-link-format] 83 specification, the maximum size estimate attribute "sz" is defined to 84 give an indication of the estimated maximum size of the resource 85 data. By using this, the requester is able to know whether it is 86 capable to accept the resource data. However it is not possible for 87 the requester to know exactly how many blocks will be transmitted, 88 therefore, concurrent Get can't be supported. 90 Also in the Post/Put request (for example, a firmware update), it is 91 not possible for the recipient to know in advance what is the size of 92 the data to be transmitted. According to the current CoAP 93 [I-D.ietf-core-coap] specification, when transmitting large data, the 94 recipient will return an error code 4.13 (Request Entity Too Large) 95 to the requester when the data size is too big to be accepted by the 96 recipient. In this case the whole transmission has failed, and the 97 previous received data will be useless. This is a waste of 98 transmission resources. 100 This document adds the new Size Option to provide the capability to 101 indicate the accurate size in a Get response or in a Post/Put 102 request. 104 By using the Size Option in a Get response, the CoAP Server can let 105 the requester know the actual size of the resource in advance. This 106 is especially useful for large resources, and can facilitate the 107 requester to allocate enough buffer space before transmission. Also, 108 using the block size, the requester can calculate the total number of 109 blocks and can use concurrent Get requests to retrieve resource data 110 using the Block Option. Finally, the receipent can check the 111 resource size after the data transmission has been completed. 113 By using the Size Option in a Put/Post request, the requester can 114 indicate the resource size in the first Block Option message, to let 115 the recipient know the resource data size in advance. If the 116 recipient is not able to receive the data with the indicated size, 117 the recipient can tell the requester in a response code, avoiding the 118 cost of the actual data transmission. 120 1.2. Terminology 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 2. Size Option Extension 128 2.1. Size Option Definition 130 +------+-----+-------+-----------+--------+---------------+ 131 | Type | C/E | Name | Data type | Length | Default | 132 +------+-----+-------+-----------+--------+---------------+ 133 | 12 | E | Size | uint | 1-4 B | | 134 +------+-----+-------+-----------+--------+---------------+ 136 2.2. Using the Size Option 138 The Size Option is used to indicate the size of the resource data 139 measured in bytes. 141 It can be used in a Get response to give indication about the 142 resource data size. 144 The Get request including Size=0 is treated as a request to get the 145 size of the resource representation (but not the resource payload). 147 Also it can be used in a Post/Put request in the first Block Option 148 message. 150 The Size option is not expected to be included for small resources 151 that can easily be carried in a single MTU, but SHOULD be included 152 for resources larger than that, if the Size information is available. 154 In the absence of the option, the size of the resource data is 155 calculated after the data transmitted to the recipient, either from 156 the CoAP payload length or based on number of blocks and block size. 158 If the Size option is specified it SHOULD be accurate at that time, 159 and SHOULD NOT be an estimate. 161 But due to the dynamic change of the resource data, the Size may not 162 be accurate. If the value of Size option is not the same as the 163 actual transmitted data, the recipient MUST take the size of the 164 actual transmitted data as accurate, and ignore the Size option. In 165 case that the recipient gets all the data but it is still smaller 166 than the Size, the recipient SHOULD stop the transmission. If the 167 recipient finds out the transmitted data reaches the Size limit, and 168 there's more data left, the recipient SHOULD continue to transmit the 169 remaining data. 171 This option is "Elective". It MUST NOT occur more than once. 173 3. Interaction with Block option 175 3.1. Usage in Post/Put Request 177 In the Put/Post request for the large resource data, the requester 178 can indicate the size of the resource using the Size option. If the 179 recipient is not capable to receive the data with the indicated size, 180 the recipient MUST return a 4.13 (Request Entity Too Large) response 181 code to the requester, and the data transmission is avoided, so that 182 the cost of the actual data transmission is saved. 184 3.2. Usage in Get Response 186 In the Get response for the large resource data, the CoAP Server can 187 use Size option to indicate the resource size and return the first 188 block data. The requester can calculate the number of blocks to be 189 transferred based on the block size and the resource size, and use 190 concurrent Get requests to retrieve resource data. 192 4. Examples 194 This section gives a number of short examples with message flows to 195 illustrate the use of Size option in GET response, or in a PUT/POST 196 request. 198 The first example (Figure 1) shows that the requester does not know 199 the resource data size, and sends the Get request, the recipient can 200 send back the resource size using the Size option and the first 201 block. In the subsequent Get request, the requester can calculate 202 the number of blocks and use concurrent Get requests to retrieve 203 resource data. 205 CLIENT SERVER 206 | | 207 | CON [MID=1234], GET, /status ------> | 208 | | 209 | <------ ACK [MID=1234], 2.00 OK, 0/1/128, Size: 5000 | 210 | | 211 | CON [MID=1235], GET, /status, 1/0/128 ------> | 212 | | 213 | <------ ACK [MID=1235], 2.00 OK, 1/1/128 | 214 | | 215 | ... ... | 216 | | 217 | CON [MID=1280], GET, /status, 40/0/128 ------> | 218 | | 219 | <------ ACK [MID=1280], 2.00 OK, 40/0/128 | 220 | | 222 Figure 1: Size Option in a GET response 224 The second example (Figure 2) shows that the requester sends a Put 225 request with the Size option to indicate the resource data size, the 226 recipient determines that the resource data is too large to be 227 accepted according to the size information, and sends back a 4.13 228 (Request Entity Too Large) response code. 230 CLIENT SERVER 231 | | 232 | CON [MID=1234], Put, /options, 1/0/128, Size: 5000 ----> | 233 | | 234 | <------ ACK [MID=1234], 4.13 Request Entity Too Large | 235 | | 237 Figure 2: Size Option in a Put request 239 5. Security Considerations 241 This presents no security considerations beyond those in section 10 242 of the base CoAP specification [I-D.ietf-core-coap] and in section 5 243 of the block specification [I-D.ietf-core-block]. 245 6. IANA Considerations 247 The IANA is requested to add the following Option Number entry. 249 +--------+---------------+----------------+ 250 | Number | Name | Reference | 251 +--------+---------------+----------------+ 252 | 12 | Size | Section 2 | 253 +--------+---------------+----------------+ 255 7. Acknowledgements 257 The authors of this draft would like to thank the participants of the 258 email discussion on this issue. Thanks to Bert Greevenbosch, Charles 259 Palmer and Carsten Bormann for the detailed reviews and suggestions. 261 8. Normative References 263 [I-D.ietf-core-block] 264 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 265 draft-ietf-core-block-03 (work in progress), May 2011. 267 [I-D.ietf-core-coap] 268 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 269 "Constrained Application Protocol (CoAP)", 270 draft-ietf-core-coap-06 (work in progress), May 2011. 272 [I-D.ietf-core-link-format] 273 Shelby, Z., "CoRE Link Format", 274 draft-ietf-core-link-format-04 (work in progress), 275 May 2011. 277 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 278 Requirement Levels", BCP 14, RFC 2119, March 1997. 280 Authors' Addresses 282 Kepeng Li 283 Huawei Technologies 284 Huawei Base, Bantian, Longgang District 285 Shenzhen, Guangdong 518129 286 P. R. China 288 Phone: +86-755-28974289 289 Email: likepeng@huawei.com 290 Linyi Tian 291 Huawei Technologies 292 Huawei Base, Bantian, Longgang District 293 Shenzhen, Guangdong 518129 294 P. R. China 296 Phone: +86-755-28978078 297 Email: tianlinyi@huawei.com 299 Barry Leiba 300 Huawei Technologies 302 Phone: +1 646 827 0648 303 Email: barryleiba@computer.org 304 URI: http://internetmessagingtechnology.org/