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