idnits 2.17.1 draft-ietf-core-block-14.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, 2013) is 3838 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) == Missing Reference: 'RFCXXXX' is mentioned on line 1221, but not defined == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-11 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) 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 Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Standards Track Z. Shelby, Ed. 5 Expires: April 24, 2014 Sensinode 6 October 21, 2013 8 Blockwise transfers in CoAP 9 draft-ietf-core-block-14 11 Abstract 13 CoAP is a RESTful transfer protocol for constrained nodes and 14 networks. Basic CoAP messages work well for the small payloads we 15 expect from temperature sensors, light switches, and similar 16 building-automation devices. Occasionally, however, applications 17 will need to transfer larger payloads -- for instance, for 18 firmware updates. With HTTP, TCP does the grunt work of slicing 19 large payloads up into multiple packets and ensuring that they all 20 arrive and are handled in the right order. 22 CoAP is based on datagram transports such as UDP or DTLS, which 23 limits the maximum size of resource representations that can be 24 transferred without too much fragmentation. Although UDP supports 25 larger payloads through IP fragmentation, it is limited to 64 KiB 26 and, more importantly, doesn't really work well for constrained 27 applications and networks. 29 Instead of relying on IP fragmentation, this specification extends 30 basic CoAP with a pair of "Block" options, for transferring multiple 31 blocks of information from a resource representation in multiple 32 request-response pairs. In many important cases, the Block options 33 enable a server to be truly stateless: the server can handle each 34 block transfer separately, with no need for a connection setup or 35 other server-side memory of previous block transfers. 37 In summary, the Block options provide a minimal way to transfer 38 larger representations in a block-wise fashion. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at http://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on April 24, 2014. 57 Copyright Notice 59 Copyright (c) 2013 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents 64 (http://trustee.ietf.org/license-info) in effect on the date of 65 publication of this document. Please review these documents 66 carefully, as they describe your rights and restrictions with respect 67 to this document. Code Components extracted from this document must 68 include Simplified BSD License text as described in Section 4.e of 69 the Trust Legal Provisions and are provided without warranty as 70 described in the Simplified BSD License. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 4 76 2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 5 77 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 6 78 2.3. Block Options in Requests and Responses . . . . . . . . . 8 79 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 10 80 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 11 81 2.6. Combining Blockwise Transfers with the Observe Option . . 12 82 2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 13 83 2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 13 84 2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 14 85 2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 14 86 2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 14 87 2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 14 88 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 14 89 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15 90 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 18 91 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20 92 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 21 93 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 24 94 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 25 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 28 97 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 28 98 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 29 99 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 29 100 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 101 9.1. Normative References . . . . . . . . . . . . . . . . . . 30 102 9.2. Informative References . . . . . . . . . . . . . . . . . 30 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 105 1. Introduction 107 The CoRE WG is tasked with standardizing an Application Protocol for 108 Constrained Networks/Nodes, CoAP. This protocol is intended to 109 provide RESTful [REST] services not unlike HTTP [RFC2616], while 110 reducing the complexity of implementation as well as the size of 111 packets exchanged in order to make these services useful in a highly 112 constrained network of themselves highly constrained nodes. 114 This objective requires restraint in a number of sometimes 115 conflicting ways: 117 o reducing implementation complexity in order to minimize code size, 119 o reducing message sizes in order to minimize the number of 120 fragments needed for each message (in turn to maximize the 121 probability of delivery of the message), the amount of 122 transmission power needed and the loading of the limited-bandwidth 123 channel, 125 o reducing requirements on the environment such as stable storage, 126 good sources of randomness or user interaction capabilities. 128 CoAP is based on datagram transports such as UDP, which limit the 129 maximum size of resource representations that can be transferred 130 without creating unreasonable levels of IP fragmentation. In 131 addition, not all resource representations will fit into a single 132 link layer packet of a constrained network, which may cause 133 adaptation layer fragmentation even if IP layer fragmentation is not 134 required. Using fragmentation (either at the adaptation layer or at 135 the IP layer) to enable the transport of larger representations is 136 possible up to the maximum size of the underlying datagram protocol 137 (such as UDP), but the fragmentation/reassembly process burdens the 138 lower layers with conversation state that is better managed in the 139 application layer. 141 The present specification defines a pair of CoAP options to enable 142 _block-wise_ access to resource representations. The Block options 143 provide a minimal way to transfer larger resource representations in 144 a block-wise fashion. The overriding objective is to avoid the need 145 for creating conversation state at the server for block-wise GET 146 requests. (It is impossible to fully avoid creating conversation 147 state for POST/PUT, if the creation/replacement of resources is to be 148 atomic; where that property is not needed, there is no need to create 149 server conversation state in this case, either.) 151 In summary, this specification adds a pair of Block options to CoAP 152 that can be used for block-wise transfers. Benefits of using these 153 options include: 155 o Transfers larger than what can be accommodated in constrained- 156 network link-layer packets can be performed in smaller blocks. 158 o No hard-to-manage conversation state is created at the adaptation 159 layer or IP layer for fragmentation. 161 o The transfer of each block is acknowledged, enabling 162 retransmission if required. 164 o Both sides have a say in the block size that actually will be 165 used. 167 o The resulting exchanges are easy to understand using packet 168 analyzer tools and thus quite accessible to debugging. 170 o If needed, the Block options can also be used (without changes) to 171 provide random access to power-of-two sized blocks within a 172 resource representation. 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 176 document are to be interpreted as described in RFC 2119, BCP 14 177 [RFC2119] and indicate requirement levels for compliant CoAP 178 implementations. 180 In this document, the term "byte" is used in its now customary sense 181 as a synonym for "octet". 183 Where bit arithmetic is explained, this document uses the notation 184 familiar from the programming language C, except that the operator 185 "**" stands for exponentiation. 187 2. Block-wise transfers 189 As discussed in the introduction, there are good reasons to limit the 190 size of datagrams in constrained networks: 192 o by the maximum datagram size (~ 64 KiB for UDP) 193 o by the desire to avoid IP fragmentation (MTU of 1280 for IPv6) 195 o by the desire to avoid adaptation layer fragmentation (60-80 bytes 196 for 6LoWPAN [RFC4919]) 198 When a resource representation is larger than can be comfortably 199 transferred in the payload of a single CoAP datagram, a Block option 200 can be used to indicate a block-wise transfer. As payloads can be 201 sent both with requests and with responses, this specification 202 provides two separate options for each direction of payload transfer. 203 In identifying these options, we use the number 1 to refer to the 204 transfer of the resource representation that pertains to the request, 205 and the number 2 to refer to the transfer of the resource 206 representation for the response. 208 In the following, the term "payload" will be used for the actual 209 content of a single CoAP message, i.e. a single block being 210 transferred, while the term "body" will be used for the entire 211 resource representation that is being transferred in a block-wise 212 fashion. The Content-Format option applies to the body, not to the 213 payload, in particular the boundaries between the blocks may be in 214 places that are not separating whole units in terms of the structure, 215 encoding, or content-coding used by the Content-Format. 217 In most cases, all blocks being transferred for a body will be of the 218 same size. The block size is not fixed by the protocol. To keep the 219 implementation as simple as possible, the Block options support only 220 a small range of power-of-two block sizes, from 2**4 (16) to 2**10 221 (1024) bytes. As bodies often will not evenly divide into the power- 222 of-two block size chosen, the size need not be reached in the final 223 block (but even for the final block, the chosen power-of-two size 224 will still be indicated in the block size field of the Block option). 226 2.1. The Block2 and Block1 Options 228 +------+---+---+---+---+--------+--------+--------+---------+ 229 | Type | C | U | N | R | Name | Format | Length | Default | 230 +------+---+---+---+---+--------+--------+--------+---------+ 231 | 23 | C | U | - | - | Block2 | uint | 0-3 B | (none) | 232 | | | | | | | | | | 233 | 27 | C | U | - | - | Block1 | uint | 0-3 B | (none) | 234 +------+---+---+---+---+--------+--------+--------+---------+ 236 Table 1: Block Option Numbers 238 Both Block1 and Block2 options can be present both in request and 239 response messages. In either case, the Block1 Option pertains to the 240 request payload, and the Block2 Option pertains to the response 241 payload. 243 Hence, for the methods defined in [I-D.ietf-core-coap], Block1 is 244 useful with the payload-bearing POST and PUT requests and their 245 responses. Block2 is useful with GET, POST, and PUT requests and 246 their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -- see 247 section "Payload" of [I-D.ietf-core-coap]). 249 Where Block1 is present in a request or Block2 in a response (i.e., 250 in that message to the payload of which it pertains) it indicates a 251 block-wise transfer and describes how this block-wise payload forms 252 part of the entire body being transferred ("descriptive usage"). 253 Where it is present in the opposite direction, it provides additional 254 control on how that payload will be formed or was processed ("control 255 usage"). 257 Implementation of either Block option is intended to be optional. 258 However, when it is present in a CoAP message, it MUST be processed 259 (or the message rejected); therefore it is identified as a critical 260 option. It MUST NOT occur more than once. 262 2.2. Structure of a Block Option 264 Three items of information may need to be transferred in a Block 265 (Block1 or Block2) option: 267 o The size of the block (SZX); 269 o whether more blocks are following (M); 271 o the relative number of the block (NUM) within a sequence of blocks 272 with the given size. 274 The value of the Block Option is a variable-size (0 to 3 byte) 275 unsigned integer (uint, see Appendix A of [I-D.ietf-core-coap]). 276 This integer value encodes these three fields, see Figure 1. (Due to 277 the CoAP uint encoding rules, when all of NUM, M, and SZX happen to 278 be zero, a zero-byte integer will be sent.) 280 0 281 0 1 2 3 4 5 6 7 282 +-+-+-+-+-+-+-+-+ 283 | NUM |M| SZX | 284 +-+-+-+-+-+-+-+-+ 285 0 1 286 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 287 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 288 | NUM |M| SZX | 289 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 291 0 1 2 292 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 293 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 294 | NUM |M| SZX | 295 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 297 Figure 1: Block option value 299 The block size is encoded using a three-bit unsigned integer (0 for 300 2**4 to 6 for 2**10 bytes), which we call the "SZX" ("size 301 exponent"); the actual block size is then "2**(SZX + 4)". SZX is 302 transferred in the three least significant bits of the option value 303 (i.e., "val & 7" where "val" is the value of the option). 305 The fourth least significant bit, the M or "more" bit ("val & 8"), 306 indicates whether more blocks are following or the current block-wise 307 transfer is the last block being transferred. 309 The option value divided by sixteen (the NUM field) is the sequence 310 number of the block currently being transferred, starting from zero. 311 The current transfer is therefore about the "size" bytes starting at 312 byte "NUM << (SZX + 4)". 314 Implementation note: As an implementation convenience, "(val & ~0xF) 315 << (val & 7)", i.e., the option value with the last 4 bits masked 316 out, shifted to the left by the value of SZX, gives the byte 317 position of the block being transferred. 319 More specifically, within the option value of a Block1 or Block2 320 Option, the meaning of the option fields is defined as follows: 322 NUM: Block Number, indicating the block number being requested or 323 provided. Block number 0 indicates the first block of a body 324 (i.e., starting with the first byte of the body). 326 M: More Flag (not last block). For descriptive usage, this flag, if 327 unset, indicates that the payload in this message is the last 328 block in the body; when set it indicates that there are one or 329 more additional blocks available. When a Block2 Option is used in 330 a request to retrieve a specific block number ("control usage"), 331 the M bit MUST be sent as zero and ignored on reception. (In a 332 Block1 Option in a response, the M flag is used to indicate 333 atomicity, see below.) 335 SZX: Block Size. The block size is represented as three-bit 336 unsigned integer indicating the size of a block to the power of 337 two. Thus block size = 2**(SZX + 4). The allowed values of SZX 338 are 0 to 6, i.e., the minimum block size is 2**(0+4) = 16 and the 339 maximum is 2**(6+4) = 1024. The value 7 for SZX (which would 340 indicate a block size of 2048) is reserved, i.e. MUST NOT be sent 341 and MUST lead to a 4.00 Bad Request response code upon reception 342 in a request. 344 There is no default value for the Block1 and Block2 Options. Absence 345 of one of these options is equivalent to an option value of 0 with 346 respect to the value of NUM and M that could be given in the option, 347 i.e. it indicates that the current block is the first and only block 348 of the transfer (block number 0, M bit not set). However, in 349 contrast to the explicit value 0, which would indicate an SZX of 0 350 and thus a size value of 16 bytes, there is no specific explicit size 351 implied by the absence of the option -- the size is left 352 unspecified. (As for any uint, the explicit value 0 is efficiently 353 indicated by a zero-length option; this, therefore, is different in 354 semantics from the absence of the option.) 356 2.3. Block Options in Requests and Responses 358 The Block options are used in one of three roles: 360 o In descriptive usage, i.e., a Block2 Option in a response (such as 361 a 2.05 response for GET), or a Block1 Option in a request (a PUT 362 or POST): 364 * The NUM field in the option value describes what block number 365 is contained in the payload of this message. 367 * The M bit indicates whether further blocks need to be 368 transferred to complete the transfer of that body. 370 * The block size given by SZX MUST match the size of the payload 371 in bytes, if the M bit is set. (SZX does not govern the 372 payload size if M is unset). For Block2, if the request 373 suggested a larger value of SZX, the next request MUST move SZX 374 down to the size given in the response. (The effect is that, 375 if the server uses the smaller of (1) its preferred block size 376 and (2) the block size requested, all blocks for a body use the 377 same block size.) 379 o A Block2 Option in control usage in a request (e.g., GET): 381 * The NUM field in the Block2 Option gives the block number of 382 the payload that is being requested to be returned in the 383 response. 385 * In this case, the M bit has no function and MUST be set to 386 zero. 388 * The block size given (SZX) suggests a block size (in the case 389 of block number 0) or repeats the block size of previous blocks 390 received (in the case of a non-zero block number). 392 o A Block1 Option in control usage in a response (e.g., a 2.xx 393 response for a PUT or POST request): 395 * The NUM field of the Block1 Option indicates what block number 396 is being acknowledged. 398 * If the M bit was set in the request, the server can choose 399 whether to act on each block separately, with no memory, or 400 whether to handle the request for the entire body atomically, 401 or any mix of the two. 403 + If the M bit is also set in the response, it indicates that 404 this response does not carry the final response code to the 405 request, i.e. the server collects further blocks from the 406 same endpoint and plans to implement the request atomically 407 (e.g., acts only upon reception of the last block of 408 payload). In this case, the response MUST NOT carry a 409 Block2 option. 411 + Conversely, if the M bit is unset even though it was set in 412 the request, it indicates the block-wise request was enacted 413 now specifically for this block, and the response carries 414 the final response to this request (and to any previous ones 415 with the M bit set in the response's Block1 Option in this 416 sequence of block-wise transfers); the client is still 417 expected to continue sending further blocks, the request 418 method for which may or may not also be enacted per-block. 420 * Finally, the SZX block size given in a control Block1 Option 421 indicates the largest block size preferred by the server for 422 transfers toward the resource that is the same or smaller than 423 the one used in the initial exchange; the client SHOULD use 424 this block size or a smaller one in all further requests in the 425 transfer sequence, even if that means changing the block size 426 (and possibly scaling the block number accordingly) from now 427 on. 429 Using one or both Block options, a single REST operation can be split 430 into multiple CoAP message exchanges. As specified in 431 [I-D.ietf-core-coap], each of these message exchanges uses their own 432 CoAP Message ID. 434 2.4. Using the Block2 Option 436 When a request is answered with a response carrying a Block2 Option 437 with the M bit set, the requester may retrieve additional blocks of 438 the resource representation by sending further requests with the same 439 options and a Block2 Option giving the block number and block size 440 desired. In a request, the client MUST set the M bit of a Block2 441 Option to zero and the server MUST ignore it on reception. 443 To influence the block size used in a response, the requester also 444 uses the Block2 Option, giving the desired size, a block number of 445 zero and an M bit of zero. A server MUST use the block size 446 indicated or a smaller size. Any further block-wise requests for 447 blocks beyond the first one MUST indicate the same block size that 448 was used by the server in the response for the first request that 449 gave a desired size using a Block2 Option. 451 Once the Block2 Option is used by the requester and a first response 452 has been received with a possibly adjusted block size, all further 453 requests in a single block-wise transfer SHOULD ultimately use the 454 same size, except that there may not be enough content to fill the 455 last block (the one returned with the M bit not set). (Note that the 456 client may start using the Block2 Option in a second request after a 457 first request without a Block2 Option resulted in a Block2 option in 458 the response.) The server SHOULD use the block size indicated in the 459 request option or a smaller size, but the requester MUST take note of 460 the actual block size used in the response it receives to its initial 461 request and proceed to use it in subsequent requests. The server 462 behavior MUST ensure that this client behavior results in the same 463 block size for all responses in a sequence (except for the last one 464 with the M bit not set, and possibly the first one if the initial 465 request did not contain a Block2 Option). 467 Block-wise transfers can be used to GET resources the representations 468 of which are entirely static (not changing over time at all, such as 469 in a schema describing a device), or for dynamically changing 470 resources. In the latter case, the Block2 Option SHOULD be used in 471 conjunction with the ETag Option, to ensure that the blocks being 472 reassembled are from the same version of the representation: The 473 server SHOULD include an ETag option in each response. If an ETag 474 option is available, the client's reassembler, when reassembling the 475 representation from the blocks being exchanged, MUST compare ETag 476 Options. If the ETag Options do not match in a GET transfer, the 477 requester has the option of attempting to retrieve fresh values for 478 the blocks it retrieved first. To minimize the resulting 479 inefficiency, the server MAY cache the current value of a 480 representation for an ongoing sequence of requests. (The server may 481 identify the sequence by the combination of the requesting end-point 482 and the URI being the same in each block-wise request.) Note well 483 that this specification makes no requirement for the server to 484 establish any state; however, servers that offer quickly changing 485 resources may thereby make it impossible for a client to ever 486 retrieve a consistent set of blocks. 488 2.5. Using the Block1 Option 490 In a request with a request payload (e.g., PUT or POST), the Block1 491 Option refers to the payload in the request (descriptive usage). 493 In response to a request with a payload (e.g., a PUT or POST 494 transfer), the block size given in the Block1 Option indicates the 495 block size preference of the server for this resource (control 496 usage). Obviously, at this point the first block has already been 497 transferred by the client without benefit of this knowledge. Still, 498 the client SHOULD heed the preference indicated and, for all further 499 blocks, use the block size preferred by the server or a smaller one. 500 Note that any reduction in the block size may mean that the second 501 request starts with a block number larger than one, as the first 502 request already transferred multiple blocks as counted in the smaller 503 size. 505 To counter the effects of adaptation layer fragmentation on packet 506 delivery probability, a client may want to give up retransmitting a 507 request with a relatively large payload even before MAX_RETRANSMIT 508 has been reached, and try restating the request as a block-wise 509 transfer with a smaller payload. Note that this new attempt is then 510 a new message-layer transaction and requires a new Message ID. 511 (Because of the uncertainty whether the request or the 512 acknowledgement was lost, this strategy is useful mostly for 513 idempotent requests.) 515 In a blockwise transfer of a request payload (e.g., a PUT or POST) 516 that is intended to be implemented in an atomic fashion at the 517 server, the actual creation/replacement takes place at the time the 518 final block, i.e. a block with the M bit unset in the Block1 Option, 519 is received. In this case, all success responses to non-final blocks 520 carry the response code 2.31 (Continue, Section 2.9.1). If not all 521 previous blocks are available at the server at the time of processing 522 the final block, the transfer fails and error code 4.08 (Request 523 Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY 524 also return a 4.08 error code for any (final or non-final) Block1 525 transfer that is not in sequence; clients that do not have specific 526 mechanisms to handle this case therefore SHOULD always start with 527 block zero and send the following blocks in order. 529 The error code 4.13 (Request Entity Too Large) can be returned at any 530 time by a server that does not currently have the resources to store 531 blocks for a block-wise request payload transfer that it would intend 532 to implement in an atomic fashion. (Note that a 4.13 response to a 533 request that does not employ Block1 is a hint for the client to try 534 sending Block1, and a 4.13 response with a smaller SZX in its Block1 535 option than requested is a hint to try a smaller SZX.) 537 The Block1 option provides no way for a single endpoint to perform 538 multiple concurrently proceeding block-wise request payload transfer 539 (e.g., PUT or POST) operations to the same resource. Starting a new 540 block-wise sequence of requests to the same resource (before an old 541 sequence from the same endpoint was finished) simply overwrites the 542 context the server may still be keeping. (This is probably exactly 543 what one wants in this case - the client may simply have restarted 544 and lost its knowledge of the previous sequence.) 546 2.6. Combining Blockwise Transfers with the Observe Option 548 The Observe Option provides a way for a client to be notified about 549 changes over time of a resource [I-D.ietf-core-observe]. Resources 550 observed by clients may be larger than can be comfortably processed 551 or transferred in one CoAP message. The following rules apply to the 552 combination of blockwise transfers with notifications. 554 Observation relationships always apply to an entire resource; the 555 Block2 option does not provide a way to observe a single block of a 556 resource. 558 As with basic GET transfers, the client can indicate its desired 559 block size in a Block2 Option in the GET request establishing or 560 renewing the observation relationship. If the server supports 561 blockwise transfers, it SHOULD take note of the block size and apply 562 it as a maximum size to all notifications/responses resulting from 563 the GET request (until the client is removed from the list of 564 observers or the entry in that list is updated by the server 565 receiving a new GET request for the resource from the client). 567 When sending a 2.05 (Content) notification, the server only sends the 568 first block of the representation. The client retrieves the rest of 569 the representation as if it had caused this first response by a GET 570 request, i.e., by using additional GET requests with Block2 options 571 containing NUM values greater than zero. (This results in the 572 transfer of the entire representation, even if only some of the 573 blocks have changed with respect to a previous notification.) 575 As with other dynamically changing resources, to ensure that the 576 blocks being reassembled are from the same version of the 577 representation, the server SHOULD include an ETag option in each 578 response, and the reassembling client MUST compare the ETag options 579 (Section 2.4). 581 See Section 3.4 for examples. 583 2.7. Combining Block1 and Block2 585 In PUT and particularly in POST exchanges, both the request body and 586 the response body may be large enough to require the use of block- 587 wise transfers. First, the Block1 transfer of the request body 588 proceeds as usual. In the exchange of the last slice of this block- 589 wise transfer, the response carries the first slice of the Block2 590 transfer (NUM is zero). To continue this Block2 transfer, the client 591 continues to send requests similar to the requests in the Block1 592 phase, but leaves out the Block1 options and includes a Block2 593 request option with non-zero NUM. 595 Block2 transfers that retrieve the response body for a request that 596 used Block1 MUST be performed in sequential order. 598 2.8. Combining Block2 with Multicast 600 A client can use the Block2 option in a multicast GET request with 601 NUM = 0 to aid in limiting the size of the response. 603 Similarly, a response to a multicast GET request can use a Block2 604 option with NUM = 0 if the representation is large, or to further 605 limit the size of the response. 607 In both cases, the client retrieves any further blocks using unicast 608 exchanges; in the unicast requests, the client SHOULD heed any block 609 size preferences indicated by the server in the response to the 610 multicast request. 612 Other uses of the Block options in conjunction with multicast 613 messages are for further study. 615 2.9. Response Codes 617 Two response codes are defined by this specification beyond those 618 already defined in [I-D.ietf-core-coap], and another response code is 619 extended in its meaning. 621 TODO: Add or appropriate useful response codes for Block2 problems 622 (overshoot beyond end of representation, unsupported out-of-order 623 access). 625 2.9.1. 2.31 Continue 627 This new success status code indicates that the transfer of this 628 block of the request body was successful and that the serve 629 encourages sending further blocks, but that a final outcome of the 630 whole block-wise request cannot yet be determined. No payload is 631 returned with this response code. 633 2.9.2. 4.08 Request Entity Incomplete 635 This new client error status code indicates that the server has not 636 received the blocks of the request body that it needs to proceed. 637 The client has not sent all blocks, not sent them in the order 638 required by the server, or has sent them long enough ago that the 639 server has already discarded them. 641 2.9.3. 4.13 Request Entity Too Large 643 In [I-D.ietf-core-coap], section 5.9.2.9, the response code 4.13 644 (Request Entity Too Large) is defined to be like HTTP 413 "Request 645 Entity Too Large". [I-D.ietf-core-coap] also recommends that this 646 response SHOULD include a Size1 Option Section 4 to indicate the 647 maximum size of request entity the server is able and willing to 648 handle, unless the server is not in a position to make this 649 information available. 651 The present specification allows the server to return this response 652 code at any time during a Block1 transfer to indicate that it does 653 not currently have the resources to store blocks for a transfer that 654 it would intend to implement in an atomic fashion. It also allows 655 the server to return a 4.13 response to a request that does not 656 employ Block1 as a hint for the client to try sending Block1. 657 Finally, a 4.13 response to a request with a Block1 option (control 658 usage, see Section 2.3) where the response carries a smaller SZX in 659 its Block1 option is a hint to try that smaller SZX. 661 3. Examples 662 This section gives a number of short examples with message flows for 663 a block-wise GET, and for a PUT or POST. These examples demonstrate 664 the basic operation, the operation in the presence of 665 retransmissions, and examples for the operation of the block size 666 negotiation. 668 In all these examples, a Block option is shown in a decomposed way 669 indicating the kind of Block option (1 or 2) followed by a colon, and 670 then the block number (NUM), more bit (M), and block size exponent 671 (2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33 672 would be shown as 2:2/0/32), or a Block1 Option value of 59 would be 673 shown as 1:3/1/128. 675 3.1. Block2 Examples 677 The first example (Figure 2) shows a GET request that is split into 678 three blocks. The server proposes a block size of 128, and the 679 client agrees. The first two ACKs contain 128 bytes of payload each, 680 and third ACK contains between 1 and 128 bytes. 682 CLIENT SERVER 683 | | 684 | CON [MID=1234], GET, /status ------> | 685 | | 686 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 687 | | 688 | CON [MID=1235], GET, /status, 2:1/0/128 ------> | 689 | | 690 | <------ ACK [MID=1235], 2.05 Content, 2:1/1/128 | 691 | | 692 | CON [MID=1236], GET, /status, 2:2/0/128 ------> | 693 | | 694 | <------ ACK [MID=1236], 2.05 Content, 2:2/0/128 | 696 Figure 2: Simple blockwise GET 698 In the second example (Figure 3), the client anticipates the 699 blockwise transfer (e.g., because of a size indication in the link- 700 format description [RFC6690]) and sends a size proposal. All ACK 701 messages except for the last carry 64 bytes of payload; the last one 702 carries between 1 and 64 bytes. 704 CLIENT SERVER 705 | | 706 | CON [MID=1234], GET, /status, 2:0/0/64 ------> | 707 | | 708 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/64 | 709 | | 710 | CON [MID=1235], GET, /status, 2:1/0/64 ------> | 711 | | 712 | <------ ACK [MID=1235], 2.05 Content, 2:1/1/64 | 713 : : 714 : ... : 715 : : 716 | CON [MID=1238], GET, /status, 2:4/0/64 ------> | 717 | | 718 | <------ ACK [MID=1238], 2.05 Content, 2:4/1/64 | 719 | | 720 | CON [MID=1239], GET, /status, 2:5/0/64 ------> | 721 | | 722 | <------ ACK [MID=1239], 2.05 Content, 2:5/0/64 | 724 Figure 3: Blockwise GET with early negotiation 726 In the third example (Figure 4), the client is surprised by the need 727 for a blockwise transfer, and unhappy with the size chosen 728 unilaterally by the server. As it did not send a size proposal 729 initially, the negotiation only influences the size from the second 730 message exchange onward. Since the client already obtained both the 731 first and second 64-byte block in the first 128-byte exchange, it 732 goes on requesting the third 64-byte block ("2/0/64"). None of this 733 is (or needs to be) understood by the server, which simply responds 734 to the requests as it best can. 736 CLIENT SERVER 737 | | 738 | CON [MID=1234], GET, /status ------> | 739 | | 740 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 741 | | 742 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 743 | | 744 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 745 | | 746 | CON [MID=1236], GET, /status, 2:3/0/64 ------> | 747 | | 748 | <------ ACK [MID=1236], 2.05 Content, 2:3/1/64 | 749 | | 750 | CON [MID=1237], GET, /status, 2:4/0/64 ------> | 751 | | 752 | <------ ACK [MID=1237], 2.05 Content, 2:4/1/64 | 753 | | 754 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 755 | | 756 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 758 Figure 4: Blockwise GET with late negotiation 760 In all these (and the following) cases, retransmissions are handled 761 by the CoAP message exchange layer, so they don't influence the block 762 operations (Figure 5, Figure 6). 764 CLIENT SERVER 765 | | 766 | CON [MID=1234], GET, /status ------> | 767 | | 768 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 769 | | 770 | CON [MID=1235], GE///////////////////////// | 771 | | 772 | (timeout) | 773 | | 774 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 775 | | 776 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 777 : : 778 : ... : 779 : : 780 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 781 | | 782 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 784 Figure 5: Blockwise GET with late negotiation and lost CON 786 CLIENT SERVER 787 | | 788 | CON [MID=1234], GET, /status ------> | 789 | | 790 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 791 | | 792 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 793 | | 794 | //////////////////////////////////tent, 2:2/1/64 | 795 | | 796 | (timeout) | 797 | | 798 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 799 | | 800 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 801 : : 802 : ... : 803 : : 804 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 805 | | 806 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 808 Figure 6: Blockwise GET with late negotiation and lost ACK 810 3.2. Block1 Examples 811 The following examples demonstrate a PUT exchange; a POST exchange 812 looks the same, with different requirements on atomicity/idempotence. 813 Note that, similar to GET, the responses to the requests that have a 814 more bit in the request Block1 Option are provisional and carry the 815 response code 2.31 (Continue); only the final response tells the 816 client that the PUT did succeed. 818 CLIENT SERVER 819 | | 820 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 821 | | 822 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 823 | | 824 | CON [MID=1235], PUT, /options, 1:1/1/128 ------> | 825 | | 826 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 827 | | 828 | CON [MID=1236], PUT, /options, 1:2/0/128 ------> | 829 | | 830 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | 832 Figure 7: Simple atomic blockwise PUT 834 A stateless server that simply builds/updates the resource in place 835 (statelessly) may indicate this by not setting the more bit in the 836 response (Figure 8); in this case, the response codes are valid 837 separately for each block being updated. This is of course only an 838 acceptable behavior of the server if the potential inconsistency 839 present during the run of the message exchange sequence does not lead 840 to problems, e.g. because the resource being created or changed is 841 not yet or not currently in use. 843 CLIENT SERVER 844 | | 845 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 846 | | 847 | <------ ACK [MID=1234], 2.04 Changed, 1:0/0/128 | 848 | | 849 | CON [MID=1235], PUT, /options, 1:1/1/128 ------> | 850 | | 851 | <------ ACK [MID=1235], 2.04 Changed, 1:1/0/128 | 852 | | 853 | CON [MID=1236], PUT, /options, 1:2/0/128 ------> | 854 | | 855 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | 857 Figure 8: Simple stateless blockwise PUT 859 Finally, a server receiving a blockwise PUT or POST may want to 860 indicate a smaller block size preference (Figure 9). In this case, 861 the client SHOULD continue with a smaller block size; if it does, it 862 MUST adjust the block number to properly count in that smaller size. 864 CLIENT SERVER 865 | | 866 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 867 | | 868 | <------ ACK [MID=1234], 2.04 Changed, 1:0/1/32 | 869 | | 870 | CON [MID=1235], PUT, /options, 1:4/1/32 ------> | 871 | | 872 | <------ ACK [MID=1235], 2.04 Changed, 1:4/1/32 | 873 | | 874 | CON [MID=1236], PUT, /options, 1:5/1/32 ------> | 875 | | 876 | <------ ACK [MID=1235], 2.04 Changed, 1:5/1/32 | 877 | | 878 | CON [MID=1237], PUT, /options, 1:6/0/32 ------> | 879 | | 880 | <------ ACK [MID=1236], 2.04 Changed, 1:6/0/32 | 882 Figure 9: Simple atomic blockwise PUT with negotiation 884 3.3. Combining Block1 and Block2 886 Block options may be used in both directions of a single exchange. 887 The following example demonstrates a blockwise POST request, 888 resulting in a separate blockwise response. 890 CLIENT SERVER 891 | | 892 | CON [MID=1234], POST, /soap, 1:0/1/128 ------> | 893 | | 894 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 895 | | 896 | CON [MID=1235], POST, /soap, 1:1/1/128 ------> | 897 | | 898 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 899 | | 900 | CON [MID=1236], POST, /soap, 1:2/0/128 ------> | 901 | | 902 | <------ ACK [MID=1236], 2.04 Changed, 2:0/1/128, 1:2/0/128 | 903 | | 904 | CON [MID=1237], POST, /soap, 2:1/0/128 ------> | 905 | (no payload for requests with Block2 with NUM != 0) | 906 | (could also do late negotiation by requesting e.g. 2:2/0/64) | 907 | | 908 | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/128 | 909 | | 910 | CON [MID=1238], POST, /soap, 2:2/0/128 ------> | 911 | | 912 | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/128 | 913 | | 914 | CON [MID=1239], POST, /soap, 2:3/0/128 ------> | 915 | | 916 | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/128 | 918 Figure 10: Atomic blockwise POST with blockwise response 920 This model does provide for early negotiation input to the Block2 921 blockwise transfer, as shown below. 923 CLIENT SERVER 924 | | 925 | CON [MID=1234], POST, /soap, 1:0/1/128 ------> | 926 | | 927 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 928 | | 929 | CON [MID=1235], POST, /soap, 1:1/1/128 ------> | 930 | | 931 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 932 | | 933 | CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------> | 934 | | 935 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 | 936 | | 937 | CON [MID=1237], POST, /soap, 2:1/0/64 ------> | 938 | (no payload for requests with Block2 with NUM != 0) | 939 | | 940 | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/64 | 941 | | 942 | CON [MID=1238], POST, /soap, 2:2/0/64 ------> | 943 | | 944 | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/64 | 945 | | 946 | CON [MID=1239], POST, /soap, 2:3/0/64 ------> | 947 | | 948 | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/64 | 950 Figure 11: Atomic blockwise POST with blockwise response, early 951 negotiation 953 3.4. Combining Observe and Block2 954 In the following example, the server first sends a direct response 955 (Observe sequence number 62350) to the initial GET request (the 956 resulting blockwise transfer is as in Figure 4 and has therefore been 957 left out). The second transfer is started by a 2.05 notification 958 that contains just the first block (Observe sequence number 62354); 959 the client then goes on to obtain the rest of the blocks. 961 CLIENT SERVER 962 | | 963 +----->| Header: GET 0x41011636 964 | GET | Token: 0xfb 965 | | Uri-Path: status-icon 966 | | Observe: (empty) 967 | | 968 |<-----+ Header: 2.05 0x61451636 969 | 2.05 | Token: 0xfb 970 | | Block2: 0/1/128 971 | | Observe: 62350 972 | | ETag: 6f00f38e 973 | | Payload: [128 bytes] 974 | | 975 | | (Usual GET transfer left out) 976 ... 977 | | (Notification of first block:) 978 | | 979 |<-----+ Header: 2.05 0x4145af9c 980 | 2.05 | Token: 0xfb 981 | | Block2: 0/1/128 982 | | Observe: 62354 983 | | ETag: 6f00f392 984 | | Payload: [128 bytes] 985 | | 986 +- - ->| Header: 0x6000af9c 987 | | 988 | | (Retrieval of remaining blocks) 989 | | 990 +----->| Header: GET 0x41011637 991 | GET | Token: 0xfc 992 | | Uri-Path: status-icon 993 | | Block2: 1/0/128 994 | | 995 |<-----+ Header: 2.05 0x61451637 996 | 2.05 | Token: 0xfc 997 | | Block2: 1/1/128 998 | | ETag: 6f00f392 999 | | Payload: [128 bytes] 1000 | | 1001 +----->| Header: GET 0x41011638 1002 | GET | Token: 0xfc 1003 | | Uri-Path: status-icon 1004 | | Block2: 2/0/128 1005 | | 1006 |<-----+ Header: 2.05 0x61451638 1007 | 2.05 | Token: 0xfc 1008 | | Block2: 2/0/128 1009 | | ETag: 6f00f392 1010 | | Payload: [53 bytes] 1012 Figure 12: Observe sequence with blockwise response 1014 In the following example, the client also uses early negotiation to 1015 limit the block size to 64 bytes. 1017 CLIENT SERVER 1018 | | 1019 +----->| Header: GET 0x41011636 1020 | GET | Token: 0xfb 1021 | | Uri-Path: status-icon 1022 | | Observe: (empty) 1023 | | Block2: 0/0/64 1024 | | 1025 |<-----+ Header: 2.05 0x61451636 1026 | 2.05 | Token: 0xfb 1027 | | Block2: 0/1/64 1028 | | Observe: 62350 1029 | | ETag: 6f00f38e 1030 | | Max-Age: 60 1031 | | Payload: [64 bytes] 1032 | | 1033 | | (Usual GET transfer left out) 1034 ... 1035 | | (Notification of first block:) 1036 | | 1037 |<-----+ Header: 2.05 0x4145af9c 1038 | 2.05 | Token: 0xfb 1039 | | Block2: 0/1/64 1040 | | Observe: 62354 1041 | | ETag: 6f00f392 1042 | | Payload: [64 bytes] 1043 | | 1044 +- - ->| Header: 0x6000af9c 1045 | | 1046 | | (Retrieval of remaining blocks) 1047 | | 1048 +----->| Header: GET 0x41011637 1049 | GET | Token: 0xfc 1050 | | Uri-Path: status-icon 1051 | | Block2: 1/0/64 1052 | | 1053 |<-----+ Header: 2.05 0x61451637 1054 | 2.05 | Token: 0xfc 1055 | | Block2: 1/1/64 1056 | | ETag: 6f00f392 1057 | | Payload: [64 bytes] 1058 .... 1059 | | 1060 +----->| Header: GET 0x41011638 1061 | GET | Token: 0xfc 1062 | | Uri-Path: status-icon 1063 | | Block2: 4/0/64 1064 | | 1065 |<-----+ Header: 2.05 0x61451638 1066 | 2.05 | Token: 0xfc 1067 | | Block2: 4/0/64 1068 | | ETag: 6f00f392 1069 | | Payload: [53 bytes] 1071 Figure 13: Observe sequence with early negotiation 1073 4. The Size2 and Size1 Options 1075 In many cases when transferring a large resource representation block 1076 by block, it is advantageous to know the total size early in the 1077 process. Some indication may be available from the maximum size 1078 estimate attribute "sz" provided in a resource description [RFC6690]. 1079 However, the size may vary dynamically, so a more up-to-date 1080 indication may be useful. 1082 This specification defines two CoAP Options, Size1 for indicating the 1083 size of the representation transferred in requests, and Size2 for 1084 indicating the size of the representation transferred in responses. 1086 The Size2 Option may be used for two purposes: 1088 o in a request, to ask the server to provide a size estimate along 1089 with the usual response ("size request"). For this usage, the 1090 value MUST be set to 0. 1092 o in a response carrying a Block2 Option, to indicate the current 1093 estimate the server has of the total size of the resource 1094 representation, measured in bytes ("size indication"). 1096 Similarly, the Size1 Option may be used for two purposes: 1098 o in a request carrying a Block1 Option, to indicate the current 1099 estimate the client has of the total size of the resource 1100 representation, measured in bytes ("size indication"). 1102 o in a 4.13 response, to indicate the maximum size that would have 1103 been acceptable [I-D.ietf-core-coap], measured in bytes. 1105 Apart from conveying/asking for size information, the Size options 1106 have no other effect on the processing of the request or response. 1107 If the client wants to minimize the size of the payload in the 1108 resulting response, it should add a Block2 option to the request with 1109 a small block size (e.g., setting SZX=0). 1111 The Size Options are "elective", i.e., a client MUST be prepared for 1112 the server to ignore the size estimate request. The Size Options 1113 MUST NOT occur more than once. 1115 +------+---+---+---+---+-------+--------+--------+---------+ 1116 | Type | C | U | N | R | Name | Format | Length | Default | 1117 +------+---+---+---+---+-------+--------+--------+---------+ 1118 | 60 | | | x | | Size1 | uint | 0-4 B | (none) | 1119 | | | | | | | | | | 1120 | 28 | | | x | | Size2 | uint | 0-4 B | (none) | 1121 +------+---+---+---+---+-------+--------+--------+---------+ 1123 Table 2: Size Option Numbers 1125 Implementation Notes: 1127 o As a quality of implementation consideration, blockwise transfers 1128 for which the total size considerably exceeds the size of one 1129 block are expected to include size indications, whenever those can 1130 be provided without undue effort (preferably with the first block 1131 exchanged). If the size estimate does not change, the indication 1132 does not need to be repeated for every block. 1134 o The end of a blockwise transfer is governed by the M bits in the 1135 Block Options, _not_ by exhausting the size estimates exchanged. 1137 o As usual for an option of type uint, the value 0 is best expressed 1138 as an empty option (0 bytes). There is no default value. 1140 o The Size Options are neither critical nor unsafe, and are marked 1141 as No-Cache-Key. 1143 5. HTTP Mapping Considerations 1144 In this subsection, we give some brief examples for the influence the 1145 Block options might have on intermediaries that map between CoAP and 1146 HTTP. 1148 For mapping CoAP requests to HTTP, the intermediary may want to map 1149 the sequence of block-wise transfers into a single HTTP transfer. 1150 E.g., for a GET request, the intermediary could perform the HTTP 1151 request once the first block has been requested and could then 1152 fulfill all further block requests out of its cache. A constrained 1153 implementation may not be able to cache the entire object and may use 1154 a combination of TCP flow control and (in particular if timeouts 1155 occur) HTTP range requests to obtain the information necessary for 1156 the next block transfer at the right time. 1158 For PUT or POST requests, there is more variation in how HTTP servers 1159 might implement ranges. Some WebDAV servers do, but in general the 1160 CoAP-to-HTTP intermediary will have to try sending the payload of all 1161 the blocks of a block-wise transfer within one HTTP request. If 1162 enough buffering is available, this request can be started when the 1163 last CoAP block is received. A constrained implementation may want 1164 to relieve its buffering by already starting to send the HTTP request 1165 at the time the first CoAP block is received; any HTTP 408 status 1166 code that indicates that the HTTP server became impatient with the 1167 resulting transfer can then be mapped into a CoAP 4.08 response code 1168 (similarly, 413 maps to 4.13). 1170 For mapping HTTP to CoAP, the intermediary may want to map a single 1171 HTTP transfer into a sequence of block-wise transfers. If the HTTP 1172 client is too slow delivering a request body on a PUT or POST, the 1173 CoAP server might time out and return a 4.08 response code, which in 1174 turn maps well to an HTTP 408 status code (again, 4.13 maps to 413). 1175 HTTP range requests received on the HTTP side may be served out of a 1176 cache and/or mapped to GET requests that request a sequence of blocks 1177 overlapping the range. 1179 (Note that, while the semantics of CoAP 4.08 and HTTP 408 differ, 1180 this difference is largely due to the different way the two protocols 1181 are mapped to transport. HTTP has an underlying TCP connection, 1182 which supplies connection state, so a HTTP 408 status code can 1183 immediately be used to indicate that a timeout occurred during 1184 transmitting a request through that active TCP connection. The CoAP 1185 4.08 response code indicates one or more missing blocks, which may be 1186 due to timeouts or resource constraints; as there is no connection 1187 state, there is no way to deliver such a response immediately; 1188 instead, it is delivered on the next block transfer. Still, HTTP 408 1189 is probably the best mapping back to HTTP, as the timeout is the most 1190 likely cause for a CoAP 4.08. Note that there is no way to 1191 distinguish a timeout from a missing block for a server without 1192 creating additional state, the need for which we want to avoid.) 1194 6. IANA Considerations 1196 This draft adds the following option numbers to the CoAP Option 1197 Numbers registry of [I-D.ietf-core-coap]: 1199 +--------+--------+-----------+ 1200 | Number | Name | Reference | 1201 +--------+--------+-----------+ 1202 | 23 | Block2 | [RFCXXXX] | 1203 | | | | 1204 | 27 | Block1 | [RFCXXXX] | 1205 | | | | 1206 | 28 | Size2 | [RFCXXXX] | 1207 | | | | 1208 | 60 | Size1 | [RFCXXXX] | 1209 +--------+--------+-----------+ 1211 Table 3: CoAP Option Numbers 1213 This draft adds the following response code to the CoAP Response 1214 Codes registry of [I-D.ietf-core-coap]: 1216 +------+---------------------------+-----------+ 1217 | Code | Description | Reference | 1218 +------+---------------------------+-----------+ 1219 | 2.31 | Continue | [RFCXXXX] | 1220 | | | | 1221 | 4.08 | Request Entity Incomplete | [RFCXXXX] | 1222 +------+---------------------------+-----------+ 1224 Table 4: CoAP Response Codes 1226 7. Security Considerations 1228 Providing access to blocks within a resource may lead to surprising 1229 vulnerabilities. Where requests are not implemented atomically, an 1230 attacker may be able to exploit a race condition or confuse a server 1231 by inducing it to use a partially updated resource representation. 1232 Partial transfers may also make certain problematic data invisible to 1233 intrusion detection systems; it is RECOMMENDED that an intrusion 1234 detection system (IDS) that analyzes resource representations 1235 transferred by CoAP implement the Block options to gain access to 1236 entire resource representations. Still, approaches such as 1237 transferring even-numbered blocks on one path and odd-numbered blocks 1238 on another path, or even transferring blocks multiple times with 1239 different content and obtaining a different interpretation of 1240 temporal order at the IDS than at the server, may prevent an IDS from 1241 seeing the whole picture. These kinds of attacks are well understood 1242 from IP fragmentation and TCP segmentation; CoAP does not add 1243 fundamentally new considerations. 1245 Where access to a resource is only granted to clients making use of a 1246 specific security association, all blocks of that resource MUST be 1247 subject to the same security checks; it MUST NOT be possible for 1248 unprotected exchanges to influence blocks of an otherwise protected 1249 resource. As a related consideration, where object security is 1250 employed, PUT/POST should be implemented in the atomic fashion, 1251 unless the object security operation is performed on each access and 1252 the creation of unusable resources can be tolerated. 1254 A stateless server might be susceptible to an attack where the 1255 adversary sends a Block1 (e.g., PUT) block with a high block number: 1256 A naive implementation might exhaust its resources by creating a huge 1257 resource representation. 1259 Misleading size indications may be used by an attacker to induce 1260 buffer overflows in poor implementations, for which the usual 1261 considerations apply. 1263 7.1. Mitigating Resource Exhaustion Attacks 1265 Certain blockwise requests may induce the server to create state, 1266 e.g. to create a snapshot for the blockwise GET of a fast-changing 1267 resource to enable consistent access to the same version of a 1268 resource for all blocks, or to create temporary resource 1269 representations that are collected until pressed into service by a 1270 final PUT or POST with the more bit unset. All mechanisms that 1271 induce a server to create state that cannot simply be cleaned up 1272 create opportunities for denial-of-service attacks. Servers SHOULD 1273 avoid being subject to resource exhaustion based on state created by 1274 untrusted sources. But even if this is done, the mitigation may 1275 cause a denial-of-service to a legitimate request when it is drowned 1276 out by other state-creating requests. Wherever possible, servers 1277 should therefore minimize the opportunities to create state for 1278 untrusted sources, e.g. by using stateless approaches. 1280 Performing segmentation at the application layer is almost always 1281 better in this respect than at the transport layer or lower (IP 1282 fragmentation, adaptation layer fragmentation), e.g. because there is 1283 application layer semantics that can be used for mitigation or 1284 because lower layers provide security associations that can prevent 1285 attacks. However, it is less common to apply timeouts and keepalive 1286 mechanisms at the application layer than at lower layers. Servers 1287 MAY want to clean up accumulated state by timing it out (cf. response 1288 code 4.08), and clients SHOULD be prepared to run blockwise transfers 1289 in an expedient way to minimize the likelihood of running into such a 1290 timeout. 1292 7.2. Mitigating Amplification Attacks 1294 [I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points 1295 for use in amplification attacks. 1297 A CoAP server can reduce the amount of amplification it provides to 1298 an attacker by offering large resource representations only in 1299 relatively small blocks. With this, e.g., for a 1000 byte resource, 1300 a 10-byte request might result in an 80-byte response (with a 64-byte 1301 block) instead of a 1016-byte response, considerably reducing the 1302 amplification provided. 1304 8. Acknowledgements 1306 Much of the content of this draft is the result of discussions with 1307 the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions. 1309 Charles Palmer provided extensive editorial comments to a previous 1310 version of this draft, some of which the authors hope to have covered 1311 in this version. Esko Dijk reviewed a more recent version, leading 1312 to a number of further editorial improvements, a solution to the 4.13 1313 ambiguity problem, and the section about combining Block and 1314 multicast. Markus Becker proposed getting rid of an ill-conceived 1315 default value for the Block2 and Block1 options. Peter Bigot 1316 insisted on a more systematic coverage of the options and response 1317 code. 1319 Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of 1320 the Size Option, which has informed this draft. Klaus Hartke wrote 1321 some of the text describing the interaction of Block2 with Observe. 1323 Matthias Kovatsch provided a number of significant simplifications of 1324 the protocol. 1326 9. References 1328 9.1. Normative References 1330 [I-D.ietf-core-coap] 1331 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 1332 Application Protocol (CoAP)", draft-ietf-core-coap-18 1333 (work in progress), June 2013. 1335 [I-D.ietf-core-observe] 1336 Hartke, K., "Observing Resources in CoAP", draft-ietf- 1337 core-observe-11 (work in progress), October 2013. 1339 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1340 Requirement Levels", BCP 14, RFC 2119, March 1997. 1342 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1343 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1344 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1346 9.2. Informative References 1348 [REST] Fielding, R., "Architectural Styles and the Design of 1349 Network-based Software Architectures", Ph.D. Dissertation, 1350 University of California, Irvine, 2000, . 1354 [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6 1355 over Low-Power Wireless Personal Area Networks (6LoWPANs): 1356 Overview, Assumptions, Problem Statement, and Goals", RFC 1357 4919, August 2007. 1359 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1360 Format", RFC 6690, August 2012. 1362 Authors' Addresses 1363 Carsten Bormann 1364 Universitaet Bremen TZI 1365 Postfach 330440 1366 Bremen D-28359 1367 Germany 1369 Phone: +49-421-218-63921 1370 Email: cabo@tzi.org 1372 Zach Shelby (editor) 1373 Sensinode 1374 Kidekuja 2 1375 Vuokatti 88600 1376 Finland 1378 Phone: +358407796297 1379 Email: zach@sensinode.com