idnits 2.17.1 draft-ietf-core-block-15.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 (July 04, 2014) is 3583 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 1229, but not defined == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-14 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). 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: January 5, 2015 ARM 6 July 04, 2014 8 Blockwise transfers in CoAP 9 draft-ietf-core-block-15 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 firmware 18 updates. With HTTP, TCP does the grunt work of slicing large 19 payloads up into multiple packets and ensuring that they all arrive 20 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 January 5, 2015. 57 Copyright Notice 59 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 89 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 15 90 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 19 91 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 20 92 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 22 93 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 25 94 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 26 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 28 97 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 29 98 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 29 99 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 100 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 101 9.1. Normative References . . . . . . . . . . . . . . . . . . 30 102 9.2. Informative References . . . . . . . . . . . . . . . . . 30 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 105 1. Introduction 107 The work on Constrained RESTful Environments (CoRE) aims at realizing 108 the REST architecture in a suitable form for the most constrained 109 nodes (such as microcontrollers with limited RAM and ROM [RFC7228]) 110 and networks (such as 6LoWPAN, [RFC4944]) [RFC7252]. The CoAP 111 protocol is intended to provide RESTful [REST] services not unlike 112 HTTP [RFC7230], while reducing the complexity of implementation as 113 well as the size of packets exchanged in order to make these services 114 useful in a highly constrained network of themselves highly 115 constrained nodes. 117 This objective requires restraint in a number of sometimes 118 conflicting ways: 120 o reducing implementation complexity in order to minimize code size, 122 o reducing message sizes in order to minimize the number of 123 fragments needed for each message (in turn to maximize the 124 probability of delivery of the message), the amount of 125 transmission power needed and the loading of the limited-bandwidth 126 channel, 128 o reducing requirements on the environment such as stable storage, 129 good sources of randomness or user interaction capabilities. 131 CoAP is based on datagram transports such as UDP, which limit the 132 maximum size of resource representations that can be transferred 133 without creating unreasonable levels of IP fragmentation. In 134 addition, not all resource representations will fit into a single 135 link layer packet of a constrained network, which may cause 136 adaptation layer fragmentation even if IP layer fragmentation is not 137 required. Using fragmentation (either at the adaptation layer or at 138 the IP layer) for the transport of larger representations would be 139 possible up to the maximum size of the underlying datagram protocol 140 (such as UDP), but the fragmentation/reassembly process burdens the 141 lower layers with conversation state that is better managed in the 142 application layer. 144 The present specification defines a pair of CoAP options to enable 145 _block-wise_ access to resource representations. The Block options 146 provide a minimal way to transfer larger resource representations in 147 a block-wise fashion. The overriding objective is to avoid the need 148 for creating conversation state at the server for block-wise GET 149 requests. (It is impossible to fully avoid creating conversation 150 state for POST/PUT, if the creation/replacement of resources is to be 151 atomic; where that property is not needed, there is no need to create 152 server conversation state in this case, either.) 154 In summary, this specification adds a pair of Block options to CoAP 155 that can be used for block-wise transfers. Benefits of using these 156 options include: 158 o Transfers larger than what can be accommodated in constrained- 159 network link-layer packets can be performed in smaller blocks. 161 o No hard-to-manage conversation state is created at the adaptation 162 layer or IP layer for fragmentation. 164 o The transfer of each block is acknowledged, enabling individual 165 retransmission if required. 167 o Both sides have a say in the block size that actually will be 168 used. 170 o The resulting exchanges are easy to understand using packet 171 analyzer tools and thus quite accessible to debugging. 173 o If needed, the Block options can also be used (without changes) to 174 provide random access to power-of-two sized blocks within a 175 resource representation. 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in RFC 180 2119, BCP 14 [RFC2119] and indicate requirement levels for compliant 181 CoAP implementations. 183 In this document, the term "byte" is used in its now customary sense 184 as a synonym for "octet". 186 Where bit arithmetic is explained, this document uses the notation 187 familiar from the programming language C, except that the operator 188 "**" stands for exponentiation. 190 2. Block-wise transfers 192 As discussed in the introduction, there are good reasons to limit the 193 size of datagrams in constrained networks: 195 o by the maximum datagram size (~ 64 KiB for UDP) 197 o by the desire to avoid IP fragmentation (MTU of 1280 for IPv6) 199 o by the desire to avoid adaptation layer fragmentation (60-80 bytes 200 for 6LoWPAN [RFC4919]) 202 When a resource representation is larger than can be comfortably 203 transferred in the payload of a single CoAP datagram, a Block option 204 can be used to indicate a block-wise transfer. As payloads can be 205 sent both with requests and with responses, this specification 206 provides two separate options for each direction of payload transfer. 207 In identifying these options, we use the number 1 to refer to the 208 transfer of the resource representation that pertains to the request, 209 and the number 2 to refer to the transfer of the resource 210 representation for the response. 212 In the following, the term "payload" will be used for the actual 213 content of a single CoAP message, i.e. a single block being 214 transferred, while the term "body" will be used for the entire 215 resource representation that is being transferred in a block-wise 216 fashion. The Content-Format option applies to the body, not to the 217 payload, in particular the boundaries between the blocks may be in 218 places that are not separating whole units in terms of the structure, 219 encoding, or content-coding used by the Content-Format. 221 In most cases, all blocks being transferred for a body (except for 222 the last one) will be of the same size. The block size is not fixed 223 by the protocol. To keep the implementation as simple as possible, 224 the Block options support only a small range of power-of-two block 225 sizes, from 2**4 (16) to 2**10 (1024) bytes. As bodies often will 226 not evenly divide into the power-of-two block size chosen, the size 227 need not be reached in the final block (but even for the final block, 228 the chosen power-of-two size will still be indicated in the block 229 size field of the Block option). 231 2.1. The Block2 and Block1 Options 232 +-----+---+---+---+---+--------+--------+--------+---------+ 233 | No. | C | U | N | R | Name | Format | Length | Default | 234 +-----+---+---+---+---+--------+--------+--------+---------+ 235 | 23 | C | U | - | - | Block2 | uint | 0-3 | (none) | 236 | | | | | | | | | | 237 | 27 | C | U | - | - | Block1 | uint | 0-3 | (none) | 238 +-----+---+---+---+---+--------+--------+--------+---------+ 240 Table 1: Block Option Numbers 242 Both Block1 and Block2 options can be present both in request and 243 response messages. In either case, the Block1 Option pertains to the 244 request payload, and the Block2 Option pertains to the response 245 payload. 247 Hence, for the methods defined in [RFC7252], Block1 is useful with 248 the payload-bearing POST and PUT requests and their responses. 249 Block2 is useful with GET, POST, and PUT requests and their payload- 250 bearing responses (2.01, 2.02, 2.04, 2.05 -- see section "Payload" of 251 [RFC7252]). 253 Where Block1 is present in a request or Block2 in a response (i.e., 254 in that message to the payload of which it pertains) it indicates a 255 block-wise transfer and describes how this specific block-wise 256 payload forms part of the entire body being transferred ("descriptive 257 usage"). Where it is present in the opposite direction, it provides 258 additional control on how that payload will be formed or was 259 processed ("control usage"). 261 Implementation of either Block option is intended to be optional. 262 However, when it is present in a CoAP message, it MUST be processed 263 (or the message rejected); therefore it is identified as a critical 264 option. It MUST NOT occur more than once. 266 2.2. Structure of a Block Option 268 Three items of information may need to be transferred in a Block 269 (Block1 or Block2) option: 271 o The size of the block (SZX); 273 o whether more blocks are following (M); 275 o the relative number of the block (NUM) within a sequence of blocks 276 with the given size. 278 The value of the Block Option is a variable-size (0 to 3 byte) 279 unsigned integer (uint, see Section 3.2 of [RFC7252]). This integer 280 value encodes these three fields, see Figure 1. (Due to the CoAP 281 uint encoding rules, when all of NUM, M, and SZX happen to be zero, a 282 zero-byte integer will be sent.) 284 0 285 0 1 2 3 4 5 6 7 286 +-+-+-+-+-+-+-+-+ 287 | NUM |M| SZX | 288 +-+-+-+-+-+-+-+-+ 290 0 1 291 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 292 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 293 | NUM |M| SZX | 294 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 296 0 1 2 297 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 298 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 299 | NUM |M| SZX | 300 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 302 Figure 1: Block option value 304 The block size is encoded using a three-bit unsigned integer (0 for 305 2**4 to 6 for 2**10 bytes), which we call the "SZX" ("size 306 exponent"); the actual block size is then "2**(SZX + 4)". SZX is 307 transferred in the three least significant bits of the option value 308 (i.e., "val & 7" where "val" is the value of the option). 310 The fourth least significant bit, the M or "more" bit ("val & 8"), 311 indicates whether more blocks are following or the current block-wise 312 transfer is the last block being transferred. 314 The option value divided by sixteen (the NUM field) is the sequence 315 number of the block currently being transferred, starting from zero. 316 The current transfer is therefore about the "size" bytes starting at 317 byte "NUM << (SZX + 4)". 319 Implementation note: As an implementation convenience, "(val & ~0xF) 320 << (val & 7)", i.e., the option value with the last 4 bits masked 321 out, shifted to the left by the value of SZX, gives the byte 322 position of the first byte of the block being transferred. 324 More specifically, within the option value of a Block1 or Block2 325 Option, the meaning of the option fields is defined as follows: 327 NUM: Block Number, indicating the block number being requested or 328 provided. Block number 0 indicates the first block of a body 329 (i.e., starting with the first byte of the body). 331 M: More Flag ("not last block"). For descriptive usage, this flag, 332 if unset, indicates that the payload in this message is the last 333 block in the body; when set it indicates that there are one or 334 more additional blocks available. When a Block2 Option is used in 335 a request to retrieve a specific block number ("control usage"), 336 the M bit MUST be sent as zero and ignored on reception. (In a 337 Block1 Option in a response, the M flag is used to indicate 338 atomicity, see below.) 340 SZX: Block Size. The block size is represented as three-bit 341 unsigned integer indicating the size of a block to the power of 342 two. Thus block size = 2**(SZX + 4). The allowed values of SZX 343 are 0 to 6, i.e., the minimum block size is 2**(0+4) = 16 and the 344 maximum is 2**(6+4) = 1024. The value 7 for SZX (which would 345 indicate a block size of 2048) is reserved, i.e. MUST NOT be sent 346 and MUST lead to a 4.00 Bad Request response code upon reception 347 in a request. 349 There is no default value for the Block1 and Block2 Options. Absence 350 of one of these options is equivalent to an option value of 0 with 351 respect to the value of NUM and M that could be given in the option, 352 i.e. it indicates that the current block is the first and only block 353 of the transfer (block number 0, M bit not set). However, in 354 contrast to the explicit value 0, which would indicate an SZX of 0 355 and thus a size value of 16 bytes, there is no specific explicit size 356 implied by the absence of the option -- the size is left unspecified. 357 (As for any uint, the explicit value 0 is efficiently indicated by a 358 zero-length option; this, therefore, is different in semantics from 359 the absence of the option.) 361 2.3. Block Options in Requests and Responses 363 The Block options are used in one of three roles: 365 o In descriptive usage, i.e., a Block2 Option in a response (such as 366 a 2.05 response for GET), or a Block1 Option in a request (a PUT 367 or POST): 369 * The NUM field in the option value describes what block number 370 is contained in the payload of this message. 372 * The M bit indicates whether further blocks need to be 373 transferred to complete the transfer of that body. 375 * The block size implied by SZX MUST match the size of the 376 payload in bytes, if the M bit is set. (SZX does not govern 377 the payload size if M is unset). For Block2, if the request 378 suggested a larger value of SZX, the next request MUST move SZX 379 down to the size given in the response. (The effect is that, 380 if the server uses the smaller of (1) its preferred block size 381 and (2) the block size requested, all blocks for a body use the 382 same block size.) 384 o A Block2 Option in control usage in a request (e.g., GET): 386 * The NUM field in the Block2 Option gives the block number of 387 the payload that is being requested to be returned in the 388 response. 390 * In this case, the M bit has no function and MUST be set to 391 zero. 393 * The block size given (SZX) suggests a block size (in the case 394 of block number 0) or repeats the block size of previous blocks 395 received (in the case of a non-zero block number). 397 o A Block1 Option in control usage in a response (e.g., a 2.xx 398 response for a PUT or POST request): 400 * The NUM field of the Block1 Option indicates what block number 401 is being acknowledged. 403 * If the M bit was set in the request, the server can choose 404 whether to act on each block separately, with no memory, or 405 whether to handle the request for the entire body atomically, 406 or any mix of the two. 408 + If the M bit is also set in the response, it indicates that 409 this response does not carry the final response code to the 410 request, i.e. the server collects further blocks from the 411 same endpoint and plans to implement the request atomically 412 (e.g., acts only upon reception of the last block of 413 payload). In this case, the response MUST NOT carry a 414 Block2 option. 416 + Conversely, if the M bit is unset even though it was set in 417 the request, it indicates the block-wise request was enacted 418 now specifically for this block, and the response carries 419 the final response to this request (and to any previous ones 420 with the M bit set in the response's Block1 Option in this 421 sequence of block-wise transfers); the client is still 422 expected to continue sending further blocks, the request 423 method for which may or may not also be enacted per-block. 425 * Finally, the SZX block size given in a control Block1 Option 426 indicates the largest block size preferred by the server for 427 transfers toward the resource that is the same or smaller than 428 the one used in the initial exchange; the client SHOULD use 429 this block size or a smaller one in all further requests in the 430 transfer sequence, even if that means changing the block size 431 (and possibly scaling the block number accordingly) from now 432 on. 434 Using one or both Block options, a single REST operation can be split 435 into multiple CoAP message exchanges. As specified in [RFC7252], 436 each of these message exchanges uses their own CoAP Message ID. 438 2.4. Using the Block2 Option 440 When a request is answered with a response carrying a Block2 Option 441 with the M bit set, the requester may retrieve additional blocks of 442 the resource representation by sending further requests with the same 443 options as the initial request and a Block2 Option giving the block 444 number and block size desired. In a request, the client MUST set the 445 M bit of a Block2 Option to zero and the server MUST ignore it on 446 reception. 448 To influence the block size used in a response, the requester MAY 449 also use the Block2 Option on the initial request, giving the desired 450 size, a block number of zero and an M bit of zero. A server MUST use 451 the block size indicated or a smaller size. Any further block-wise 452 requests for blocks beyond the first one MUST indicate the same block 453 size that was used by the server in the response for the first 454 request that gave a desired size using a Block2 Option. 456 Once the Block2 Option is used by the requester and a first response 457 has been received with a possibly adjusted block size, all further 458 requests in a single block-wise transfer SHOULD ultimately use the 459 same size, except that there may not be enough content to fill the 460 last block (the one returned with the M bit not set). (Note that the 461 client may start using the Block2 Option in a second request after a 462 first request without a Block2 Option resulted in a Block2 option in 463 the response.) The server SHOULD use the block size indicated in the 464 request option or a smaller size, but the requester MUST take note of 465 the actual block size used in the response it receives to its initial 466 request and proceed to use it in subsequent requests. The server 467 behavior MUST ensure that this client behavior results in the same 468 block size for all responses in a sequence (except for the last one 469 with the M bit not set, and possibly the first one if the initial 470 request did not contain a Block2 Option). 472 Block-wise transfers can be used to GET resources the representations 473 of which are entirely static (not changing over time at all, such as 474 in a schema describing a device), or for dynamically changing 475 resources. In the latter case, the Block2 Option SHOULD be used in 476 conjunction with the ETag Option, to ensure that the blocks being 477 reassembled are from the same version of the representation: The 478 server SHOULD include an ETag option in each response. If an ETag 479 option is available, the client's reassembler, when reassembling the 480 representation from the blocks being exchanged, MUST compare ETag 481 Options. If the ETag Options do not match in a GET transfer, the 482 requester has the option of attempting to retrieve fresh values for 483 the blocks it retrieved first. To minimize the resulting 484 inefficiency, the server MAY cache the current value of a 485 representation for an ongoing sequence of requests. (The server may 486 identify the sequence by the combination of the requesting end-point 487 and the URI being the same in each block-wise request.) Note well 488 that this specification makes no requirement for the server to 489 establish any state; however, servers that offer quickly changing 490 resources may thereby make it impossible for a client to ever 491 retrieve a consistent set of blocks. 493 2.5. Using the Block1 Option 495 In a request with a request payload (e.g., PUT or POST), the Block1 496 Option refers to the payload in the request (descriptive usage). 498 In response to a request with a payload (e.g., a PUT or POST 499 transfer), the block size given in the Block1 Option indicates the 500 block size preference of the server for this resource (control 501 usage). Obviously, at this point the first block has already been 502 transferred by the client without benefit of this knowledge. Still, 503 the client SHOULD heed the preference indicated and, for all further 504 blocks, use the block size preferred by the server or a smaller one. 505 Note that any reduction in the block size may mean that the second 506 request starts with a block number larger than one, as the first 507 request already transferred multiple blocks as counted in the smaller 508 size. 510 To counter the effects of adaptation layer fragmentation on packet 511 delivery probability, a client may want to give up retransmitting a 512 request with a relatively large payload even before MAX_RETRANSMIT 513 has been reached, and try restating the request as a block-wise 514 transfer with a smaller payload. Note that this new attempt is then 515 a new message-layer transaction and requires a new Message ID. 516 (Because of the uncertainty whether the request or the 517 acknowledgement was lost, this strategy is useful mostly for 518 idempotent requests.) 520 In a blockwise transfer of a request payload (e.g., a PUT or POST) 521 that is intended to be implemented in an atomic fashion at the 522 server, the actual creation/replacement takes place at the time the 523 final block, i.e. a block with the M bit unset in the Block1 Option, 524 is received. In this case, all success responses to non-final blocks 525 carry the response code 2.31 (Continue, Section 2.9.1). If not all 526 previous blocks are available at the server at the time of processing 527 the final block, the transfer fails and error code 4.08 (Request 528 Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY 529 also return a 4.08 error code for any (final or non-final) Block1 530 transfer that is not in sequence; clients that do not have specific 531 mechanisms to handle this case therefore SHOULD always start with 532 block zero and send the following blocks in order. 534 The error code 4.13 (Request Entity Too Large) can be returned at any 535 time by a server that does not currently have the resources to store 536 blocks for a block-wise request payload transfer that it would intend 537 to implement in an atomic fashion. (Note that a 4.13 response to a 538 request that does not employ Block1 is a hint for the client to try 539 sending Block1, and a 4.13 response with a smaller SZX in its Block1 540 option than requested is a hint to try a smaller SZX.) 542 The Block1 option provides no way for a single endpoint to perform 543 multiple concurrently proceeding block-wise request payload transfer 544 (e.g., PUT or POST) operations to the same resource. Starting a new 545 block-wise sequence of requests to the same resource (before an old 546 sequence from the same endpoint was finished) simply overwrites the 547 context the server may still be keeping. (This is probably exactly 548 what one wants in this case - the client may simply have restarted 549 and lost its knowledge of the previous sequence.) 551 2.6. Combining Blockwise Transfers with the Observe Option 553 The Observe Option provides a way for a client to be notified about 554 changes over time of a resource [I-D.ietf-core-observe]. Resources 555 observed by clients may be larger than can be comfortably processed 556 or transferred in one CoAP message. The following rules apply to the 557 combination of blockwise transfers with notifications. 559 Observation relationships always apply to an entire resource; the 560 Block2 option does not provide a way to observe a single block of a 561 resource. 563 As with basic GET transfers, the client can indicate its desired 564 block size in a Block2 Option in the GET request establishing or 565 renewing the observation relationship. If the server supports 566 blockwise transfers, it SHOULD take note of the block size and apply 567 it as a maximum size to all notifications/responses resulting from 568 the GET request (until the client is removed from the list of 569 observers or the entry in that list is updated by the server 570 receiving a new GET request for the resource from the client). 572 When sending a 2.05 (Content) notification, the server only sends the 573 first block of the representation. The client retrieves the rest of 574 the representation as if it had caused this first response by a GET 575 request, i.e., by using additional GET requests with Block2 options 576 containing NUM values greater than zero. (This results in the 577 transfer of the entire representation, even if only some of the 578 blocks have changed with respect to a previous notification.) 580 As with other dynamically changing resources, to ensure that the 581 blocks being reassembled are from the same version of the 582 representation, the server SHOULD include an ETag option in each 583 response, and the reassembling client MUST compare the ETag options 584 (Section 2.4). 586 See Section 3.4 for examples. 588 2.7. Combining Block1 and Block2 590 In PUT and particularly in POST exchanges, both the request body and 591 the response body may be large enough to require the use of block- 592 wise transfers. First, the Block1 transfer of the request body 593 proceeds as usual. In the exchange of the last slice of this block- 594 wise transfer, the response carries the first slice of the Block2 595 transfer (NUM is zero). To continue this Block2 transfer, the client 596 continues to send requests similar to the requests in the Block1 597 phase, but leaves out the Block1 options and includes a Block2 598 request option with non-zero NUM. 600 Block2 transfers that retrieve the response body for a request that 601 used Block1 MUST be performed in sequential order. 603 2.8. Combining Block2 with Multicast 605 A client can use the Block2 option in a multicast GET request with 606 NUM = 0 to aid in limiting the size of the response. 608 Similarly, a response to a multicast GET request can use a Block2 609 option with NUM = 0 if the representation is large, or to further 610 limit the size of the response. 612 In both cases, the client retrieves any further blocks using unicast 613 exchanges; in the unicast requests, the client SHOULD heed any block 614 size preferences indicated by the server in the response to the 615 multicast request. 617 Other uses of the Block options in conjunction with multicast 618 messages are for further study. 620 2.9. Response Codes 622 Two response codes are defined by this specification beyond those 623 already defined in [RFC7252], and another response code is extended 624 in its meaning. 626 2.9.1. 2.31 Continue 628 This new success status code indicates that the transfer of this 629 block of the request body was successful and that the server 630 encourages sending further blocks, but that a final outcome of the 631 whole block-wise request cannot yet be determined. No payload is 632 returned with this response code. 634 2.9.2. 4.08 Request Entity Incomplete 636 This new client error status code indicates that the server has not 637 received the blocks of the request body that it needs to proceed. 638 The client has not sent all blocks, not sent them in the order 639 required by the server, or has sent them long enough ago that the 640 server has already discarded them. 642 2.9.3. 4.13 Request Entity Too Large 644 In [RFC7252], section 5.9.2.9, the response code 4.13 (Request Entity 645 Too Large) is defined to be like HTTP 413 "Request Entity Too Large". 646 [RFC7252] also recommends that this response SHOULD include a Size1 647 Option (Section 4) to indicate the maximum size of request entity the 648 server is able and willing to handle, unless the server is not in a 649 position to make this 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 663 This section gives a number of short examples with message flows for 664 a block-wise GET, and for a PUT or POST. These examples demonstrate 665 the basic operation, the operation in the presence of 666 retransmissions, and examples for the operation of the block size 667 negotiation. 669 In all these examples, a Block option is shown in a decomposed way 670 indicating the kind of Block option (1 or 2) followed by a colon, and 671 then the block number (NUM), more bit (M), and block size exponent 672 (2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33 673 would be shown as 2:2/0/32), or a Block1 Option value of 59 would be 674 shown as 1:3/1/128. 676 3.1. Block2 Examples 678 The first example (Figure 2) shows a GET request that is split into 679 three blocks. The server proposes a block size of 128, and the 680 client agrees. The first two ACKs contain 128 bytes of payload each, 681 and third ACK contains between 1 and 128 bytes. 683 CLIENT SERVER 684 | | 685 | CON [MID=1234], GET, /status ------> | 686 | | 687 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 688 | | 689 | CON [MID=1235], GET, /status, 2:1/0/128 ------> | 690 | | 691 | <------ ACK [MID=1235], 2.05 Content, 2:1/1/128 | 692 | | 693 | CON [MID=1236], GET, /status, 2:2/0/128 ------> | 694 | | 695 | <------ ACK [MID=1236], 2.05 Content, 2:2/0/128 | 697 Figure 2: Simple blockwise GET 699 In the second example (Figure 3), the client anticipates the 700 blockwise transfer (e.g., because of a size indication in the link- 701 format description [RFC6690]) and sends a block size proposal. All 702 ACK messages except for the last carry 64 bytes of payload; the last 703 one carries between 1 and 64 bytes. 705 CLIENT SERVER 706 | | 707 | CON [MID=1234], GET, /status, 2:0/0/64 ------> | 708 | | 709 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/64 | 710 | | 711 | CON [MID=1235], GET, /status, 2:1/0/64 ------> | 712 | | 713 | <------ ACK [MID=1235], 2.05 Content, 2:1/1/64 | 714 : : 715 : ... : 716 : : 717 | CON [MID=1238], GET, /status, 2:4/0/64 ------> | 718 | | 719 | <------ ACK [MID=1238], 2.05 Content, 2:4/1/64 | 720 | | 721 | CON [MID=1239], GET, /status, 2:5/0/64 ------> | 722 | | 723 | <------ ACK [MID=1239], 2.05 Content, 2:5/0/64 | 725 Figure 3: Blockwise GET with early negotiation 727 In the third example (Figure 4), the client is surprised by the need 728 for a blockwise transfer, and unhappy with the size chosen 729 unilaterally by the server. As it did not send a size proposal 730 initially, the negotiation only influences the size from the second 731 message exchange onward. Since the client already obtained both the 732 first and second 64-byte block in the first 128-byte exchange, it 733 goes on requesting the third 64-byte block ("2/0/64"). None of this 734 is (or needs to be) understood by the server, which simply responds 735 to the requests as it best can. 737 CLIENT SERVER 738 | | 739 | CON [MID=1234], GET, /status ------> | 740 | | 741 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 742 | | 743 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 744 | | 745 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 746 | | 747 | CON [MID=1236], GET, /status, 2:3/0/64 ------> | 748 | | 749 | <------ ACK [MID=1236], 2.05 Content, 2:3/1/64 | 750 | | 751 | CON [MID=1237], GET, /status, 2:4/0/64 ------> | 752 | | 753 | <------ ACK [MID=1237], 2.05 Content, 2:4/1/64 | 754 | | 755 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 756 | | 757 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 759 Figure 4: Blockwise GET with late negotiation 761 In all these (and the following) cases, retransmissions are handled 762 by the CoAP message exchange layer, so they don't influence the block 763 operations (Figure 5, Figure 6). 765 CLIENT SERVER 766 | | 767 | CON [MID=1234], GET, /status ------> | 768 | | 769 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 770 | | 771 | CON [MID=1235], GE///////////////////////// | 772 | | 773 | (timeout) | 774 | | 775 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 776 | | 777 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 778 : : 779 : ... : 780 : : 781 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 782 | | 783 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 785 Figure 5: Blockwise GET with late negotiation and lost CON 787 CLIENT SERVER 788 | | 789 | CON [MID=1234], GET, /status ------> | 790 | | 791 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 792 | | 793 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 794 | | 795 | //////////////////////////////////tent, 2:2/1/64 | 796 | | 797 | (timeout) | 798 | | 799 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 800 | | 801 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 802 : : 803 : ... : 804 : : 805 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 806 | | 807 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 809 Figure 6: Blockwise GET with late negotiation and lost ACK 811 3.2. Block1 Examples 813 The following examples demonstrate a PUT exchange; a POST exchange 814 looks the same, with different requirements on atomicity/idempotence. 815 Note that, similar to GET, the responses to the requests that have a 816 more bit in the request Block1 Option are provisional and carry the 817 response code 2.31 (Continue); only the final response tells the 818 client that the PUT did succeed. 820 CLIENT SERVER 821 | | 822 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 823 | | 824 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 825 | | 826 | CON [MID=1235], PUT, /options, 1:1/1/128 ------> | 827 | | 828 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 829 | | 830 | CON [MID=1236], PUT, /options, 1:2/0/128 ------> | 831 | | 832 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | 834 Figure 7: Simple atomic blockwise PUT 836 A stateless server that simply builds/updates the resource in place 837 (statelessly) may indicate this by not setting the more bit in the 838 response (Figure 8); in this case, the response codes are valid 839 separately for each block being updated. This is of course only an 840 acceptable behavior of the server if the potential inconsistency 841 present during the run of the message exchange sequence does not lead 842 to problems, e.g. because the resource being created or changed is 843 not yet or not currently in use. 845 CLIENT SERVER 846 | | 847 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 848 | | 849 | <------ ACK [MID=1234], 2.04 Changed, 1:0/0/128 | 850 | | 851 | CON [MID=1235], PUT, /options, 1:1/1/128 ------> | 852 | | 853 | <------ ACK [MID=1235], 2.04 Changed, 1:1/0/128 | 854 | | 855 | CON [MID=1236], PUT, /options, 1:2/0/128 ------> | 856 | | 857 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | 859 Figure 8: Simple stateless blockwise PUT 861 Finally, a server receiving a blockwise PUT or POST may want to 862 indicate a smaller block size preference (Figure 9). In this case, 863 the client SHOULD continue with a smaller block size; if it does, it 864 MUST adjust the block number to properly count in that smaller size. 866 CLIENT SERVER 867 | | 868 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 869 | | 870 | <------ ACK [MID=1234], 2.04 Changed, 1:0/1/32 | 871 | | 872 | CON [MID=1235], PUT, /options, 1:4/1/32 ------> | 873 | | 874 | <------ ACK [MID=1235], 2.04 Changed, 1:4/1/32 | 875 | | 876 | CON [MID=1236], PUT, /options, 1:5/1/32 ------> | 877 | | 878 | <------ ACK [MID=1235], 2.04 Changed, 1:5/1/32 | 879 | | 880 | CON [MID=1237], PUT, /options, 1:6/0/32 ------> | 881 | | 882 | <------ ACK [MID=1236], 2.04 Changed, 1:6/0/32 | 884 Figure 9: Simple atomic blockwise PUT with negotiation 886 3.3. Combining Block1 and Block2 888 Block options may be used in both directions of a single exchange. 889 The following example demonstrates a blockwise POST request, 890 resulting in a separate blockwise response. 892 CLIENT SERVER 893 | | 894 | CON [MID=1234], POST, /soap, 1:0/1/128 ------> | 895 | | 896 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 897 | | 898 | CON [MID=1235], POST, /soap, 1:1/1/128 ------> | 899 | | 900 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 901 | | 902 | CON [MID=1236], POST, /soap, 1:2/0/128 ------> | 903 | | 904 | <------ ACK [MID=1236], 2.04 Changed, 2:0/1/128, 1:2/0/128 | 905 | | 906 | CON [MID=1237], POST, /soap, 2:1/0/128 ------> | 907 | (no payload for requests with Block2 with NUM != 0) | 908 | (could also do late negotiation by requesting e.g. 2:2/0/64) | 909 | | 910 | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/128 | 911 | | 912 | CON [MID=1238], POST, /soap, 2:2/0/128 ------> | 913 | | 914 | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/128 | 915 | | 916 | CON [MID=1239], POST, /soap, 2:3/0/128 ------> | 917 | | 918 | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/128 | 920 Figure 10: Atomic blockwise POST with blockwise response 922 This model does provide for early negotiation input to the Block2 923 blockwise transfer, as shown below. 925 CLIENT SERVER 926 | | 927 | CON [MID=1234], POST, /soap, 1:0/1/128 ------> | 928 | | 929 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 930 | | 931 | CON [MID=1235], POST, /soap, 1:1/1/128 ------> | 932 | | 933 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 934 | | 935 | CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------> | 936 | | 937 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 | 938 | | 939 | CON [MID=1237], POST, /soap, 2:1/0/64 ------> | 940 | (no payload for requests with Block2 with NUM != 0) | 941 | | 942 | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/64 | 943 | | 944 | CON [MID=1238], POST, /soap, 2:2/0/64 ------> | 945 | | 946 | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/64 | 947 | | 948 | CON [MID=1239], POST, /soap, 2:3/0/64 ------> | 949 | | 950 | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/64 | 952 Figure 11: Atomic blockwise POST with blockwise response, early 953 negotiation 955 3.4. Combining Observe and Block2 957 In the following example, the server first sends a direct response 958 (Observe sequence number 62350) to the initial GET request (the 959 resulting blockwise transfer is as in Figure 4 and has therefore been 960 left out). The second transfer is started by a 2.05 notification 961 that contains just the first block (Observe sequence number 62354); 962 the client then goes on to obtain the rest of the blocks. 964 CLIENT SERVER 965 | | 966 +----->| Header: GET 0x41011636 967 | GET | Token: 0xfb 968 | | Uri-Path: status-icon 969 | | Observe: (empty) 970 | | 971 |<-----+ Header: 2.05 0x61451636 972 | 2.05 | Token: 0xfb 973 | | Block2: 0/1/128 974 | | Observe: 62350 975 | | ETag: 6f00f38e 976 | | Payload: [128 bytes] 977 | | 978 | | (Usual GET transfer left out) 979 ... 980 | | (Notification of first block:) 981 | | 982 |<-----+ Header: 2.05 0x4145af9c 983 | 2.05 | Token: 0xfb 984 | | Block2: 0/1/128 985 | | Observe: 62354 986 | | ETag: 6f00f392 987 | | Payload: [128 bytes] 988 | | 989 +- - ->| Header: 0x6000af9c 990 | | 991 | | (Retrieval of remaining blocks) 992 | | 993 +----->| Header: GET 0x41011637 994 | GET | Token: 0xfc 995 | | Uri-Path: status-icon 996 | | Block2: 1/0/128 997 | | 998 |<-----+ Header: 2.05 0x61451637 999 | 2.05 | Token: 0xfc 1000 | | Block2: 1/1/128 1001 | | ETag: 6f00f392 1002 | | Payload: [128 bytes] 1003 | | 1004 +----->| Header: GET 0x41011638 1005 | GET | Token: 0xfc 1006 | | Uri-Path: status-icon 1007 | | Block2: 2/0/128 1008 | | 1009 |<-----+ Header: 2.05 0x61451638 1010 | 2.05 | Token: 0xfc 1011 | | Block2: 2/0/128 1012 | | ETag: 6f00f392 1013 | | Payload: [53 bytes] 1015 Figure 12: Observe sequence with blockwise response 1017 In the following example, the client also uses early negotiation to 1018 limit the block size to 64 bytes. 1020 CLIENT SERVER 1021 | | 1022 +----->| Header: GET 0x41011636 1023 | GET | Token: 0xfb 1024 | | Uri-Path: status-icon 1025 | | Observe: (empty) 1026 | | Block2: 0/0/64 1027 | | 1028 |<-----+ Header: 2.05 0x61451636 1029 | 2.05 | Token: 0xfb 1030 | | Block2: 0/1/64 1031 | | Observe: 62350 1032 | | ETag: 6f00f38e 1033 | | Max-Age: 60 1034 | | Payload: [64 bytes] 1035 | | 1036 | | (Usual GET transfer left out) 1037 ... 1038 | | (Notification of first block:) 1039 | | 1040 |<-----+ Header: 2.05 0x4145af9c 1041 | 2.05 | Token: 0xfb 1042 | | Block2: 0/1/64 1043 | | Observe: 62354 1044 | | ETag: 6f00f392 1045 | | Payload: [64 bytes] 1046 | | 1047 +- - ->| Header: 0x6000af9c 1048 | | 1049 | | (Retrieval of remaining blocks) 1050 | | 1051 +----->| Header: GET 0x41011637 1052 | GET | Token: 0xfc 1053 | | Uri-Path: status-icon 1054 | | Block2: 1/0/64 1055 | | 1056 |<-----+ Header: 2.05 0x61451637 1057 | 2.05 | Token: 0xfc 1058 | | Block2: 1/1/64 1059 | | ETag: 6f00f392 1060 | | Payload: [64 bytes] 1061 .... 1062 | | 1063 +----->| Header: GET 0x41011638 1064 | GET | Token: 0xfc 1065 | | Uri-Path: status-icon 1066 | | Block2: 4/0/64 1067 | | 1068 |<-----+ Header: 2.05 0x61451638 1069 | 2.05 | Token: 0xfc 1070 | | Block2: 4/0/64 1071 | | ETag: 6f00f392 1072 | | Payload: [53 bytes] 1074 Figure 13: Observe sequence with early negotiation 1076 4. The Size2 and Size1 Options 1078 In many cases when transferring a large resource representation block 1079 by block, it is advantageous to know the total size early in the 1080 process. Some indication may be available from the maximum size 1081 estimate attribute "sz" provided in a resource description [RFC6690]. 1082 However, the size may vary dynamically, so a more up-to-date 1083 indication may be useful. 1085 This specification defines two CoAP Options, Size1 for indicating the 1086 size of the representation transferred in requests, and Size2 for 1087 indicating the size of the representation transferred in responses. 1088 (Size1 is already defined in [RFC7252] for the narrow case of 1089 indicating in 4.13 responses the maximum size of request payload that 1090 the server is able and willing to handle.) 1092 The Size2 Option may be used for two purposes: 1094 o in a request, to ask the server to provide a size estimate along 1095 with the usual response ("size request"). For this usage, the 1096 value MUST be set to 0. 1098 o in a response carrying a Block2 Option, to indicate the current 1099 estimate the server has of the total size of the resource 1100 representation, measured in bytes ("size indication"). 1102 Similarly, the Size1 Option may be used for two purposes: 1104 o in a request carrying a Block1 Option, to indicate the current 1105 estimate the client has of the total size of the resource 1106 representation, measured in bytes ("size indication"). 1108 o in a 4.13 response, to indicate the maximum size that would have 1109 been acceptable [RFC7252], measured in bytes. 1111 Apart from conveying/asking for size information, the Size options 1112 have no other effect on the processing of the request or response. 1113 If the client wants to minimize the size of the payload in the 1114 resulting response, it should add a Block2 option to the request with 1115 a small block size (e.g., setting SZX=0). 1117 The Size Options are "elective", i.e., a client MUST be prepared for 1118 the server to ignore the size estimate request. The Size Options 1119 MUST NOT occur more than once. 1121 +-----+---+---+---+---+-------+--------+--------+---------+ 1122 | No. | C | U | N | R | Name | Format | Length | Default | 1123 +-----+---+---+---+---+-------+--------+--------+---------+ 1124 | 60 | | | x | | Size1 | uint | 0-4 | (none) | 1125 | | | | | | | | | | 1126 | 28 | | | x | | Size2 | uint | 0-4 | (none) | 1127 +-----+---+---+---+---+-------+--------+--------+---------+ 1129 Table 2: Size Option Numbers 1131 Implementation Notes: 1133 o As a quality of implementation consideration, blockwise transfers 1134 for which the total size considerably exceeds the size of one 1135 block are expected to include size indications, whenever those can 1136 be provided without undue effort (preferably with the first block 1137 exchanged). If the size estimate does not change, the indication 1138 does not need to be repeated for every block. 1140 o The end of a blockwise transfer is governed by the M bits in the 1141 Block Options, _not_ by exhausting the size estimates exchanged. 1143 o As usual for an option of type uint, the value 0 is best expressed 1144 as an empty option (0 bytes). There is no default value for 1145 either Size Option. 1147 o The Size Options are neither critical nor unsafe, and are marked 1148 as No-Cache-Key. 1150 5. HTTP Mapping Considerations 1152 In this subsection, we give some brief examples for the influence the 1153 Block options might have on intermediaries that map between CoAP and 1154 HTTP. 1156 For mapping CoAP requests to HTTP, the intermediary may want to map 1157 the sequence of block-wise transfers into a single HTTP transfer. 1158 E.g., for a GET request, the intermediary could perform the HTTP 1159 request once the first block has been requested and could then 1160 fulfill all further block requests out of its cache. A constrained 1161 implementation may not be able to cache the entire object and may use 1162 a combination of TCP flow control and (in particular if timeouts 1163 occur) HTTP range requests to obtain the information necessary for 1164 the next block transfer at the right time. 1166 For PUT or POST requests, historically there was more variation in 1167 how HTTP servers might implement ranges; recently, [RFC7233] has 1168 defined that Range header fields received with a request method other 1169 than GET are not to be interpreted. So, in general, the CoAP-to-HTTP 1170 intermediary will have to try sending the payload of all the blocks 1171 of a block-wise transfer for these other methods within one HTTP 1172 request. If enough buffering is available, this request can be 1173 started when the last CoAP block is received. A constrained 1174 implementation may want to relieve its buffering by already starting 1175 to send the HTTP request at the time the first CoAP block is 1176 received; any HTTP 408 status code that indicates that the HTTP 1177 server became impatient with the resulting transfer can then be 1178 mapped into a CoAP 4.08 response code (similarly, 413 maps to 4.13). 1180 For mapping HTTP to CoAP, the intermediary may want to map a single 1181 HTTP transfer into a sequence of block-wise transfers. If the HTTP 1182 client is too slow delivering a request body on a PUT or POST, the 1183 CoAP server might time out and return a 4.08 response code, which in 1184 turn maps well to an HTTP 408 status code (again, 4.13 maps to 413). 1185 HTTP range requests received on the HTTP side may be served out of a 1186 cache and/or mapped to GET requests that request a sequence of blocks 1187 overlapping the range. 1189 (Note that, while the semantics of CoAP 4.08 and HTTP 408 differ, 1190 this difference is largely due to the different way the two protocols 1191 are mapped to transport. HTTP has an underlying TCP connection, 1192 which supplies connection state, so a HTTP 408 status code can 1193 immediately be used to indicate that a timeout occurred during 1194 transmitting a request through that active TCP connection. The CoAP 1195 4.08 response code indicates one or more missing blocks, which may be 1196 due to timeouts or resource constraints; as there is no connection 1197 state, there is no way to deliver such a response immediately; 1198 instead, it is delivered on the next block transfer. Still, HTTP 408 1199 is probably the best mapping back to HTTP, as the timeout is the most 1200 likely cause for a CoAP 4.08. Note that there is no way to 1201 distinguish a timeout from a missing block for a server without 1202 creating additional state, the need for which we want to avoid.) 1204 6. IANA Considerations 1206 This draft adds the following option numbers to the CoAP Option 1207 Numbers registry of [RFC7252]: 1209 +--------+--------+-----------+ 1210 | Number | Name | Reference | 1211 +--------+--------+-----------+ 1212 | 23 | Block2 | [RFCXXXX] | 1213 | | | | 1214 | 27 | Block1 | [RFCXXXX] | 1215 | | | | 1216 | 28 | Size2 | [RFCXXXX] | 1217 +--------+--------+-----------+ 1219 Table 3: CoAP Option Numbers 1221 This draft adds the following response code to the CoAP Response 1222 Codes registry of [RFC7252]: 1224 +------+---------------------------+-----------+ 1225 | Code | Description | Reference | 1226 +------+---------------------------+-----------+ 1227 | 2.31 | Continue | [RFCXXXX] | 1228 | | | | 1229 | 4.08 | Request Entity Incomplete | [RFCXXXX] | 1230 +------+---------------------------+-----------+ 1232 Table 4: CoAP Response Codes 1234 7. Security Considerations 1236 Providing access to blocks within a resource may lead to surprising 1237 vulnerabilities. Where requests are not implemented atomically, an 1238 attacker may be able to exploit a race condition or confuse a server 1239 by inducing it to use a partially updated resource representation. 1240 Partial transfers may also make certain problematic data invisible to 1241 intrusion detection systems; it is RECOMMENDED that an intrusion 1242 detection system (IDS) that analyzes resource representations 1243 transferred by CoAP implement the Block options to gain access to 1244 entire resource representations. Still, approaches such as 1245 transferring even-numbered blocks on one path and odd-numbered blocks 1246 on another path, or even transferring blocks multiple times with 1247 different content and obtaining a different interpretation of 1248 temporal order at the IDS than at the server, may prevent an IDS from 1249 seeing the whole picture. These kinds of attacks are well understood 1250 from IP fragmentation and TCP segmentation; CoAP does not add 1251 fundamentally new considerations. 1253 Where access to a resource is only granted to clients making use of 1254 specific security associations, all blocks of that resource MUST be 1255 subject to the same security checks; it MUST NOT be possible for 1256 unprotected exchanges to influence blocks of an otherwise protected 1257 resource. As a related consideration, where object security is 1258 employed, PUT/POST should be implemented in the atomic fashion, 1259 unless the object security operation is performed on each access and 1260 the creation of unusable resources can be tolerated. 1262 A stateless server might be susceptible to an attack where the 1263 adversary sends a Block1 (e.g., PUT) block with a high block number: 1264 A naive implementation might exhaust its resources by creating a huge 1265 resource representation. 1267 Misleading size indications may be used by an attacker to induce 1268 buffer overflows in poor implementations, for which the usual 1269 considerations apply. 1271 7.1. Mitigating Resource Exhaustion Attacks 1273 Certain blockwise requests may induce the server to create state, 1274 e.g. to create a snapshot for the blockwise GET of a fast-changing 1275 resource to enable consistent access to the same version of a 1276 resource for all blocks, or to create temporary resource 1277 representations that are collected until pressed into service by a 1278 final PUT or POST with the more bit unset. All mechanisms that 1279 induce a server to create state that cannot simply be cleaned up 1280 create opportunities for denial-of-service attacks. Servers SHOULD 1281 avoid being subject to resource exhaustion based on state created by 1282 untrusted sources. But even if this is done, the mitigation may 1283 cause a denial-of-service to a legitimate request when it is drowned 1284 out by other state-creating requests. Wherever possible, servers 1285 should therefore minimize the opportunities to create state for 1286 untrusted sources, e.g. by using stateless approaches. 1288 Performing segmentation at the application layer is almost always 1289 better in this respect than at the transport layer or lower (IP 1290 fragmentation, adaptation layer fragmentation), for instance because 1291 there is application layer semantics that can be used for mitigation 1292 or because lower layers provide security associations that can 1293 prevent attacks. However, it is less common to apply timeouts and 1294 keepalive mechanisms at the application layer than at lower layers. 1295 Servers MAY want to clean up accumulated state by timing it out (cf. 1296 response code 4.08), and clients SHOULD be prepared to run blockwise 1297 transfers in an expedient way to minimize the likelihood of running 1298 into such a timeout. 1300 7.2. Mitigating Amplification Attacks 1302 [RFC7252] discusses the susceptibility of CoAP end-points for use in 1303 amplification attacks. 1305 A CoAP server can reduce the amount of amplification it provides to 1306 an attacker by offering large resource representations only in 1307 relatively small blocks. With this, e.g., for a 1000 byte resource, 1308 a 10-byte request might result in an 80-byte response (with a 64-byte 1309 block) instead of a 1016-byte response, considerably reducing the 1310 amplification provided. 1312 8. Acknowledgements 1314 Much of the content of this draft is the result of discussions with 1315 the [RFC7252] authors, and via many CoRE WG discussions. 1317 Charles Palmer provided extensive editorial comments to a previous 1318 version of this draft, some of which the authors hope to have covered 1319 in this version. Esko Dijk reviewed a more recent version, leading 1320 to a number of further editorial improvements, a solution to the 4.13 1321 ambiguity problem, and the section about combining Block and 1322 multicast. Markus Becker proposed getting rid of an ill-conceived 1323 default value for the Block2 and Block1 options. Peter Bigot 1324 insisted on a more systematic coverage of the options and response 1325 code. 1327 Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of 1328 the Size Option, which has informed this draft. Klaus Hartke wrote 1329 some of the text describing the interaction of Block2 with Observe. 1330 Matthias Kovatsch provided a number of significant simplifications of 1331 the protocol. 1333 9. References 1335 9.1. Normative References 1337 [I-D.ietf-core-observe] 1338 Hartke, K., "Observing Resources in CoAP", draft-ietf- 1339 core-observe-14 (work in progress), June 2014. 1341 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1342 Requirement Levels", BCP 14, RFC 2119, March 1997. 1344 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1345 Application Protocol (CoAP)", RFC 7252, June 2014. 1347 9.2. Informative References 1349 [REST] Fielding, R., "Architectural Styles and the Design of 1350 Network-based Software Architectures", Ph.D. Dissertation, 1351 University of California, Irvine, 2000, 1352 . 1355 [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6 1356 over Low-Power Wireless Personal Area Networks (6LoWPANs): 1357 Overview, Assumptions, Problem Statement, and Goals", RFC 1358 4919, August 2007. 1360 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 1361 "Transmission of IPv6 Packets over IEEE 802.15.4 1362 Networks", RFC 4944, September 2007. 1364 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1365 Format", RFC 6690, August 2012. 1367 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1368 Constrained-Node Networks", RFC 7228, May 2014. 1370 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1371 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 1372 2014. 1374 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 1375 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 1376 June 2014. 1378 Authors' Addresses 1380 Carsten Bormann 1381 Universitaet Bremen TZI 1382 Postfach 330440 1383 Bremen D-28359 1384 Germany 1386 Phone: +49-421-218-63921 1387 Email: cabo@tzi.org 1388 Zach Shelby (editor) 1389 ARM 1390 150 Rose Orchard 1391 San Jose, CA 95134 1392 USA 1394 Phone: +1-408-203-9434 1395 Email: zach.shelby@arm.com