idnits 2.17.00 (12 Aug 2021) /tmp/idnits48457/draft-li-core-coap-size-option-00.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 26, 2011) is 4073 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. -------------------------------------------------------------------------------- 1 core K. Li 2 Internet-Draft L. Tian 3 Intended status: Standards Track B. Leiba 4 Expires: September 27, 2011 Huawei Technologies 5 March 26, 2011 7 CoAP Option Extension : Size 8 draft-li-core-coap-size-option-00 10 Abstract 12 This document defines an extension to the Constrained Application 13 Protocol (CoAP) to add a new option Size, which is used to indicate 14 the resource size in a Put/Post request or in a Get response. 16 Note 18 Discussion and suggestions for improvement are requested, and should 19 be sent to core@ietf.org. 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 http://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 27, 2011. 38 Copyright Notice 40 Copyright (c) 2011 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Justification . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Size Option Extension . . . . . . . . . . . . . . . . . . . . . 4 59 2.1. Size Option Definition . . . . . . . . . . . . . . . . . . 4 60 2.2. Using the Size Option . . . . . . . . . . . . . . . . . . . 4 61 3. Interaction with Block option . . . . . . . . . . . . . . . . . 5 62 3.1. Usage in Post/Put Request . . . . . . . . . . . . . . . . . 5 63 3.2. Usage in Get Response . . . . . . . . . . . . . . . . . . . 5 64 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 66 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 67 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 68 8. Normative References . . . . . . . . . . . . . . . . . . . . . 7 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 71 1. Introduction 73 This specification adds a new option Size to the Constrained 74 Application Protocol (CoAP). The main purpose is to indicate the 75 resource size in a Put/Post request, or in a Get response. 77 1.1. Justification 79 If the requester wants to retrieve large resource data using a Get 80 request, it is better to know in advance the size of the resource 81 data. Currently in the Link Format [I-D.ietf-core-link-format] 82 specification, the maximum size estimate attribute "sz" is defined to 83 give an indication of the estimated maximum size of the resource 84 data. By using this, the requester is able to know whether it is 85 capable to accept the resource data. However it is not possible for 86 the requester to know exactly how many blocks will be transmitted, 87 therefore, concurrent Get can't be supported. 89 Also in the Post/Put request (for example, a firmware update), it is 90 not possible for the recipient to know in advance what is the size of 91 the data to be transmitted. According to the current CoAP 92 [I-D.ietf-core-coap] specification, when transmitting large data, the 93 recipient will return an error code 4.13 (Request Entity Too Large) 94 to the requester when the data size is too big to be accepted by the 95 recipient. In this case the whole transmission has failed, and the 96 previous received data will be useless. This is a waste of 97 transmission resources. 99 This document adds the new Size Option to provide the capability to 100 indicate the accurate size in a Get response or in a Post/Put 101 request. 103 By using the Size Option in a Get response, the CoAP Server can let 104 the requester know the actual size of the resource in advance. This 105 is especially useful for large resources, and can facilitate the 106 requester to allocate enough buffer space before transmission. Also, 107 using the block size, the requester can calculate the total number of 108 blocks and can use concurrent Get requests to retrieve resource data 109 using the Block Option. Finally, the receipent can check the 110 resource size after the data transmission has been completed. 112 By using the Size Option in a Put/Post request, the requester can 113 indicate the resource size in the first Block Option message, to let 114 the recipient know the resource data size in advance. If the 115 recipient is not able to receive the data with the indicated size, 116 the recipient can tell the requester in a response code, avoiding the 117 cost of the actual data transmission. 119 1.2. Terminology 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in [RFC2119]. 125 2. Size Option Extension 127 2.1. Size Option Definition 129 +------+-----+-------+-----------+--------+---------------+ 130 | Type | C/E | Name | Data type | Length | Default | 131 +------+-----+-------+-----------+--------+---------------+ 132 | 12 | E | Size | uint | 1-4 B | | 133 +------+-----+-------+-----------+--------+---------------+ 135 2.2. Using the Size Option 137 The Size Option is used to indicate the size of the resource data 138 measured in bytes. 140 It can be used in a Get response to give indication about the 141 resource data size. 143 Also it can be used in a Post/Put request in the first Block Option 144 message. 146 The Size option is not expected to be included for small resources 147 that can easily be carried in a single MTU, but SHOULD be included 148 for resources larger than that. 150 In the absence of the option, the size of the resource data is 151 calculated after the data transmitted to the recipient, either from 152 the CoAP payload length or based on number of blocks and block size. 154 If the Size option is specified it MUST be accurate at that time, and 155 MUST NOT be an estimate. 157 But due to the dynamic change of the resource data, the Size may not 158 be accurate. If the value of Size option is not the same as the 159 actual transmitted data, the recipient MUST take the size of the 160 actual transmitted data as accurate, and ignore the Size option. In 161 case that the recipient gets all the data but it is still smaller 162 than the Size, the recipient SHOULD stop the transmission. If the 163 recipient finds out the transmitted data reaches the Size limit, and 164 there's more data left, the recipient SHOULD continue to transmit the 165 remaining data. 167 This option is "Elective". It MUST NOT occur more than once. 169 3. Interaction with Block option 171 3.1. Usage in Post/Put Request 173 In the Put/Post request for the large resource data, the requester 174 can indicate the size of the resource using the Size option. If the 175 recipient is not capable to receive the data with the indicated size, 176 the recipient MUST return a 4.13 (Request Entity Too Large) response 177 code to the requester, and the data transmission is avoided, so that 178 the cost of the actual data transmission is saved. 180 3.2. Usage in Get Response 182 In the Get response for the large resource data, the CoAP Server can 183 use Size option to indicate the resource size and return the first 184 block data. The requester can calculate the number of blocks to be 185 transferred based on the block size and the resource size, and use 186 concurrent Get requests to retrieve resource data. 188 4. Examples 190 This section gives a number of short examples with message flows to 191 illustrate the use of Size option in GET response, or in a PUT/POST 192 request. 194 The first example (Figure 1) shows that the requester does not know 195 the resource data size, and sends the Get request, the recipient can 196 send back the resource size using the Size option and the first 197 block. In the subsequent Get request, the requester can calculate 198 the number of blocks and use concurrent Get requests to retrieve 199 resource data. 201 CLIENT SERVER 202 | | 203 | CON [MID=1234], GET, /status ------> | 204 | | 205 | <------ ACK [MID=1234], 2.00 OK, 0/1/128, Size: 5000 | 206 | | 207 | CON [MID=1235], GET, /status, 1/0/128 ------> | 208 | | 209 | <------ ACK [MID=1235], 2.00 OK, 1/1/128 | 210 | | 211 | ... ... | 212 | | 213 | CON [MID=1280], GET, /status, 40/0/128 ------> | 214 | | 215 | <------ ACK [MID=1280], 2.00 OK, 40/0/128 | 216 | | 218 Figure 1: Size Option in a GET response 220 The second example (Figure 2) shows that the requester sends a Put 221 request with the Size option to indicate the resource data size, the 222 recipient determines that the resource data is too large to be 223 accepted according to the size information, and sends back a 4.13 224 (Request Entity Too Large) response code. 226 CLIENT SERVER 227 | | 228 | CON [MID=1234], Put, /options, 1/0/128, Size: 5000 ----> | 229 | | 230 | <------ ACK [MID=1234], 4.13 Request Entity Too Large | 231 | | 233 Figure 2: Size Option in a Put request 235 5. Security Considerations 237 This presents no security considerations beyond those in section 10 238 of the base CoAP specification [I-D.ietf-core-coap] and in section 5 239 of the block specification [I-D.ietf-core-block]. 241 6. IANA Considerations 243 The IANA is requested to add the following Option Number entry. 245 +--------+---------------+----------------+ 246 | Number | Name | Reference | 247 +--------+---------------+----------------+ 248 | 12 | Size | Section 2 | 249 +--------+---------------+----------------+ 251 7. Acknowledgements 253 The authors of this draft would like to thank the participants of the 254 email discussion on this issue. Thanks to Bert Greevenbosch for the 255 detailed reviews and discussions. 257 8. Normative References 259 [I-D.ietf-core-block] 260 Shelby, Z. and C. Bormann, "Blockwise transfers in CoAP", 261 draft-ietf-core-block-02 (work in progress), March 2011. 263 [I-D.ietf-core-coap] 264 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 265 "Constrained Application Protocol (CoAP)", 266 draft-ietf-core-coap-05 (work in progress), March 2011. 268 [I-D.ietf-core-link-format] 269 Shelby, Z., "CoRE Link Format", 270 draft-ietf-core-link-format-03 (work in progress), 271 March 2011. 273 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 274 Requirement Levels", BCP 14, RFC 2119, March 1997. 276 Authors' Addresses 278 Kepeng Li 279 Huawei Technologies 280 Huawei Base, Bantian, Longgang District 281 Shenzhen, Guangdong 518129 282 P. R. China 284 Phone: +86-755-28974289 285 Email: likepeng@huawei.com 286 Linyi Tian 287 Huawei Technologies 288 Huawei Base, Bantian, Longgang District 289 Shenzhen, Guangdong 518129 290 P. R. China 292 Phone: +86-755-28978078 293 Email: tianlinyi@huawei.com 295 Barry Leiba 296 Huawei Technologies 298 Phone: +1 646 827 0648 299 Email: barryleiba@computer.org 300 URI: http://internetmessagingtechnology.org/