idnits 2.17.00 (12 Aug 2021) /tmp/idnits23836/draft-ietf-core-block-21.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC7252, but the abstract doesn't seem to directly say this. It does mention RFC7252 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 08, 2016) is 2136 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 1387, but not defined Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 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 Updates: 7252 (if approved) Z. Shelby, Ed. 5 Intended status: Standards Track ARM 6 Expires: January 9, 2017 July 08, 2016 8 Block-wise transfers in CoAP 9 draft-ietf-core-block-21 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 A CoAP implementation that does not support these options generally 41 is limited in the size of the representations that can be exchanged. 42 There is therefore an expectation that the Block options are very 43 widely implemented in CoAP implementations, which is why this 44 specification is listed as "updating" RFC 7252. 46 Status of This Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current Internet- 54 Drafts is at http://datatracker.ietf.org/drafts/current/. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 This Internet-Draft will expire on January 9, 2017. 63 Copyright Notice 65 Copyright (c) 2016 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (http://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 Table of Contents 80 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 81 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . 6 82 2.1. The Block2 and Block1 Options . . . . . . . . . . . . . . 7 83 2.2. Structure of a Block Option . . . . . . . . . . . . . . . 7 84 2.3. Block Options in Requests and Responses . . . . . . . . . 9 85 2.4. Using the Block2 Option . . . . . . . . . . . . . . . . . 11 86 2.5. Using the Block1 Option . . . . . . . . . . . . . . . . . 13 87 2.6. Combining Block-wise Transfers with the Observe Option . 14 88 2.7. Combining Block1 and Block2 . . . . . . . . . . . . . . . 15 89 2.8. Combining Block2 with Multicast . . . . . . . . . . . . . 15 90 2.9. Response Codes . . . . . . . . . . . . . . . . . . . . . 16 91 2.9.1. 2.31 Continue . . . . . . . . . . . . . . . . . . . . 16 92 2.9.2. 4.08 Request Entity Incomplete . . . . . . . . . . . 16 93 2.9.3. 4.13 Request Entity Too Large . . . . . . . . . . . . 16 95 2.10. Caching Considerations . . . . . . . . . . . . . . . . . 17 96 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 17 97 3.1. Block2 Examples . . . . . . . . . . . . . . . . . . . . . 18 98 3.2. Block1 Examples . . . . . . . . . . . . . . . . . . . . . 22 99 3.3. Combining Block1 and Block2 . . . . . . . . . . . . . . . 23 100 3.4. Combining Observe and Block2 . . . . . . . . . . . . . . 25 101 4. The Size2 and Size1 Options . . . . . . . . . . . . . . . . . 28 102 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 30 103 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 104 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31 105 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . 32 106 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . 33 107 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 108 8.1. Normative References . . . . . . . . . . . . . . . . . . 33 109 8.2. Informative References . . . . . . . . . . . . . . . . . 33 110 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 34 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 113 1. Introduction 115 The work on Constrained RESTful Environments (CoRE) aims at realizing 116 the REST architecture in a suitable form for the most constrained 117 nodes (such as microcontrollers with limited RAM and ROM [RFC7228]) 118 and networks (such as 6LoWPAN, [RFC4944]) [RFC7252]. The CoAP 119 protocol is intended to provide RESTful [REST] services not unlike 120 HTTP [RFC7230], while reducing the complexity of implementation as 121 well as the size of packets exchanged in order to make these services 122 useful in a highly constrained network of themselves highly 123 constrained nodes. 125 This objective requires restraint in a number of sometimes 126 conflicting ways: 128 o reducing implementation complexity in order to minimize code size, 130 o reducing message sizes in order to minimize the number of 131 fragments needed for each message (in turn to maximize the 132 probability of delivery of the message), the amount of 133 transmission power needed and the loading of the limited-bandwidth 134 channel, 136 o reducing requirements on the environment such as stable storage, 137 good sources of randomness or user interaction capabilities. 139 CoAP is based on datagram transports such as UDP, which limit the 140 maximum size of resource representations that can be transferred 141 without creating unreasonable levels of IP fragmentation. In 142 addition, not all resource representations will fit into a single 143 link layer packet of a constrained network, which may cause 144 adaptation layer fragmentation even if IP layer fragmentation is not 145 required. Using fragmentation (either at the adaptation layer or at 146 the IP layer) for the transport of larger representations would be 147 possible up to the maximum size of the underlying datagram protocol 148 (such as UDP), but the fragmentation/reassembly process burdens the 149 lower layers with conversation state that is better managed in the 150 application layer. 152 The present specification defines a pair of CoAP options to enable 153 _block-wise_ access to resource representations. The Block options 154 provide a minimal way to transfer larger resource representations in 155 a block-wise fashion. The overriding objective is to avoid the need 156 for creating conversation state at the server for block-wise GET 157 requests. (It is impossible to fully avoid creating conversation 158 state for POST/PUT, if the creation/replacement of resources is to be 159 atomic; where that property is not needed, there is no need to create 160 server conversation state in this case, either.) 162 Block-wise transfers are realized as combinations of exchanges, each 163 of which is performed according to the CoAP base protocol [RFC7252]. 164 Each exchange in such a combination is governed by the specifications 165 in [RFC7252], including the congestion control specifications 166 (Section 4.7 of [RFC7252]) and the security considerations 167 (Section 11 of [RFC7252]; additional security considerations then 168 apply to the transfers as a whole, see Section 7). The present 169 specification minimizes the constraints it adds to those base 170 exchanges; however, not all variants of using CoAP are very useful 171 inside a block-wise transfer (e.g., using Non-confirmable requests 172 within block-wise transfers outside the use case of Section 2.8 would 173 escalate the overall non-delivery probability). To be perfectly 174 clear, the present specification also does not remove any of the 175 constraints posed by the base specification it is strictly layered on 176 top of; e.g., back-to-back packets are limited by Section 4.7 of 177 [RFC7252] (NSTART as a limit for initiating exchanges, PROBING_RATE 178 as a limit for sending with no response): block-wise transfers cannot 179 send/solicit more traffic than a client could be sending to the same 180 server without the block-wise mode. 182 In some cases, the present specification will RECOMMEND that a client 183 perform a sequence of block-wise transfers "without undue delay". 184 This cannot be phrased as an interoperability requirement, but is an 185 expectation on implementation quality. Conversely, the expectation 186 is that servers will not have go out of their way to accommodate 187 clients that take forever to finish a block-wise transfer. E.g., for 188 a block-wise GET, if the resource changes while this proceeds, the 189 ETag for a further block obtained may be different. To avoid this 190 happening all the time for a fast-changing resource, a server MAY try 191 to keep a cache around for a specific client for a short amount of 192 time. The expectation here is that the lifetime for such a cache can 193 be kept short, on the order of a few expected round-trip times, 194 counting from the previous block transferred. 196 In summary, this specification adds a pair of Block options to CoAP 197 that can be used for block-wise transfers. Benefits of using these 198 options include: 200 o Transfers larger than what can be accommodated in constrained- 201 network link-layer packets can be performed in smaller blocks. 203 o No hard-to-manage conversation state is created at the adaptation 204 layer or IP layer for fragmentation. 206 o The transfer of each block is acknowledged, enabling individual 207 retransmission if required. 209 o Both sides have a say in the block size that actually will be 210 used. 212 o The resulting exchanges are easy to understand using packet 213 analyzer tools and thus quite accessible to debugging. 215 o If needed, the Block options can also be used (without changes) to 216 provide random access to power-of-two sized blocks within a 217 resource representation. 219 A CoAP implementation that does not support these options generally 220 is limited in the size of the representations that can be exchanged, 221 see Section 4.6 of [RFC7252]. Even though the options are Critical, 222 a server may decide to start using them in an unsolicited way in a 223 response. No effort was expended to provide a capability indication 224 mechanism supporting that decision: since the block-wise transfer 225 mechanisms are so fundamental to the use of CoAP for representations 226 larger than about a kilobyte, there is an expectation that they are 227 very widely implemented. 229 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 230 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 231 "OPTIONAL" in this document are to be interpreted as described in RFC 232 2119, BCP 14 [RFC2119] and indicate requirement levels for compliant 233 CoAP implementations. 235 In this document, the term "byte" is used in its now customary sense 236 as a synonym for "octet". 238 Where bit arithmetic is explained, this document uses the notation 239 familiar from the programming language C, except that the operator 240 "**" stands for exponentiation. 242 2. Block-wise transfers 244 As discussed in the introduction, there are good reasons to limit the 245 size of datagrams in constrained networks: 247 o by the maximum datagram size (~ 64 KiB for UDP) 249 o by the desire to avoid IP fragmentation (MTU of 1280 for IPv6) 251 o by the desire to avoid adaptation layer fragmentation (60-80 bytes 252 for 6LoWPAN [RFC4919]) 254 When a resource representation is larger than can be comfortably 255 transferred in the payload of a single CoAP datagram, a Block option 256 can be used to indicate a block-wise transfer. As payloads can be 257 sent both with requests and with responses, this specification 258 provides two separate options for each direction of payload transfer. 259 In naming these options (for block-wise transfers as well as in 260 Section 4), we use the number 1 ("Block1", "Size1") to refer to the 261 transfer of the resource representation that pertains to the request, 262 and the number 2 ("Block2", "Size2") to refer to the transfer of the 263 resource representation for the response. 265 In the following, the term "payload" will be used for the actual 266 content of a single CoAP message, i.e. a single block being 267 transferred, while the term "body" will be used for the entire 268 resource representation that is being transferred in a block-wise 269 fashion. The Content-Format option applies to the body, not to the 270 payload, in particular the boundaries between the blocks may be in 271 places that are not separating whole units in terms of the structure, 272 encoding, or content-coding used by the Content-Format. (Similarly, 273 the ETag option defined in Section 5.10.6 of [RFC7252] applies to the 274 whole representation of the resource and thus to the body of the 275 response.) 277 In most cases, all blocks being transferred for a body (except for 278 the last one) will be of the same size. (If the first request uses a 279 bigger block size than the receiver prefers, subsequent requests will 280 use the preferred block size.) The block size is not fixed by the 281 protocol. To keep the implementation as simple as possible, the 282 Block options support only a small range of power-of-two block sizes, 283 from 2**4 (16) to 2**10 (1024) bytes. As bodies often will not 284 evenly divide into the power-of-two block size chosen, the size need 285 not be reached in the final block (but even for the final block, the 286 chosen power-of-two size will still be indicated in the block size 287 field of the Block option). 289 2.1. The Block2 and Block1 Options 291 +-----+---+---+---+---+--------+--------+--------+---------+ 292 | No. | C | U | N | R | Name | Format | Length | Default | 293 +-----+---+---+---+---+--------+--------+--------+---------+ 294 | 23 | C | U | - | - | Block2 | uint | 0-3 | (none) | 295 | | | | | | | | | | 296 | 27 | C | U | - | - | Block1 | uint | 0-3 | (none) | 297 +-----+---+---+---+---+--------+--------+--------+---------+ 299 Table 1: Block Option Numbers 301 Both Block1 and Block2 options can be present both in request and 302 response messages. In either case, the Block1 Option pertains to the 303 request payload, and the Block2 Option pertains to the response 304 payload. 306 Hence, for the methods defined in [RFC7252], Block1 is useful with 307 the payload-bearing POST and PUT requests and their responses. 308 Block2 is useful with GET, POST, and PUT requests and their payload- 309 bearing responses (2.01, 2.02, 2.04, 2.05 -- see Section 5.5 of 310 [RFC7252]). 312 Where Block1 is present in a request or Block2 in a response (i.e., 313 in that message to the payload of which it pertains) it indicates a 314 block-wise transfer and describes how this specific block-wise 315 payload forms part of the entire body being transferred ("descriptive 316 usage"). Where it is present in the opposite direction, it provides 317 additional control on how that payload will be formed or was 318 processed ("control usage"). 320 Implementation of either Block option is intended to be optional. 321 However, when it is present in a CoAP message, it MUST be processed 322 (or the message rejected); therefore it is identified as a critical 323 option. It MUST NOT occur more than once. 325 2.2. Structure of a Block Option 327 Three items of information may need to be transferred in a Block 328 (Block1 or Block2) option: 330 o The size of the block (SZX); 332 o whether more blocks are following (M); 333 o the relative number of the block (NUM) within a sequence of blocks 334 with the given size. 336 The value of the Block Option is a variable-size (0 to 3 byte) 337 unsigned integer (uint, see Section 3.2 of [RFC7252]). This integer 338 value encodes these three fields, see Figure 1. (Due to the CoAP 339 uint encoding rules, when all of NUM, M, and SZX happen to be zero, a 340 zero-byte integer will be sent.) 342 0 343 0 1 2 3 4 5 6 7 344 +-+-+-+-+-+-+-+-+ 345 | NUM |M| SZX | 346 +-+-+-+-+-+-+-+-+ 348 0 1 349 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 350 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 351 | NUM |M| SZX | 352 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 354 0 1 2 355 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 356 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 357 | NUM |M| SZX | 358 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 360 Figure 1: Block option value 362 The block size is encoded using a three-bit unsigned integer (0 for 363 2**4 to 6 for 2**10 bytes), which we call the "SZX" ("size 364 exponent"); the actual block size is then "2**(SZX + 4)". SZX is 365 transferred in the three least significant bits of the option value 366 (i.e., "val & 7" where "val" is the value of the option). 368 The fourth least significant bit, the M or "more" bit ("val & 8"), 369 indicates whether more blocks are following or the current block-wise 370 transfer is the last block being transferred. 372 The option value divided by sixteen (the NUM field) is the sequence 373 number of the block currently being transferred, starting from zero. 374 The current transfer is therefore about the "size" bytes starting at 375 byte "NUM << (SZX + 4)". 377 Implementation note: As an implementation convenience, "(val & ~0xF) 378 << (val & 7)", i.e., the option value with the last 4 bits masked 379 out, shifted to the left by the value of SZX, gives the byte 380 position of the first byte of the block being transferred. 382 More specifically, within the option value of a Block1 or Block2 383 Option, the meaning of the option fields is defined as follows: 385 NUM: Block Number, indicating the block number being requested or 386 provided. Block number 0 indicates the first block of a body 387 (i.e., starting with the first byte of the body). 389 M: More Flag ("not last block"). For descriptive usage, this flag, 390 if unset, indicates that the payload in this message is the last 391 block in the body; when set it indicates that there are one or 392 more additional blocks available. When a Block2 Option is used in 393 a request to retrieve a specific block number ("control usage"), 394 the M bit MUST be sent as zero and ignored on reception. (In a 395 Block1 Option in a response, the M flag is used to indicate 396 atomicity, see below.) 398 SZX: Block Size. The block size is represented as three-bit 399 unsigned integer indicating the size of a block to the power of 400 two. Thus block size = 2**(SZX + 4). The allowed values of SZX 401 are 0 to 6, i.e., the minimum block size is 2**(0+4) = 16 and the 402 maximum is 2**(6+4) = 1024. The value 7 for SZX (which would 403 indicate a block size of 2048) is reserved, i.e. MUST NOT be sent 404 and MUST lead to a 4.00 Bad Request response code upon reception 405 in a request. 407 There is no default value for the Block1 and Block2 Options. Absence 408 of one of these options is equivalent to an option value of 0 with 409 respect to the value of NUM and M that could be given in the option, 410 i.e. it indicates that the current block is the first and only block 411 of the transfer (block number 0, M bit not set). However, in 412 contrast to the explicit value 0, which would indicate an SZX of 0 413 and thus a size value of 16 bytes, there is no specific explicit size 414 implied by the absence of the option -- the size is left unspecified. 415 (As for any uint, the explicit value 0 is efficiently indicated by a 416 zero-length option; this, therefore, is different in semantics from 417 the absence of the option.) 419 2.3. Block Options in Requests and Responses 421 The Block options are used in one of three roles: 423 o In descriptive usage, i.e., a Block2 Option in a response (such as 424 a 2.05 response for GET), or a Block1 Option in a request (a PUT 425 or POST): 427 * The NUM field in the option value describes what block number 428 is contained in the payload of this message. 430 * The M bit indicates whether further blocks need to be 431 transferred to complete the transfer of that body. 433 * The block size implied by SZX MUST match the size of the 434 payload in bytes, if the M bit is set. (SZX does not govern 435 the payload size if M is unset). For Block2, if the request 436 suggested a larger value of SZX, the next request MUST move SZX 437 down to the size given in the response. (The effect is that, 438 if the server uses the smaller of (1) its preferred block size 439 and (2) the block size requested, all blocks for a body use the 440 same block size.) 442 o A Block2 Option in control usage in a request (e.g., GET): 444 * The NUM field in the Block2 Option gives the block number of 445 the payload that is being requested to be returned in the 446 response. 448 * In this case, the M bit has no function and MUST be set to 449 zero. 451 * The block size given (SZX) suggests a block size (in the case 452 of block number 0) or repeats the block size of previous blocks 453 received (in the case of a non-zero block number). 455 o A Block1 Option in control usage in a response (e.g., a 2.xx 456 response for a PUT or POST request): 458 * The NUM field of the Block1 Option indicates what block number 459 is being acknowledged. 461 * If the M bit was set in the request, the server can choose 462 whether to act on each block separately, with no memory, or 463 whether to handle the request for the entire body atomically, 464 or any mix of the two. 466 + If the M bit is also set in the response, it indicates that 467 this response does not carry the final response code to the 468 request, i.e. the server collects further blocks from the 469 same endpoint and plans to implement the request atomically 470 (e.g., acts only upon reception of the last block of 471 payload). In this case, the response MUST NOT carry a 472 Block2 option. 474 + Conversely, if the M bit is unset even though it was set in 475 the request, it indicates the block-wise request was enacted 476 now specifically for this block, and the response carries 477 the final response to this request (and to any previous ones 478 with the M bit set in the response's Block1 Option in this 479 sequence of block-wise transfers); the client is still 480 expected to continue sending further blocks, the request 481 method for which may or may not also be enacted per-block. 482 (Note that the resource is now in a partially updated state; 483 this approach is only appropriate where exposing such an 484 intermediate state is acceptable. The client can reduce the 485 window by quickly continuing to update the resource, or, in 486 case of failure, restarting the update.) 488 * Finally, the SZX block size given in a control Block1 Option 489 indicates the largest block size preferred by the server for 490 transfers toward the resource that is the same or smaller than 491 the one used in the initial exchange; the client SHOULD use 492 this block size or a smaller one in all further requests in the 493 transfer sequence, even if that means changing the block size 494 (and possibly scaling the block number accordingly) from now 495 on. 497 Using one or both Block options, a single REST operation can be split 498 into multiple CoAP message exchanges. As specified in [RFC7252], 499 each of these message exchanges uses their own CoAP Message ID. 501 The Content-Format Option sent with the requests or responses MUST 502 reflect the content-format of the entire body. If blocks of a 503 response body arrive with different content-format options, it is up 504 to the client how to handle this error (it will typically abort any 505 ongoing block-wise transfer). If blocks of a request arrive at a 506 server with mismatching content-format options, the server MUST NOT 507 assemble them into a single request; this usually leads to a 4.08 508 (Request Entity Incomplete, Section 2.9.2) error response on the 509 mismatching block. 511 2.4. Using the Block2 Option 513 When a request is answered with a response carrying a Block2 Option 514 with the M bit set, the requester may retrieve additional blocks of 515 the resource representation by sending further requests with the same 516 options as the initial request and a Block2 Option giving the block 517 number and block size desired. In a request, the client MUST set the 518 M bit of a Block2 Option to zero and the server MUST ignore it on 519 reception. 521 To influence the block size used in a response, the requester MAY 522 also use the Block2 Option on the initial request, giving the desired 523 size, a block number of zero and an M bit of zero. A server MUST use 524 the block size indicated or a smaller size. Any further block-wise 525 requests for blocks beyond the first one MUST indicate the same block 526 size that was used by the server in the response for the first 527 request that gave a desired size using a Block2 Option. 529 Once the Block2 Option is used by the requester and a first response 530 has been received with a possibly adjusted block size, all further 531 requests in a single block-wise transfer will ultimately converge on 532 using the same size, except that there may not be enough content to 533 fill the last block (the one returned with the M bit not set). (Note 534 that the client may start using the Block2 Option in a second request 535 after a first request without a Block2 Option resulted in a Block2 536 option in the response.) The server uses the block size indicated in 537 the request option or a smaller size, but the requester MUST take 538 note of the actual block size used in the response it receives to its 539 initial request and proceed to use it in subsequent requests. The 540 server behavior MUST ensure that this client behavior results in the 541 same block size for all responses in a sequence (except for the last 542 one with the M bit not set, and possibly the first one if the initial 543 request did not contain a Block2 Option). 545 Block-wise transfers can be used to GET resources the representations 546 of which are entirely static (not changing over time at all, such as 547 in a schema describing a device), or for dynamically changing 548 resources. In the latter case, the Block2 Option SHOULD be used in 549 conjunction with the ETag Option ([RFC7252], Section 5.10.6), to 550 ensure that the blocks being reassembled are from the same version of 551 the representation: The server SHOULD include an ETag option in each 552 response. If an ETag option is available, the client, when 553 reassembling the representation from the blocks being exchanged, MUST 554 compare ETag Options. If the ETag Options do not match in a GET 555 transfer, the requester has the option of attempting to retrieve 556 fresh values for the blocks it retrieved first. To minimize the 557 resulting inefficiency, the server MAY cache the current value of a 558 representation for an ongoing sequence of requests. (The server may 559 identify the sequence by the combination of the requesting end-point 560 and the URI being the same in each block-wise request.) Note well 561 that this specification makes no requirement for the server to 562 establish any state; however, servers that offer quickly changing 563 resources may thereby make it impossible for a client to ever 564 retrieve a consistent set of blocks. Clients that want to retrieve 565 all blocks of a resource SHOULD strive to do so without undue delay. 566 Servers can fully expect to be free to discard any cached state after 567 a period of EXCHANGE_LIFETIME ([RFC7252], Section 4.8.2) after the 568 last access to the state, however, there is no requirement to always 569 keep the state for as long. 571 The Block2 option provides no way for a single endpoint to perform 572 multiple concurrently proceeding block-wise response payload transfer 573 (e.g., GET) operations to the same resource. This is rarely a 574 requirement, but as a workaround, a client may vary the cache key 575 (e.g., by using one of several URIs accessing resources with the same 576 semantics, or by varying a proxy-safe elective option). 578 2.5. Using the Block1 Option 580 In a request with a request payload (e.g., PUT or POST), the Block1 581 Option refers to the payload in the request (descriptive usage). 583 In response to a request with a payload (e.g., a PUT or POST 584 transfer), the block size given in the Block1 Option indicates the 585 block size preference of the server for this resource (control 586 usage). Obviously, at this point the first block has already been 587 transferred by the client without benefit of this knowledge. Still, 588 the client SHOULD heed the preference indicated and, for all further 589 blocks, use the block size preferred by the server or a smaller one. 590 Note that any reduction in the block size may mean that the second 591 request starts with a block number larger than one, as the first 592 request already transferred multiple blocks as counted in the smaller 593 size. 595 To counter the effects of adaptation layer fragmentation on packet 596 delivery probability, a client may want to give up retransmitting a 597 request with a relatively large payload even before MAX_RETRANSMIT 598 has been reached, and try restating the request as a block-wise 599 transfer with a smaller payload. Note that this new attempt is then 600 a new message-layer transaction and requires a new Message ID. 601 (Because of the uncertainty whether the request or the 602 acknowledgement was lost, this strategy is useful mostly for 603 idempotent requests.) 605 In a block-wise transfer of a request payload (e.g., a PUT or POST) 606 that is intended to be implemented in an atomic fashion at the 607 server, the actual creation/replacement takes place at the time the 608 final block, i.e. a block with the M bit unset in the Block1 Option, 609 is received. In this case, all success responses to non-final blocks 610 carry the response code 2.31 (Continue, Section 2.9.1). If not all 611 previous blocks are available at the server at the time of processing 612 the final block, the transfer fails and error code 4.08 (Request 613 Entity Incomplete, Section 2.9.2) MUST be returned. A server MAY 614 also return a 4.08 error code for any (final or non-final) Block1 615 transfer that is not in sequence; clients that do not have specific 616 mechanisms to handle this case therefore SHOULD always start with 617 block zero and send the following blocks in order. 619 One reason that a client might encounter a 4.08 error code is that 620 the server has already timed out and discarded the partial request 621 body being assembled. Clients SHOULD strive to send all blocks of a 622 request without undue delay. Servers can fully expect to be free to 623 discard any partial request body when a period of EXCHANGE_LIFETIME 624 ([RFC7252], Section 4.8.2) has elapsed after the most recent block 625 was transferred; however, there is no requirement on a server to 626 always keep the partial request body for as long. 628 The error code 4.13 (Request Entity Too Large) can be returned at any 629 time by a server that does not currently have the resources to store 630 blocks for a block-wise request payload transfer that it would intend 631 to implement in an atomic fashion. (Note that a 4.13 response to a 632 request that does not employ Block1 is a hint for the client to try 633 sending Block1, and a 4.13 response with a smaller SZX in its Block1 634 option than requested is a hint to try a smaller SZX.) 636 A block-wise transfer of a request payload that is implemented in a 637 stateless fashion at the server is likely to leave the resource being 638 operated on in an inconsistent state during the time the transfer is 639 still ongoing or when the client does not complete the transfer. 640 This characteristic is closer to that of remote file systems than to 641 that of HTTP, where state is always kept on the server during a 642 transfer. Techniques well known from shared file access (e.g., 643 client-specific temporary resources) can be used to mitigate this 644 difference from HTTP. 646 The Block1 option provides no way for a single endpoint to perform 647 multiple concurrently proceeding block-wise request payload transfer 648 (e.g., PUT or POST) operations to the same resource. Starting a new 649 block-wise sequence of requests to the same resource (before an old 650 sequence from the same endpoint was finished) simply overwrites the 651 context the server may still be keeping. (This is probably exactly 652 what one wants in this case -- the client may simply have restarted 653 and lost its knowledge of the previous sequence.) 655 2.6. Combining Block-wise Transfers with the Observe Option 657 The Observe Option provides a way for a client to be notified about 658 changes over time of a resource [RFC7641]. Resources observed by 659 clients may be larger than can be comfortably processed or 660 transferred in one CoAP message. The following rules apply to the 661 combination of block-wise transfers with notifications. 663 Observation relationships always apply to an entire resource; the 664 Block2 option does not provide a way to observe a single block of a 665 resource. 667 As with basic GET transfers, the client can indicate its desired 668 block size in a Block2 Option in the GET request establishing or 669 renewing the observation relationship. If the server supports block- 670 wise transfers, it SHOULD take note of the block size and apply it as 671 a maximum size to all notifications/responses resulting from the GET 672 request (until the client is removed from the list of observers or 673 the entry in that list is updated by the server receiving a new GET 674 request for the resource from the client). 676 When sending a 2.05 (Content) notification, the server only sends the 677 first block of the representation. The client retrieves the rest of 678 the representation as if it had caused this first response by a GET 679 request, i.e., by using additional GET requests with Block2 options 680 containing NUM values greater than zero. (This results in the 681 transfer of the entire representation, even if only some of the 682 blocks have changed with respect to a previous notification.) 684 As with other dynamically changing resources, to ensure that the 685 blocks being reassembled are from the same version of the 686 representation, the server SHOULD include an ETag option in each 687 response, and the reassembling client MUST compare the ETag options 688 (Section 2.4). Even more so than for the general case of Block2, 689 clients that want to retrieve all blocks of a resource they have been 690 notified about with a first block SHOULD strive to do so without 691 undue delay. 693 See Section 3.4 for examples. 695 2.7. Combining Block1 and Block2 697 In PUT and particularly in POST exchanges, both the request body and 698 the response body may be large enough to require the use of block- 699 wise transfers. First, the Block1 transfer of the request body 700 proceeds as usual. In the exchange of the last slice of this block- 701 wise transfer, the response carries the first slice of the Block2 702 transfer (NUM is zero). To continue this Block2 transfer, the client 703 continues to send requests similar to the requests in the Block1 704 phase, but leaves out the Block1 options and includes a Block2 705 request option with non-zero NUM. 707 Block2 transfers that retrieve the response body for a request that 708 used Block1 MUST be performed in sequential order. 710 2.8. Combining Block2 with Multicast 712 A client can use the Block2 option in a multicast GET request with 713 NUM = 0 to aid in limiting the size of the response. 715 Similarly, a response to a multicast GET request can use a Block2 716 option with NUM = 0 if the representation is large, or to further 717 limit the size of the response. 719 In both cases, the client retrieves any further blocks using unicast 720 exchanges; in the unicast requests, the client SHOULD heed any block 721 size preferences indicated by the server in the response to the 722 multicast request. 724 Other uses of the Block options in conjunction with multicast 725 messages are for further study. 727 2.9. Response Codes 729 Two response codes are defined by this specification beyond those 730 already defined in [RFC7252], and another response code is extended 731 in its meaning. 733 2.9.1. 2.31 Continue 735 This new success status code indicates that the transfer of this 736 block of the request body was successful and that the server 737 encourages sending further blocks, but that a final outcome of the 738 whole block-wise request cannot yet be determined. No payload is 739 returned with this response code. 741 2.9.2. 4.08 Request Entity Incomplete 743 This new client error status code indicates that the server has not 744 received the blocks of the request body that it needs to proceed. 745 The client has not sent all blocks, not sent them in the order 746 required by the server, or has sent them long enough ago that the 747 server has already discarded them. 749 (Note that one reason for not having the necessary blocks at hand may 750 be a Content-Format mismatch, see Section 2.3. Implementation note: 751 A server can reject a Block1 transfer with this code when NUM != 0 752 and a different Content-Format is indicated than expected from the 753 current state of the resource. If it implements the transfer in a 754 stateless fashion, it can match up the Content-Format of the block 755 against that of the existing resource. If it implements the transfer 756 in an atomic fashion, it can match up the block against the partially 757 reassembled piece of representation that is going to replace the 758 state of the resource.) 760 2.9.3. 4.13 Request Entity Too Large 762 In [RFC7252], Section 5.9.2.9, the response code 4.13 (Request Entity 763 Too Large) is defined to be like HTTP 413 "Request Entity Too Large". 764 [RFC7252] also recommends that this response SHOULD include a Size1 765 Option (Section 4) to indicate the maximum size of request entity the 766 server is able and willing to handle, unless the server is not in a 767 position to make this information available. 769 The present specification allows the server to return this response 770 code at any time during a Block1 transfer to indicate that it does 771 not currently have the resources to store blocks for a transfer that 772 it would intend to implement in an atomic fashion. It also allows 773 the server to return a 4.13 response to a request that does not 774 employ Block1 as a hint for the client to try sending Block1. 775 Finally, a 4.13 response to a request with a Block1 option (control 776 usage, see Section 2.3) where the response carries a smaller SZX in 777 its Block1 option is a hint to try that smaller SZX. 779 2.10. Caching Considerations 781 This specification attempts to leave a variety of implementation 782 strategies open for caches, in particular those in caching proxies. 783 E.g., a cache is free to cache blocks individually, but also could 784 wait to obtain the complete representation before it serves parts of 785 it. Partial caching may be more efficient in a cross-proxy 786 (equivalent to a streaming HTTP proxy). A cached block (partial 787 cached response) can be used in place of a complete response to 788 satisfy a block-wise request that is presented to a cache. Note that 789 different blocks can have different Max-Age values, as they are 790 transferred at different times. A response with a block updates the 791 freshness of the complete representation. Individual blocks can be 792 validated, and validating a single block validates the complete 793 representation. A response with a Block1 Option in control usage 794 with the M bit set invalidates cached responses for the target URI. 796 A cache or proxy that combines responses (e.g., to split blocks in a 797 request or increase the block size in a response, or a cross-proxy) 798 may need to combine 2.31 and 2.01/2.04 responses; a stateless server 799 may be responding with 2.01 only on the first Block1 block 800 transferred, which dominates any 2.04 responses for later blocks. 802 If-None-Match only works correctly on Block1 requests with (NUM=0) 803 and MUST NOT be used on Block1 requests with NUM != 0. 805 3. Examples 807 This section gives a number of short examples with message flows for 808 a block-wise GET, and for a PUT or POST. These examples demonstrate 809 the basic operation, the operation in the presence of 810 retransmissions, and examples for the operation of the block size 811 negotiation. 813 In all these examples, a Block option is shown in a decomposed way 814 indicating the kind of Block option (1 or 2) followed by a colon, and 815 then the block number (NUM), more bit (M), and block size exponent 816 (2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33 817 would be shown as 2:2/0/32), or a Block1 Option value of 59 would be 818 shown as 1:3/1/128. 820 As in [RFC7252], "MID" is used as an abbreviation of "Message ID". 822 3.1. Block2 Examples 824 The first example (Figure 2) shows a GET request that is split into 825 three blocks. The server proposes a block size of 128, and the 826 client agrees. The first two ACKs contain a payload of 128 bytes 827 each, and the third ACK contains a payload between 1 and 128 bytes. 829 CLIENT SERVER 830 | | 831 | CON [MID=1234], GET, /status ------> | 832 | | 833 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 834 | | 835 | CON [MID=1235], GET, /status, 2:1/0/128 ------> | 836 | | 837 | <------ ACK [MID=1235], 2.05 Content, 2:1/1/128 | 838 | | 839 | CON [MID=1236], GET, /status, 2:2/0/128 ------> | 840 | | 841 | <------ ACK [MID=1236], 2.05 Content, 2:2/0/128 | 843 Figure 2: Simple block-wise GET 845 In the second example (Figure 3), the client anticipates the block- 846 wise transfer (e.g., because of a size indication in the link-format 847 description [RFC6690]) and sends a block size proposal. All ACK 848 messages except for the last carry 64 bytes of payload; the last one 849 carries between 1 and 64 bytes. 851 CLIENT SERVER 852 | | 853 | CON [MID=1234], GET, /status, 2:0/0/64 ------> | 854 | | 855 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/64 | 856 | | 857 | CON [MID=1235], GET, /status, 2:1/0/64 ------> | 858 | | 859 | <------ ACK [MID=1235], 2.05 Content, 2:1/1/64 | 860 : : 861 : ... : 862 : : 863 | CON [MID=1238], GET, /status, 2:4/0/64 ------> | 864 | | 865 | <------ ACK [MID=1238], 2.05 Content, 2:4/1/64 | 866 | | 867 | CON [MID=1239], GET, /status, 2:5/0/64 ------> | 868 | | 869 | <------ ACK [MID=1239], 2.05 Content, 2:5/0/64 | 871 Figure 3: Block-wise GET with early negotiation 873 In the third example (Figure 4), the client is surprised by the need 874 for a block-wise transfer, and unhappy with the size chosen 875 unilaterally by the server. As it did not send a size proposal 876 initially, the negotiation only influences the size from the second 877 message exchange onward. Since the client already obtained both the 878 first and second 64-byte block in the first 128-byte exchange, it 879 goes on requesting the third 64-byte block ("2/0/64"). None of this 880 is (or needs to be) understood by the server, which simply responds 881 to the requests as it best can. 883 CLIENT SERVER 884 | | 885 | CON [MID=1234], GET, /status ------> | 886 | | 887 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 888 | | 889 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 890 | | 891 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 892 | | 893 | CON [MID=1236], GET, /status, 2:3/0/64 ------> | 894 | | 895 | <------ ACK [MID=1236], 2.05 Content, 2:3/1/64 | 896 | | 897 | CON [MID=1237], GET, /status, 2:4/0/64 ------> | 898 | | 899 | <------ ACK [MID=1237], 2.05 Content, 2:4/1/64 | 900 | | 901 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 902 | | 903 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 905 Figure 4: Block-wise GET with late negotiation 907 In all these (and the following) cases, retransmissions are handled 908 by the CoAP message exchange layer, so they don't influence the block 909 operations (Figure 5, Figure 6). 911 CLIENT SERVER 912 | | 913 | CON [MID=1234], GET, /status ------> | 914 | | 915 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 916 | | 917 | CON [MID=1235], GE///////////////////////// | 918 | | 919 | (timeout) | 920 | | 921 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 922 | | 923 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 924 : : 925 : ... : 926 : : 927 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 928 | | 929 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 931 Figure 5: Block-wise GET with late negotiation and lost CON 933 CLIENT SERVER 934 | | 935 | CON [MID=1234], GET, /status ------> | 936 | | 937 | <------ ACK [MID=1234], 2.05 Content, 2:0/1/128 | 938 | | 939 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 940 | | 941 | //////////////////////////////////tent, 2:2/1/64 | 942 | | 943 | (timeout) | 944 | | 945 | CON [MID=1235], GET, /status, 2:2/0/64 ------> | 946 | | 947 | <------ ACK [MID=1235], 2.05 Content, 2:2/1/64 | 948 : : 949 : ... : 950 : : 951 | CON [MID=1238], GET, /status, 2:5/0/64 ------> | 952 | | 953 | <------ ACK [MID=1238], 2.05 Content, 2:5/0/64 | 955 Figure 6: Block-wise GET with late negotiation and lost ACK 957 3.2. Block1 Examples 959 The following examples demonstrate a PUT exchange; a POST exchange 960 looks the same, with different requirements on atomicity/idempotence. 961 Note that, similar to GET, the responses to the requests that have a 962 more bit in the request Block1 Option are provisional and carry the 963 response code 2.31 (Continue); only the final response tells the 964 client that the PUT did succeed. 966 CLIENT SERVER 967 | | 968 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 969 | | 970 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 971 | | 972 | CON [MID=1235], PUT, /options, 1:1/1/128 ------> | 973 | | 974 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 975 | | 976 | CON [MID=1236], PUT, /options, 1:2/0/128 ------> | 977 | | 978 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | 980 Figure 7: Simple atomic block-wise PUT 982 A stateless server that simply builds/updates the resource in place 983 (statelessly) may indicate this by not setting the more bit in the 984 response (Figure 8); in this case, the response codes are valid 985 separately for each block being updated. This is of course only an 986 acceptable behavior of the server if the potential inconsistency 987 present during the run of the message exchange sequence does not lead 988 to problems, e.g. because the resource being created or changed is 989 not yet or not currently in use. 991 CLIENT SERVER 992 | | 993 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 994 | | 995 | <------ ACK [MID=1234], 2.04 Changed, 1:0/0/128 | 996 | | 997 | CON [MID=1235], PUT, /options, 1:1/1/128 ------> | 998 | | 999 | <------ ACK [MID=1235], 2.04 Changed, 1:1/0/128 | 1000 | | 1001 | CON [MID=1236], PUT, /options, 1:2/0/128 ------> | 1002 | | 1003 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128 | 1005 Figure 8: Simple stateless block-wise PUT 1007 Finally, a server receiving a block-wise PUT or POST may want to 1008 indicate a smaller block size preference (Figure 9). In this case, 1009 the client SHOULD continue with a smaller block size; if it does, it 1010 MUST adjust the block number to properly count in that smaller size. 1012 CLIENT SERVER 1013 | | 1014 | CON [MID=1234], PUT, /options, 1:0/1/128 ------> | 1015 | | 1016 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/32 | 1017 | | 1018 | CON [MID=1235], PUT, /options, 1:4/1/32 ------> | 1019 | | 1020 | <------ ACK [MID=1235], 2.31 Continue, 1:4/1/32 | 1021 | | 1022 | CON [MID=1236], PUT, /options, 1:5/1/32 ------> | 1023 | | 1024 | <------ ACK [MID=1235], 2.31 Continue, 1:5/1/32 | 1025 | | 1026 | CON [MID=1237], PUT, /options, 1:6/0/32 ------> | 1027 | | 1028 | <------ ACK [MID=1236], 2.04 Changed, 1:6/0/32 | 1030 Figure 9: Simple atomic block-wise PUT with negotiation 1032 3.3. Combining Block1 and Block2 1034 Block options may be used in both directions of a single exchange. 1035 The following example demonstrates a block-wise POST request, 1036 resulting in a separate block-wise response. 1038 CLIENT SERVER 1039 | | 1040 | CON [MID=1234], POST, /soap, 1:0/1/128 ------> | 1041 | | 1042 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 1043 | | 1044 | CON [MID=1235], POST, /soap, 1:1/1/128 ------> | 1045 | | 1046 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 1047 | | 1048 | CON [MID=1236], POST, /soap, 1:2/0/128 ------> | 1049 | | 1050 | <------ ACK [MID=1236], 2.04 Changed, 2:0/1/128, 1:2/0/128 | 1051 | | 1052 | CON [MID=1237], POST, /soap, 2:1/0/128 ------> | 1053 | (no payload for requests with Block2 with NUM != 0) | 1054 | (could also do late negotiation by requesting e.g. 2:2/0/64) | 1055 | | 1056 | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/128 | 1057 | | 1058 | CON [MID=1238], POST, /soap, 2:2/0/128 ------> | 1059 | | 1060 | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/128 | 1061 | | 1062 | CON [MID=1239], POST, /soap, 2:3/0/128 ------> | 1063 | | 1064 | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/128 | 1066 Figure 10: Atomic block-wise POST with block-wise response 1068 This model does provide for early negotiation input to the Block2 1069 block-wise transfer, as shown below. 1071 CLIENT SERVER 1072 | | 1073 | CON [MID=1234], POST, /soap, 1:0/1/128 ------> | 1074 | | 1075 | <------ ACK [MID=1234], 2.31 Continue, 1:0/1/128 | 1076 | | 1077 | CON [MID=1235], POST, /soap, 1:1/1/128 ------> | 1078 | | 1079 | <------ ACK [MID=1235], 2.31 Continue, 1:1/1/128 | 1080 | | 1081 | CON [MID=1236], POST, /soap, 1:2/0/128, 2:0/0/64 ------> | 1082 | | 1083 | <------ ACK [MID=1236], 2.04 Changed, 1:2/0/128, 2:0/1/64 | 1084 | | 1085 | CON [MID=1237], POST, /soap, 2:1/0/64 ------> | 1086 | (no payload for requests with Block2 with NUM != 0) | 1087 | | 1088 | <------ ACK [MID=1237], 2.04 Changed, 2:1/1/64 | 1089 | | 1090 | CON [MID=1238], POST, /soap, 2:2/0/64 ------> | 1091 | | 1092 | <------ ACK [MID=1238], 2.04 Changed, 2:2/1/64 | 1093 | | 1094 | CON [MID=1239], POST, /soap, 2:3/0/64 ------> | 1095 | | 1096 | <------ ACK [MID=1239], 2.04 Changed, 2:3/0/64 | 1098 Figure 11: Atomic block-wise POST with block-wise response, early 1099 negotiation 1101 3.4. Combining Observe and Block2 1103 In the following example, the server first sends a direct response 1104 (Observe sequence number 62350) to the initial GET request (the 1105 resulting block-wise transfer is as in Figure 4 and has therefore 1106 been left out). The second transfer is started by a 2.05 1107 notification that contains just the first block (Observe sequence 1108 number 62354); the client then goes on to obtain the rest of the 1109 blocks. 1111 CLIENT SERVER 1112 | | 1113 +----->| Header: GET 0x41011636 1114 | GET | Token: 0xfb 1115 | | Uri-Path: status-icon 1116 | | Observe: (empty) 1117 | | 1118 |<-----+ Header: 2.05 0x61451636 1119 | 2.05 | Token: 0xfb 1120 | | Block2: 0/1/128 1121 | | Observe: 62350 1122 | | ETag: 6f00f38e 1123 | | Payload: [128 bytes] 1124 | | 1125 | | (Usual GET transfer left out) 1126 ... 1127 | | (Notification of first block:) 1128 | | 1129 |<-----+ Header: 2.05 0x4145af9c 1130 | 2.05 | Token: 0xfb 1131 | | Block2: 0/1/128 1132 | | Observe: 62354 1133 | | ETag: 6f00f392 1134 | | Payload: [128 bytes] 1135 | | 1136 +- - ->| Header: 0x6000af9c 1137 | | 1138 | | (Retrieval of remaining blocks) 1139 | | 1140 +----->| Header: GET 0x41011637 1141 | GET | Token: 0xfc 1142 | | Uri-Path: status-icon 1143 | | Block2: 1/0/128 1144 | | 1145 |<-----+ Header: 2.05 0x61451637 1146 | 2.05 | Token: 0xfc 1147 | | Block2: 1/1/128 1148 | | ETag: 6f00f392 1149 | | Payload: [128 bytes] 1150 | | 1151 +----->| Header: GET 0x41011638 1152 | GET | Token: 0xfc 1153 | | Uri-Path: status-icon 1154 | | Block2: 2/0/128 1155 | | 1156 |<-----+ Header: 2.05 0x61451638 1157 | 2.05 | Token: 0xfc 1158 | | Block2: 2/0/128 1159 | | ETag: 6f00f392 1160 | | Payload: [53 bytes] 1162 Figure 12: Observe sequence with block-wise response 1164 (Note that the choice of token 0xfc in this examples is arbitrary; 1165 tokens are just shown in this example to illustrate that the requests 1166 for additional blocks cannot make use of the token of the Observation 1167 relationship. As a general comment on tokens, there is no other 1168 mention of tokens in this document, as block-wise transfers handle 1169 tokens like any other CoAP exchange. As usual the client is free to 1170 choose tokens for each exchange as it likes.) 1172 In the following example, the client also uses early negotiation to 1173 limit the block size to 64 bytes. 1175 CLIENT SERVER 1176 | | 1177 +----->| Header: GET 0x41011636 1178 | GET | Token: 0xfb 1179 | | Uri-Path: status-icon 1180 | | Observe: (empty) 1181 | | Block2: 0/0/64 1182 | | 1183 |<-----+ Header: 2.05 0x61451636 1184 | 2.05 | Token: 0xfb 1185 | | Block2: 0/1/64 1186 | | Observe: 62350 1187 | | ETag: 6f00f38e 1188 | | Max-Age: 60 1189 | | Payload: [64 bytes] 1190 | | 1191 | | (Usual GET transfer left out) 1192 ... 1193 | | (Notification of first block:) 1194 | | 1195 |<-----+ Header: 2.05 0x4145af9c 1196 | 2.05 | Token: 0xfb 1197 | | Block2: 0/1/64 1198 | | Observe: 62354 1199 | | ETag: 6f00f392 1200 | | Payload: [64 bytes] 1201 | | 1202 +- - ->| Header: 0x6000af9c 1203 | | 1204 | | (Retrieval of remaining blocks) 1205 | | 1206 +----->| Header: GET 0x41011637 1207 | GET | Token: 0xfc 1208 | | Uri-Path: status-icon 1209 | | Block2: 1/0/64 1210 | | 1211 |<-----+ Header: 2.05 0x61451637 1212 | 2.05 | Token: 0xfc 1213 | | Block2: 1/1/64 1214 | | ETag: 6f00f392 1215 | | Payload: [64 bytes] 1216 .... 1217 | | 1218 +----->| Header: GET 0x41011638 1219 | GET | Token: 0xfc 1220 | | Uri-Path: status-icon 1221 | | Block2: 4/0/64 1222 | | 1223 |<-----+ Header: 2.05 0x61451638 1224 | 2.05 | Token: 0xfc 1225 | | Block2: 4/0/64 1226 | | ETag: 6f00f392 1227 | | Payload: [53 bytes] 1229 Figure 13: Observe sequence with early negotiation 1231 4. The Size2 and Size1 Options 1233 In many cases when transferring a large resource representation block 1234 by block, it is advantageous to know the total size early in the 1235 process. Some indication may be available from the maximum size 1236 estimate attribute "sz" provided in a resource description [RFC6690]. 1237 However, the size may vary dynamically, so a more up-to-date 1238 indication may be useful. 1240 This specification defines two CoAP Options, Size1 for indicating the 1241 size of the representation transferred in requests, and Size2 for 1242 indicating the size of the representation transferred in responses. 1243 (Size1 has already been defined in Section 5.10.9 of [RFC7252] to 1244 provide "size information about the resource representation in a 1245 request", however that section only details the narrow case of 1246 indicating in 4.13 responses the maximum size of request payload that 1247 the server is able and willing to handle. The present specification 1248 provides details about its use as a request option as well.) 1250 The Size2 Option may be used for two purposes: 1252 o in a request, to ask the server to provide a size estimate along 1253 with the usual response ("size request"). For this usage, the 1254 value MUST be set to 0. 1256 o in a response carrying a Block2 Option, to indicate the current 1257 estimate the server has of the total size of the resource 1258 representation, measured in bytes ("size indication"). 1260 Similarly, the Size1 Option may be used for two purposes: 1262 o in a request carrying a Block1 Option, to indicate the current 1263 estimate the client has of the total size of the resource 1264 representation, measured in bytes ("size indication"). 1266 o in a 4.13 response, to indicate the maximum size that would have 1267 been acceptable [RFC7252], measured in bytes. 1269 Apart from conveying/asking for size information, the Size options 1270 have no other effect on the processing of the request or response. 1271 If the client wants to minimize the size of the payload in the 1272 resulting response, it should add a Block2 option to the request with 1273 a small block size (e.g., setting SZX=0). 1275 The Size Options are "elective", i.e., a client MUST be prepared for 1276 the server to ignore the size estimate request. The Size Options 1277 MUST NOT occur more than once. 1279 +-----+---+---+---+---+-------+--------+--------+---------+ 1280 | No. | C | U | N | R | Name | Format | Length | Default | 1281 +-----+---+---+---+---+-------+--------+--------+---------+ 1282 | 60 | | | x | | Size1 | uint | 0-4 | (none) | 1283 | | | | | | | | | | 1284 | 28 | | | x | | Size2 | uint | 0-4 | (none) | 1285 +-----+---+---+---+---+-------+--------+--------+---------+ 1287 Table 2: Size Option Numbers 1289 Implementation Notes: 1291 o As a quality of implementation consideration, block-wise transfers 1292 for which the total size considerably exceeds the size of one 1293 block are expected to include size indications, whenever those can 1294 be provided without undue effort (preferably with the first block 1295 exchanged). If the size estimate does not change, the indication 1296 does not need to be repeated for every block. 1298 o The end of a block-wise transfer is governed by the M bits in the 1299 Block Options, _not_ by exhausting the size estimates exchanged. 1301 o As usual for an option of type uint, the value 0 is best expressed 1302 as an empty option (0 bytes). There is no default value for 1303 either Size Option. 1305 o The Size Options are neither critical nor unsafe, and are marked 1306 as No-Cache-Key. 1308 5. HTTP Mapping Considerations 1310 In this subsection, we give some brief examples for the influence the 1311 Block options might have on intermediaries that map between CoAP and 1312 HTTP. 1314 For mapping CoAP requests to HTTP, the intermediary may want to map 1315 the sequence of block-wise transfers into a single HTTP transfer. 1316 E.g., for a GET request, the intermediary could perform the HTTP 1317 request once the first block has been requested and could then 1318 fulfill all further block requests out of its cache. A constrained 1319 implementation may not be able to cache the entire object and may use 1320 a combination of TCP flow control and (in particular if timeouts 1321 occur) HTTP range requests to obtain the information necessary for 1322 the next block transfer at the right time. 1324 For PUT or POST requests, historically there was more variation in 1325 how HTTP servers might implement ranges; recently, [RFC7233] has 1326 defined that Range header fields received with a request method other 1327 than GET are not to be interpreted. So, in general, the CoAP-to-HTTP 1328 intermediary will have to try sending the payload of all the blocks 1329 of a block-wise transfer for these other methods within one HTTP 1330 request. If enough buffering is available, this request can be 1331 started when the last CoAP block is received. A constrained 1332 implementation may want to relieve its buffering by already starting 1333 to send the HTTP request at the time the first CoAP block is 1334 received; any HTTP 408 status code that indicates that the HTTP 1335 server became impatient with the resulting transfer can then be 1336 mapped into a CoAP 4.08 response code (similarly, 413 maps to 4.13). 1338 For mapping HTTP to CoAP, the intermediary may want to map a single 1339 HTTP transfer into a sequence of block-wise transfers. If the HTTP 1340 client is too slow delivering a request body on a PUT or POST, the 1341 CoAP server might time out and return a 4.08 response code, which in 1342 turn maps well to an HTTP 408 status code (again, 4.13 maps to 413). 1343 HTTP range requests received on the HTTP side may be served out of a 1344 cache and/or mapped to GET requests that request a sequence of blocks 1345 overlapping the range. 1347 (Note that, while the semantics of CoAP 4.08 and HTTP 408 differ, 1348 this difference is largely due to the different way the two protocols 1349 are mapped to transport. HTTP has an underlying TCP connection, 1350 which supplies connection state, so a HTTP 408 status code can 1351 immediately be used to indicate that a timeout occurred during 1352 transmitting a request through that active TCP connection. The CoAP 1353 4.08 response code indicates one or more missing blocks, which may be 1354 due to timeouts or resource constraints; as there is no connection 1355 state, there is no way to deliver such a response immediately; 1356 instead, it is delivered on the next block transfer. Still, HTTP 408 1357 is probably the best mapping back to HTTP, as the timeout is the most 1358 likely cause for a CoAP 4.08. Note that there is no way to 1359 distinguish a timeout from a missing block for a server without 1360 creating additional state, the need for which we want to avoid.) 1362 6. IANA Considerations 1364 This draft adds the following option numbers to the CoAP Option 1365 Numbers registry of [RFC7252]: 1367 +--------+--------+-----------+ 1368 | Number | Name | Reference | 1369 +--------+--------+-----------+ 1370 | 23 | Block2 | [RFCXXXX] | 1371 | | | | 1372 | 27 | Block1 | [RFCXXXX] | 1373 | | | | 1374 | 28 | Size2 | [RFCXXXX] | 1375 +--------+--------+-----------+ 1377 Table 3: CoAP Option Numbers 1379 This draft adds the following response code to the CoAP Response 1380 Codes registry of [RFC7252]: 1382 +------+---------------------------+-----------+ 1383 | Code | Description | Reference | 1384 +------+---------------------------+-----------+ 1385 | 2.31 | Continue | [RFCXXXX] | 1386 | | | | 1387 | 4.08 | Request Entity Incomplete | [RFCXXXX] | 1388 +------+---------------------------+-----------+ 1390 Table 4: CoAP Response Codes 1392 7. Security Considerations 1394 Providing access to blocks within a resource may lead to surprising 1395 vulnerabilities. Where requests are not implemented atomically, an 1396 attacker may be able to exploit a race condition or confuse a server 1397 by inducing it to use a partially updated resource representation. 1398 Partial transfers may also make certain problematic data invisible to 1399 intrusion detection systems; it is RECOMMENDED that an intrusion 1400 detection system (IDS) that analyzes resource representations 1401 transferred by CoAP implement the Block options to gain access to 1402 entire resource representations. Still, approaches such as 1403 transferring even-numbered blocks on one path and odd-numbered blocks 1404 on another path, or even transferring blocks multiple times with 1405 different content and obtaining a different interpretation of 1406 temporal order at the IDS than at the server, may prevent an IDS from 1407 seeing the whole picture. These kinds of attacks are well understood 1408 from IP fragmentation and TCP segmentation; CoAP does not add 1409 fundamentally new considerations. 1411 Where access to a resource is only granted to clients making use of 1412 specific security associations, all blocks of that resource MUST be 1413 subject to the same security checks; it MUST NOT be possible for 1414 unprotected exchanges to influence blocks of an otherwise protected 1415 resource. As a related consideration, where object security is 1416 employed, PUT/POST should be implemented in the atomic fashion, 1417 unless the object security operation is performed on each access and 1418 the creation of unusable resources can be tolerated. Future end-to- 1419 end security mechanisms that may be added to CoAP itself may have 1420 related security considerations, this includes considerations about 1421 caching of blocks in clients and in proxies (see Section 2.10 and 1422 Section 5 for different strategies in performing this caching); these 1423 security considerations will need to be described in the 1424 specifications of those mechanisms. 1426 A stateless server might be susceptible to an attack where the 1427 adversary sends a Block1 (e.g., PUT) block with a high block number: 1428 A naive implementation might exhaust its resources by creating a huge 1429 resource representation. 1431 Misleading size indications may be used by an attacker to induce 1432 buffer overflows in poor implementations, for which the usual 1433 considerations apply. 1435 7.1. Mitigating Resource Exhaustion Attacks 1437 Certain block-wise requests may induce the server to create state, 1438 e.g. to create a snapshot for the block-wise GET of a fast-changing 1439 resource to enable consistent access to the same version of a 1440 resource for all blocks, or to create temporary resource 1441 representations that are collected until pressed into service by a 1442 final PUT or POST with the more bit unset. All mechanisms that 1443 induce a server to create state that cannot simply be cleaned up 1444 create opportunities for denial-of-service attacks. Servers SHOULD 1445 avoid being subject to resource exhaustion based on state created by 1446 untrusted sources. But even if this is done, the mitigation may 1447 cause a denial-of-service to a legitimate request when it is drowned 1448 out by other state-creating requests. Wherever possible, servers 1449 should therefore minimize the opportunities to create state for 1450 untrusted sources, e.g. by using stateless approaches. 1452 Performing segmentation at the application layer is almost always 1453 better in this respect than at the transport layer or lower (IP 1454 fragmentation, adaptation layer fragmentation), for instance because 1455 there is application layer semantics that can be used for mitigation 1456 or because lower layers provide security associations that can 1457 prevent attacks. However, it is less common to apply timeouts and 1458 keepalive mechanisms at the application layer than at lower layers. 1459 Servers MAY want to clean up accumulated state by timing it out (cf. 1460 response code 4.08), and clients SHOULD be prepared to run block-wise 1461 transfers in an expedient way to minimize the likelihood of running 1462 into such a timeout. 1464 7.2. Mitigating Amplification Attacks 1466 [RFC7252] discusses the susceptibility of CoAP end-points for use in 1467 amplification attacks. 1469 A CoAP server can reduce the amount of amplification it provides to 1470 an attacker by offering large resource representations only in 1471 relatively small blocks. With this, e.g., for a 1000 byte resource, 1472 a 10-byte request might result in an 80-byte response (with a 64-byte 1473 block) instead of a 1016-byte response, considerably reducing the 1474 amplification provided. 1476 8. References 1478 8.1. Normative References 1480 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1481 Requirement Levels", BCP 14, RFC 2119, 1482 DOI 10.17487/RFC2119, March 1997, 1483 . 1485 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1486 Application Protocol (CoAP)", RFC 7252, 1487 DOI 10.17487/RFC7252, June 2014, 1488 . 1490 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1491 Application Protocol (CoAP)", RFC 7641, 1492 DOI 10.17487/RFC7641, September 2015, 1493 . 1495 8.2. Informative References 1497 [REST] Fielding, R., "Architectural Styles and the Design of 1498 Network-based Software Architectures", Ph.D. Dissertation, 1499 University of California, Irvine, 2000, 1500 . 1503 [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6 1504 over Low-Power Wireless Personal Area Networks (6LoWPANs): 1505 Overview, Assumptions, Problem Statement, and Goals", 1506 RFC 4919, DOI 10.17487/RFC4919, August 2007, 1507 . 1509 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 1510 "Transmission of IPv6 Packets over IEEE 802.15.4 1511 Networks", RFC 4944, DOI 10.17487/RFC4944, September 2007, 1512 . 1514 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1515 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1516 . 1518 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1519 Constrained-Node Networks", RFC 7228, 1520 DOI 10.17487/RFC7228, May 2014, 1521 . 1523 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1524 Protocol (HTTP/1.1): Message Syntax and Routing", 1525 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1526 . 1528 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1529 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 1530 RFC 7233, DOI 10.17487/RFC7233, June 2014, 1531 . 1533 Acknowledgements 1535 Much of the content of this draft is the result of discussions with 1536 the [RFC7252] authors, and via many CoRE WG discussions. 1538 Charles Palmer provided extensive editorial comments to a previous 1539 version of this draft, some of which the authors hope to have covered 1540 in this version. Esko Dijk reviewed a more recent version, leading 1541 to a number of further editorial improvements, a solution to the 4.13 1542 ambiguity problem, and the section about combining Block and 1543 multicast. Markus Becker proposed getting rid of an ill-conceived 1544 default value for the Block2 and Block1 options. Peter Bigot 1545 insisted on a more systematic coverage of the options and response 1546 code. Qin Wu provided a review for the IETF Operational directorate, 1547 and Goeran Selander commented on the security considerations. 1549 Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of 1550 the Size Option, which has informed this draft. Klaus Hartke wrote 1551 some of the text describing the interaction of Block2 with Observe. 1552 Matthias Kovatsch provided a number of significant simplifications of 1553 the protocol. 1555 The IESG reviewers provided very useful comments. Spencer Dawkins 1556 even suggested new text. Mirja Kuehlewind and he insisted on being 1557 more explicit about the layering of block-wise transfers on top of 1558 the base protocol. Ben Campbell helped untangling some MUST/SHOULD 1559 soup. Comments by Alexey Melnikov, as well as the gen-art review by 1560 Jouni Korhonen and the ops-dir review by Qin Wu, caused further 1561 improvements to the text. 1563 Authors' Addresses 1565 Carsten Bormann 1566 Universitaet Bremen TZI 1567 Postfach 330440 1568 Bremen D-28359 1569 Germany 1571 Phone: +49-421-218-63921 1572 Email: cabo@tzi.org 1574 Zach Shelby (editor) 1575 ARM 1576 150 Rose Orchard 1577 San Jose, CA 95134 1578 USA 1580 Phone: +1-408-203-9434 1581 Email: zach.shelby@arm.com