idnits 2.17.1 draft-ietf-core-block-08.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 (February 15, 2012) is 4447 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 891, but not defined == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-08 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-11 Summary: 1 error (**), 0 flaws (~~), 4 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: August 18, 2012 Sensinode 6 February 15, 2012 8 Blockwise transfers in CoAP 9 draft-ietf-core-block-08 11 Abstract 13 CoAP is a RESTful transfer protocol for constrained nodes and 14 networks. Basic CoAP messages work well for the small payloads we 15 expect from temperature sensors, light switches, and similar 16 building-automation devices. Occasionally, however, applications 17 will need to transfer larger payloads -- for instance, for firmware 18 updates. With HTTP, TCP does the grunt work of slicing large 19 payloads up into multiple packets and ensuring that they all arrive 20 and are handled in the right order. 22 CoAP is based on datagram transports such as UDP or DTLS, which 23 limits the maximum size of resource representations that can be 24 transferred without too much fragmentation. Although UDP supports 25 larger payloads through IP fragmentation, it is limited to 64 KiB 26 and, more importantly, doesn't really work well for constrained 27 applications and networks. 29 Instead of relying on IP fragmentation, this specification extends 30 basic CoAP with a pair of "Block" options, for transferring multiple 31 blocks of information from a resource representation in multiple 32 request-response pairs. In many important cases, the Block options 33 enable a server to be truly stateless: the server can handle each 34 block transfer separately, with no need for a connection setup or 35 other server-side memory of previous block transfers. 37 In summary, the Block options provide a minimal way to transfer 38 larger representations in a block-wise fashion. 40 Status of this Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at http://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on August 18, 2012. 57 Copyright Notice 59 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 75 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 6 76 2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 6 77 2.2. Using the Block Options . . . . . . . . . . . . . . . . . 10 78 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 79 4. The Size Option . . . . . . . . . . . . . . . . . . . . . . . 20 80 5. HTTP Mapping Considerations . . . . . . . . . . . . . . . . . 22 81 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 82 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 83 7.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 25 84 7.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 26 85 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 87 9.1. Normative References . . . . . . . . . . . . . . . . . . . 28 88 9.2. Informative References . . . . . . . . . . . . . . . . . . 28 89 Appendix A. Historical Note . . . . . . . . . . . . . . . . . . . 29 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 92 1. Introduction 94 The CoRE WG is tasked with standardizing an Application Protocol for 95 Constrained Networks/Nodes, CoAP. This protocol is intended to 96 provide RESTful [REST] services not unlike HTTP [RFC2616], while 97 reducing the complexity of implementation as well as the size of 98 packets exchanged in order to make these services useful in a highly 99 constrained network of themselves highly constrained nodes. 101 This objective requires restraint in a number of sometimes 102 conflicting ways: 104 o reducing implementation complexity in order to minimize code size, 106 o reducing message sizes in order to minimize the number of 107 fragments needed for each message (in turn to maximize the 108 probability of delivery of the message), the amount of 109 transmission power needed and the loading of the limited-bandwidth 110 channel, 112 o reducing requirements on the environment such as stable storage, 113 good sources of randomness or user interaction capabilities. 115 CoAP is based on datagram transports such as UDP, which limit the 116 maximum size of resource representations that can be transferred 117 without creating unreasonable levels of IP fragmentation. In 118 addition, not all resource representations will fit into a single 119 link layer packet of a constrained network, which may cause 120 adaptation layer fragmentation even if IP layer fragmentation is not 121 required. Using fragmentation (either at the adaptation layer or at 122 the IP layer) to enable the transport of larger representations is 123 possible up to the maximum size of the underlying datagram protocol 124 (such as UDP), but the fragmentation/reassembly process burdens the 125 lower layers with conversation state that is better managed in the 126 application layer. 128 This specification defines a pair of CoAP options to enable _block- 129 wise_ access to resource representations. The Block options provide 130 a minimal way to transfer larger resource representations in a block- 131 wise fashion. The overriding objective is to avoid creating 132 conversation state at the server for block-wise GET requests. (It is 133 impossible to fully avoid creating conversation state for POST/PUT, 134 if the creation/replacement of resources is to be atomic; where that 135 property is not needed, there is no need to create server 136 conversation state in this case, either.) 138 In summary, this specification adds a pair of Block options to CoAP 139 that can be used for block-wise transfers. Benefits of using these 140 options include: 142 o Transfers larger than can be accommodated in constrained-network 143 link-layer packets can be performed in smaller blocks. 145 o No hard-to-manage conversation state is created at the adaptation 146 layer or IP layer for fragmentation. 148 o The transfer of each block is acknowledged, enabling 149 retransmission if required. 151 o Both sides have a say in the block size that actually will be 152 used. 154 o The resulting exchanges are easy to understand using packet 155 analyzer tools and thus quite accessible to debugging. 157 o If needed, the Block options can also be used as is to provide 158 random access to power-of-two sized blocks within a resource 159 representation. 161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 162 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 163 document are to be interpreted as described in RFC 2119, BCP 14 164 [RFC2119] and indicate requirement levels for compliant CoAP 165 implementations. 167 In this document, the term "byte" is used in its now customary sense 168 as a synonym for "octet". 170 Where bit arithmetic is explained, this document uses the notation 171 familiar from the programming language C, except that the operator 172 "**" stands for exponentiation. 174 2. Block-wise transfers 176 As discussed in the introduction, there are good reasons to limit the 177 size of datagrams in constrained networks: 179 o by the maximum datagram size (~ 64 KiB for UDP) 181 o by the desire to avoid IP fragmentation (MTU of 1280 for IPv6) 183 o by the desire to avoid adaptation layer fragmentation (60-80 bytes 184 for 6LoWPAN [RFC4919]) 186 When a resource representation is larger than can be comfortably 187 transferred in the payload of a single CoAP datagram, a Block option 188 can be used to indicate a block-wise transfer. As payloads can be 189 sent both with requests and with responses, this specification 190 provides two separate options for each direction of payload transfer. 192 In the following, the term "payload" will be used for the actual 193 content of a single CoAP message, i.e. a single block being 194 transferred, while the term "body" will be used for the entire 195 resource representation that is being transferred in a block-wise 196 fashion. 198 In most cases, all blocks being transferred for a body will be of the 199 same size. The block size is not fixed by the protocol. To keep the 200 implementation as simple as possible, the Block options support only 201 a small range of power-of-two block sizes, from 2**4 (16) to 2**10 202 (1024) bytes. As bodies often will not evenly divide into the power- 203 of-two block size chosen, the size need not be reached in the final 204 block (but even for the final block, the chosen power-of-two size 205 will still be indicated in the block size field of the Block option). 207 2.1. The Block Options 209 +------+----------+--------+--------+--------+---------------+ 210 | Type | C/E | Name | Format | Length | Default | 211 +------+----------+--------+--------+--------+---------------+ 212 | 19 | Critical | Block1 | uint | 1-3 B | 0 (see below) | 213 | | | | | | | 214 | 17 | Critical | Block2 | uint | 1-3 B | 0 (see below) | 215 +------+----------+--------+--------+--------+---------------+ 217 Table 1: Block Option Numbers 219 Both Block1 and Block2 options can be present both in request and 220 response messages. In either case, the Block1 Option pertains to the 221 request payload, and the Block2 Option pertains to the response 222 payload. 224 Hence, for the methods defined in [I-D.ietf-core-coap], Block1 is 225 useful with the payload-bearing POST and PUT requests and their 226 responses. Block2 is useful with GET, POST, and PUT requests and 227 their payload-bearing responses (2.01, 2.02, 2.04, 2.05 -- see 228 section "Payload" of [I-D.ietf-core-coap]). 230 (As a memory aid: Block_1_ pertains to the payload of the _1st_ part 231 of the request-response exchange, i.e. the request, and Block_2_ 232 pertains to the payload of the _2nd_ part of the request-response 233 exchange, i.e. the response.) 235 Where Block1 is present in a request or Block2 in a response (i.e., 236 in that message to the payload of which it pertains) it indicates a 237 block-wise transfer and describes how this block-wise payload forms 238 part of the entire body being transferred ("descriptive usage"). 239 Where it is present in the opposite direction, it provides additional 240 control on how that payload will be formed or was processed ("control 241 usage"). 243 Implementation of either Block option is intended to be optional. 244 However, when it is present in a CoAP message, it MUST be processed 245 (or the message rejected); therefore it is identified as a critical 246 option. It MUST NOT occur more than once. 248 Three items of information may need to be transferred in a Block 249 option: 251 o The size of the block (SZX); 253 o whether more blocks are following (M); 255 o the relative number of the block (NUM) within a sequence of blocks 256 with the given size. 258 The value of the option is a 1-, 2- or 3-byte integer which encodes 259 these three fields, see Figure 1. 261 0 262 0 1 2 3 4 5 6 7 263 +-+-+-+-+-+-+-+-+ 264 | NUM |M| SZX | 265 +-+-+-+-+-+-+-+-+ 267 0 1 268 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 269 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 270 | NUM |M| SZX | 271 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 273 0 1 2 274 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 275 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 276 | NUM |M| SZX | 277 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 279 Figure 1: Block option value 281 The block size is encoded as a three-bit unsigned integer (0 for 2**4 282 to 6 for 2**10 bytes), which we call the "SZX" (size exponent); the 283 actual block size is then "2**(SZX + 4)". SZX is transferred in the 284 three least significant bits of the option value (i.e., "val & 7" 285 where "val" is the value of the option). 287 The fourth least significant bit, the M or "more" bit ("val & 8"), 288 indicates whether more blocks are following or the current block-wise 289 transfer is the last block being transferred. 291 The option value divided by sixteen (the NUM field) is the sequence 292 number of the block currently being transferred, starting from zero. 293 The current transfer is therefore about the "size" bytes starting at 294 byte "NUM << (SZX + 4)". (Note that, as an implementation 295 convenience, "(val & ~0xF) << (val & 7)", i.e. the option value with 296 the last 4 bits masked out, shifted to the left by the value of SZX, 297 gives the byte position of the block.) 299 The default value of both the Block1 and the Block2 Option is zero, 300 indicating that the current block is the first and only block of the 301 transfer (block number 0, M bit not set); however, there is no 302 explicit size implied by this default value. 304 More specifically, within the option value of a Block1 or Block2 305 Option, the meaning of the option fields is defined as follows: 307 NUM: Block Number. The block number is a variable-size (4, 12, or 308 20 bit) unsigned integer (uint, see Appendix A of 309 [I-D.ietf-core-coap]) indicating the block number being requested 310 or provided. Block number 0 indicates the first block of a body. 312 M: More Flag (not last block). For descriptive usage, this flag, if 313 unset, indicates that the payload in this message is the last 314 block in the body; when set it indicates that there are one or 315 more additional blocks available. When a Block2 Option is used in 316 a request to retrieve a specific block number ("control usage"), 317 the M bit MUST be sent as zero and ignored on reception. (In a 318 Block1 Option in a response, the M flag is used to indicate 319 atomicity, see below.) 321 SZX: Block Size. The block size is a three-bit unsigned integer 322 indicating the size of a block to the power of two. Thus block 323 size = 2**(SZX + 4). The allowed values of SZX are 0 to 6, i.e., 324 the minimum block size is 2**(0+4) = 16 and the maximum is 325 2**(6+4) = 1024. The value 7 for SZX (which would indicate a 326 block size of 2048) is reserved, i.e. MUST NOT be sent and MUST 327 lead to a 4.00 Bad Request response code upon reception in a 328 request. 330 The Block options are used in one of three roles: 332 o In descriptive usage, i.e. a Block2 Option in a response (e.g., a 333 2.05 response for GET), or a Block1 Option in a request (e.g., PUT 334 or POST): 336 * The NUM field in the option value describes what block number 337 is contained in the payload of this message. 339 * The M bit indicates whether further blocks are required to 340 complete the transfer of that body. 342 * The block size given by SZX MUST match the size of the payload 343 in bytes, if the M bit is set. (SZX does not govern the 344 payload size if M is unset). For Block2, if the request 345 suggested a larger value of SZX, the next request MUST move SZX 346 down to the size given here. (The effect is that, if the 347 server uses the smaller of its preferred block size and the one 348 requested, all blocks for a body use the same block size.) 350 o A Block2 Option in control usage in a request (e.g., GET): 352 * The NUM field in the Block2 Option gives the block number of 353 the payload that is being requested to be returned in the 354 response. 356 * In this case, the M bit has no function and MUST be set to 357 zero. 359 * The block size given (SZX) suggests a block size (in the case 360 of block number 0) or repeats the block size of previous blocks 361 received (in the case of block numbers other than 0). 363 o A Block1 Option in control usage in a response (e.g., a 2.xx 364 response for a PUT or POST request): 366 * The NUM field of the Block1 Option indicates what block number 367 is being acknowledged. 369 * If the M bit was set in the request, the server can choose 370 whether to act on each block separately, with no memory, or 371 whether to handle the request for the entire body atomically, 372 or any mix of the two. If the M bit is also set in the 373 response, it indicates that this response does not carry the 374 final response code to the request, i.e. the server collects 375 further blocks and plans to implement the request atomically 376 (e.g., acts only upon reception of the last block of payload). 377 Conversely, if the M bit is unset even though it was set in the 378 request, it indicates the block-wise request was enacted now 379 specifically for this block, and the response carries the final 380 response to this request (and to any previous ones with the M 381 bit set in the response's Block1 Option in this sequence of 382 block-wise transfers); the client is still expected to continue 383 sending further blocks, the request method for which may or may 384 not also be enacted per-block. 386 * Finally, the SZX block size given in a control Block1 Option 387 indicates the largest block size preferred by the server for 388 transfers toward the resource that is the same or smaller than 389 the one used in the initial exchange; the client SHOULD use 390 this block size or a smaller one in all further requests in the 391 transfer sequence, even if that means changing the block size 392 (and possibly scaling the block number accordingly) from now 393 on. 395 2.2. Using the Block Options 397 Using one or both Block options, a single REST operation can be split 398 into multiple CoAP message exchanges. As specified in 399 [I-D.ietf-core-coap], each of these message exchanges uses their own 400 CoAP Message ID. 402 When a request is answered with a response carrying a Block2 Option 403 with the M bit set, the requester may retrieve additional blocks of 404 the resource representation by sending further requests with the same 405 options and a Block2 Option giving the block number and block size 406 desired. In a request, the client MUST set the M bit of a Block2 407 Option to zero and the server MUST ignore it on reception. 409 To influence the block size used in a response, the requester also 410 uses the Block2 Option, giving the desired size, a block number of 411 zero and an M bit of zero. A server MUST use the block size 412 indicated or a smaller size. Any further block-wise requests for 413 blocks beyond the first one MUST indicate the same block size that 414 was used by the server in the response for the first request that 415 gave a desired size using a Block2 Option. 417 Once the Block2 Option is used by the requester, all requests in a 418 single block-wise transfer MUST ultimately use the same size, except 419 that there may not be enough content to fill the last block (the one 420 returned with the M bit not set). (Note that the client may start 421 using the Block2 Option in a second request after a first request 422 without a Block2 Option resulted in a Block option in the response.) 423 The server SHOULD use the block size indicated in the request option 424 or a smaller size, but the requester MUST take note of the actual 425 block size used in the response it receives to its initial request 426 and proceed to use it in subsequent requests. The server behavior 427 MUST ensure that this client behavior results in the same block size 428 for all responses in a sequence (except for the last one with the M 429 bit not set, and possibly the first one if the initial request did 430 not contain a Block2 Option). 432 Block-wise transfers can be used to GET resources the representations 433 of which are entirely static (not changing over time at all, such as 434 in a schema describing a device), or for dynamically changing 435 resources. In the latter case, the Block2 Option SHOULD be used in 436 conjunction with the ETag Option, to ensure that the blocks being 437 reassembled are from the same version of the representation: The 438 server SHOULD include an ETag option in each response. If an ETag 439 option is available, the client's reassembler, when reassembling the 440 representation from the blocks being exchanged, MUST compare ETag 441 Options. If the ETag Options do not match in a GET transfer, the 442 requester has the option of attempting to retrieve fresh values for 443 the blocks it retrieved first. To minimize the resulting 444 inefficiency, the server MAY cache the current value of a 445 representation for an ongoing sequence of requests. The client MAY 446 facilitate identifying the sequence by using the Token Option with a 447 non-default value. Note well that this specification makes no 448 requirement for the server to establish any state; however, servers 449 that offer quickly changing resources may thereby make it impossible 450 for a client to ever retrieve a consistent set of blocks. 452 In a request with a request payload (e.g., PUT or POST), the Block1 453 Option refers to the payload in the request (descriptive usage). 455 In response to a request with a payload (e.g., a PUT or POST 456 transfer), the block size given in the Block1 Option indicates the 457 block size preference of the server for this resource (control 458 usage). Obviously, at this point the first block has already been 459 transferred by the client without benefit of this knowledge. Still, 460 the client SHOULD heed the preference and, for all further blocks, 461 use the block size preferred by the server or a smaller one. Note 462 that any reduction in the block size may mean that the second request 463 starts with a block number larger than one, as the first request 464 already transferred multiple blocks as counted in the smaller size. 466 To counter the effects of adaptation layer fragmentation on packet 467 delivery probability, a client may want to give up retransmitting a 468 request with a relatively large payload even before MAX_RETRANSMIT 469 has been reached, and try restating the request as a block-wise 470 transfer with a smaller payload. Note that this new attempt is then 471 a new message-layer transaction and requires a new Message ID. 472 (Because of the uncertainty whether the request or the 473 acknowledgement was lost, this strategy is useful mostly for 474 idempotent requests.) 476 In a blockwise transfer of a request payload (e.g., a PUT or POST) 477 that is intended to be implemented in an atomic fashion at the 478 server, the actual creation/replacement takes place at the time the 479 final block, i.e. a block with the M bit unset in the Block1 Option, 480 is received. If not all previous blocks are available at the server 481 at this time, the transfer fails and error code 4.08 (Request Entity 482 Incomplete) MUST be returned. The error code 4.13 (Request Entity 483 Too Large) can be returned at any time by a server that does not 484 currently have the resources to store blocks for a block-wise request 485 payload transfer that it would intend to implement in an atomic 486 fashion. (Note that a 4.13 response to a request that does not 487 employ Block1 is a hint for the client to try sending Block1, and a 488 4.13 response with a smaller SZX in the Block1 than requested is a 489 hint to try a smaller SZX.) 491 If multiple concurrently proceeding block-wise request payload 492 transfer (e.g., PUT or POST) operations are possible, the requester 493 SHOULD use the Token Option to clearly separate the different 494 sequences. In this case, when reassembling the representation from 495 the blocks being exchanged to enable atomic processing, the 496 reassembler MUST compare any Token Options present (and, as usual, 497 taking an absent Token Option to default to the empty Token). If 498 atomic processing is not desired, there is no need to process the 499 Token Option (but it is still returned in the response as usual). 501 3. Examples 503 This section gives a number of short examples with message flows for 504 a block-wise GET, and for a PUT or POST. These examples demonstrate 505 the basic operation, the operation in the presence of 506 retransmissions, and examples for the operation of the block size 507 negotiation. 509 In all these examples, a Block option is shown in a decomposed way 510 separating the kind of Block option (1 or 2), block number (NUM), 511 more bit (M), and block size exponent (2**(SZX+4)) by slashes. E.g., 512 a Block2 Option value of 33 would be shown as 2/2/0/32), or a Block1 513 Option value of 59 would be shown as 1/3/1/128. 515 The first example (Figure 2) shows a GET request that is split into 516 three blocks. The server proposes a block size of 128, and the 517 client agrees. The first two ACKs contain 128 bytes of payload each, 518 and third ACK contains between 1 and 128 bytes. 520 CLIENT SERVER 521 | | 522 | CON [MID=1234], GET, /status ------> | 523 | | 524 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 525 | | 526 | CON [MID=1235], GET, /status, 2/1/0/128 ------> | 527 | | 528 | <------ ACK [MID=1235], 2.05 Content, 2/1/1/128 | 529 | | 530 | CON [MID=1236], GET, /status, 2/2/0/128 ------> | 531 | | 532 | <------ ACK [MID=1236], 2.05 Content, 2/2/0/128 | 534 Figure 2: Simple blockwise GET 536 In the second example (Figure 3), the client anticipates the 537 blockwise transfer (e.g., because of a size indication in the link- 538 format description [I-D.ietf-core-link-format]) and sends a size 539 proposal. All ACK messages except for the last carry 64 bytes of 540 payload; the last one carries between 1 and 64 bytes. 542 CLIENT SERVER 543 | | 544 | CON [MID=1234], GET, /status, 2/0/0/64 ------> | 545 | | 546 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/64 | 547 | | 548 | CON [MID=1235], GET, /status, 2/1/0/64 ------> | 549 | | 550 | <------ ACK [MID=1235], 2.05 Content, 2/1/1/64 | 551 : : 552 : ... : 553 : : 554 | CON [MID=1238], GET, /status, 2/4/0/64 ------> | 555 | | 556 | <------ ACK [MID=1238], 2.05 Content, 2/4/1/64 | 557 | | 558 | CON [MID=1239], GET, /status, 2/5/0/64 ------> | 559 | | 560 | <------ ACK [MID=1239], 2.05 Content, 2/5/0/64 | 562 Figure 3: Blockwise GET with early negotiation 564 In the third example (Figure 4), the client is surprised by the need 565 for a blockwise transfer, and unhappy with the size chosen 566 unilaterally by the server. As it did not send a size proposal 567 initially, the negotiation only influences the size from the second 568 message exchange onward. Since the client already obtained both the 569 first and second 64-byte block in the first 128-byte exchange, it 570 goes on requesting the third 64-byte block ("2/0/64"). None of this 571 is (or needs to be) understood by the server, which simply responds 572 to the requests as it best can. 574 CLIENT SERVER 575 | | 576 | CON [MID=1234], GET, /status ------> | 577 | | 578 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 579 | | 580 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 581 | | 582 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 583 | | 584 | CON [MID=1236], GET, /status, 2/3/0/64 ------> | 585 | | 586 | <------ ACK [MID=1236], 2.05 Content, 2/3/1/64 | 587 | | 588 | CON [MID=1237], GET, /status, 2/4/0/64 ------> | 589 | | 590 | <------ ACK [MID=1237], 2.05 Content, 2/4/1/64 | 591 | | 592 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 593 | | 594 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 596 Figure 4: Blockwise GET with late negotiation 598 In all these (and the following) cases, retransmissions are handled 599 by the CoAP message exchange layer, so they don't influence the block 600 operations (Figure 5, Figure 6). 602 CLIENT SERVER 603 | | 604 | CON [MID=1234], GET, /status ------> | 605 | | 606 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 607 | | 608 | CON [MID=1235], GE///////////////////////// | 609 | | 610 | (timeout) | 611 | | 612 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 613 | | 614 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 615 : : 616 : ... : 617 : : 618 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 619 | | 620 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 621 Figure 5: Blockwise GET with late negotiation and lost CON 623 CLIENT SERVER 624 | | 625 | CON [MID=1234], GET, /status ------> | 626 | | 627 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 628 | | 629 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 630 | | 631 | //////////////////////////////////tent, 2/2/1/64 | 632 | | 633 | (timeout) | 634 | | 635 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 636 | | 637 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 638 : : 639 : ... : 640 : : 641 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 642 | | 643 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 645 Figure 6: Blockwise GET with late negotiation and lost ACK 647 The following examples demonstrate a PUT exchange; a POST exchange 648 looks the same, with different requirements on atomicity/idempotence. 649 To ensure that the blocks relate to the same version of the resource 650 representation carried in the request, the client in Figure 7 sets 651 the Token to "v17" in all requests. Note that, similar to GET, the 652 responses to the requests that have a more bit in the request Block1 653 Option are provisional; only the final response tells the client that 654 the PUT succeeded. 656 CLIENT SERVER 657 | | 658 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 659 | | 660 | <------ ACK [MID=1234], 2.04 Changed, 1/0/1/128 | 661 | | 662 | CON [MID=1235], PUT, /options, v17, 1/1/1/128 ------> | 663 | | 664 | <------ ACK [MID=1235], 2.04 Changed, 1/1/1/128 | 665 | | 666 | CON [MID=1236], PUT, /options, v17, 1/2/0/128 ------> | 667 | | 668 | <------ ACK [MID=1236], 2.04 Changed, 1/2/0/128 | 670 Figure 7: Simple atomic blockwise PUT 672 A stateless server that simply builds/updates the resource in place 673 (statelessly) may indicate this by not setting the more bit in the 674 response (Figure 8); in this case, the response codes are valid 675 separately for each block being updated. This is of course only an 676 acceptable behavior of the server if the potential inconsistency 677 present during the run of the message exchange sequence does not lead 678 to problems, e.g. because the resource being created or changed is 679 not yet or not currently in use. 681 CLIENT SERVER 682 | | 683 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 684 | | 685 | <------ ACK [MID=1234], 2.04 Changed, 1/0/0/128 | 686 | | 687 | CON [MID=1235], PUT, /options, v17, 1/1/1/128 ------> | 688 | | 689 | <------ ACK [MID=1235], 2.04 Changed, 1/1/0/128 | 690 | | 691 | CON [MID=1236], PUT, /options, v17, 1/2/0/128 ------> | 692 | | 693 | <------ ACK [MID=1236], 2.04 Changed, 1/2/0/128 | 695 Figure 8: Simple stateless blockwise PUT 697 Finally, a server receiving a blockwise PUT or POST may want to 698 indicate a smaller block size preference (Figure 9). In this case, 699 the client SHOULD continue with a smaller block size; if it does, it 700 MUST adjust the block number to properly count in that smaller size. 702 CLIENT SERVER 703 | | 704 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 705 | | 706 | <------ ACK [MID=1234], 2.04 Changed, 1/0/1/32 | 707 | | 708 | CON [MID=1235], PUT, /options, v17, 1/4/1/32 ------> | 709 | | 710 | <------ ACK [MID=1235], 2.04 Changed, 1/4/1/32 | 711 | | 712 | CON [MID=1236], PUT, /options, v17, 1/5/1/32 ------> | 713 | | 714 | <------ ACK [MID=1235], 2.04 Changed, 1/5/1/32 | 715 | | 716 | CON [MID=1237], PUT, /options, v17, 1/6/0/32 ------> | 717 | | 718 | <------ ACK [MID=1236], 2.04 Changed, 1/6/0/32 | 720 Figure 9: Simple atomic blockwise PUT with negotiation 722 Block options may be used in both directions of a single exchange. 723 The following example demonstrates a blockwise POST request, 724 resulting in a separate blockwise response. The client in Figure 10 725 sets the Token to "37a" in all requests, which is echoed in all 726 response CONs in the separate response. 728 CLIENT SERVER 729 | | 730 | CON [MID=1234], POST, /soap, 37a, 1/0/1/128 ------> | 731 | | 732 | <------ ACK [MID=1234], 2.01 Created, 1/0/1/128 | 733 | | 734 | CON [MID=1235], POST, /soap, 37a, 1/1/1/128 ------> | 735 | | 736 | <------ ACK [MID=1235], 2.01 Created, 1/1/1/128 | 737 | | 738 | CON [MID=1236], POST, /soap, 37a, 1/2/0/128 ------> | 739 | | 740 | <------ ACK [MID=1236], 0, 1/2/0/128 | 741 | | 742 | <------ CON [MID=4712], 2.01 Created, 37a, 2/0/1/128 | 743 | | 744 | ACK [MID=4712], 0, 2/0/1/128 ------> | 745 | | 746 | <------ CON [MID=4713], 2.01 Created, 37a, 2/1/1/128 | 747 | | 748 | ACK [MID=4713], 0, 2/1/1/128 ------> | 749 | | 750 | <------ CON [MID=4714], 2.01 Created, 37a, 2/2/1/128 | 751 | | 752 | ACK [MID=4714], 0, 2/2/1/128 ------> | 753 | | 754 | <------ CON [MID=4715], 2.01 Created, 37a, 2/3/0/128 | 755 | | 756 | ACK [MID=4715], 0, 2/3/0/128 ------> | 758 Figure 10: Atomic blockwise POST with separate blockwise response 760 4. The Size Option 762 In many cases when transferring a large resource representation block 763 by block, it is advantageous to know the total size early in the 764 process. Some indication may be available from the maximum size 765 estimate attribute "sz" provided in a resource description 766 [I-D.ietf-core-link-format]. However, the size may vary dynamically, 767 so a more up-to-date indication may be useful. 769 The Size Option may be used for three purposes: 771 o in a request, to ask the server to provide a size estimate in the 772 response ("size request"). For this usage, the value MUST be set 773 to 0. 775 o in a response carrying a Block2 Option, to indicate the current 776 estimate the server has of the total size of the resource 777 representation. 779 o in a request carrying a Block1 Option, to indicate the current 780 estimate the client has of the total size of the resource 781 representation. 783 A size request can be easily distinguished from a size indication, as 784 the third case is not useful for a GET or DELETE, and an actual size 785 indication of 0 would either be overridden by the actual size of the 786 payload for a PUT or POST or would not be useful. 788 In the latter two cases ("size indication"), the value of the option 789 is the current estimate, measured in bytes. 791 The Size Option is "elective", i.e., a client MUST be prepared for 792 the server to ignore the size estimate request. The Size Option MUST 793 NOT occur more than once. 795 +------+----------+------+--------+--------+---------+ 796 | Type | C/E | Name | Format | Length | Default | 797 +------+----------+------+--------+--------+---------+ 798 | 18 | Elective | Size | uint | 0-4 B | (none) | 799 +------+----------+------+--------+--------+---------+ 801 Implementation Notes: 803 o As a quality of implementation consideration, blockwise transfers 804 for which the total size considerably exceeds the size of one 805 block are expected to include size indications, whenever those can 806 be provided without undue effort (preferably with the first block 807 exchanged). If the size estimate does not change, the indication 808 does not need to be repeated for every block. 810 o The end of a blockwise transfer is governed by the M bits in the 811 Block Options, _not_ by exhausting the size estimates exchanged. 813 o As usual for an option of type uint, the value 0 is best expressed 814 as an empty option (0 bytes). There is no default value. 816 5. HTTP Mapping Considerations 818 In this subsection, we give some brief examples for the influence the 819 Block options might have on intermediaries that map between CoAP and 820 HTTP. 822 For mapping CoAP requests to HTTP, the intermediary may want to map 823 the sequence of block-wise transfers into a single HTTP transfer. 824 E.g., for a GET request, the intermediary could perform the HTTP 825 request once the first block has been requested and could then 826 fulfill all further block requests out of its cache. A constrained 827 implementation may not be able to cache the entire object and may use 828 a combination of TCP flow control and (in particular if timeouts 829 occur) HTTP range requests to obtain the information necessary for 830 the next block transfer at the right time. 832 For PUT or POST requests, there is more variation in how HTTP servers 833 might implement ranges. Some WebDAV servers do, but in general the 834 CoAP-to-HTTP intermediary will have to try sending the payload of all 835 the blocks of a block-wise transfer within one HTTP request. If 836 enough buffering is available, this request can be started when the 837 last CoAP block is received. A constrained implementation may want 838 to relieve its buffering by already starting to send the HTTP request 839 at the time the first CoAP block is received; any HTTP 408 status 840 code that indicates that the HTTP server became impatient with the 841 resulting transfer can then be mapped into a CoAP 4.08 response code 842 (similarly, 413 maps to 4.13). 844 For mapping HTTP to CoAP, the intermediary may want to map a single 845 HTTP transfer into a sequence of block-wise transfers. If the HTTP 846 client is too slow delivering a request body on a PUT or POST, the 847 CoAP server might time out and return a 4.08 response code, which in 848 turn maps well to an HTTP 408 status code (again, 4.13 maps to 413). 849 HTTP range requests received on the HTTP side may be served out of a 850 cache and/or mapped to GET requests that request a sequence of blocks 851 overlapping the range. 853 (Note that, while the semantics of CoAP 4.08 and HTTP 408 differ, 854 this difference is largely due to the different way the two protocols 855 are mapped to transport. HTTP has an underlying TCP connection, 856 which supplies connection state, so a HTTP 408 status code can 857 immediately be used to indicate that a timeout occurred during 858 transmitting a request through that active TCP connection. The CoAP 859 4.08 response code indicates one or more missing blocks, which may be 860 due to timeouts or resource constraints; as there is no connection 861 state, there is no way to deliver such a response immediately; 862 instead, it is delivered on the next block transfer. Still, HTTP 408 863 is probably the best mapping back to HTTP, as the timeout is the most 864 likely cause for a CoAP 4.08. Note that there is no way to 865 distinguish a timeout from a missing block for a server without 866 creating additional state, the need for which we want to avoid.) 868 6. IANA Considerations 870 This draft adds the following option numbers to the CoAP Option 871 Numbers registry of [I-D.ietf-core-coap]: 873 +--------+--------+-----------+ 874 | Number | Name | Reference | 875 +--------+--------+-----------+ 876 | 17 | Block2 | [RFCXXXX] | 877 | | | | 878 | 18 | Size | [RFCXXXX] | 879 | | | | 880 | 19 | Block1 | [RFCXXXX] | 881 +--------+--------+-----------+ 883 Table 2: CoAP Option Numbers 885 This draft adds the following response code to the CoAP Response 886 Codes registry of [I-D.ietf-core-coap]: 888 +------+--------------------------------+-----------+ 889 | Code | Description | Reference | 890 +------+--------------------------------+-----------+ 891 | 136 | 4.08 Request Entity Incomplete | [RFCXXXX] | 892 +------+--------------------------------+-----------+ 894 Table 3: CoAP Response Codes 896 7. Security Considerations 898 Providing access to blocks within a resource may lead to surprising 899 vulnerabilities. Where requests are not implemented atomically, an 900 attacker may be able to exploit a race condition or confuse a server 901 by inducing it to use a partially updated resource representation. 902 Partial transfers may also make certain problematic data invisible to 903 intrusion detection systems; it is RECOMMENDED that an intrusion 904 detection system (IDS) that analyzes resource representations 905 transferred by CoAP implement the Block options to gain access to 906 entire resource representations. Still, approaches such as 907 transferring even-numbered blocks on one path and odd-numbered blocks 908 on another path, or even transferring blocks multiple times with 909 different content and obtaining a different interpretation of 910 temporal order at the IDS than at the server, may prevent an IDS from 911 seeing the whole picture. These kinds of attacks are well understood 912 from IP fragmentation and TCP segmentation; CoAP does not add 913 fundamentally new considerations. 915 Where access to a resource is only granted to clients making use of a 916 specific security association, all blocks of that resource MUST be 917 subject to the same security checks; it MUST NOT be possible for 918 unprotected exchanges to influence blocks of an otherwise protected 919 resource. As a related consideration, where object security is 920 employed, PUT/POST should be implemented in the atomic fashion, 921 unless the object security operation is performed on each access and 922 the creation of unusable resources can be tolerated. 924 Misleading size indications may be used by an attacker to induce 925 buffer overflows in poor implementations, for which the usual 926 considerations apply. 928 7.1. Mitigating Resource Exhaustion Attacks 930 Certain blockwise requests may induce the server to create state, 931 e.g. to create a snapshot for the blockwise GET of a fast-changing 932 resource to enable consistent access to the same version of a 933 resource for all blocks, or to create temporary resource 934 representations that are collected until pressed into service by a 935 final PUT or POST with the more bit unset. All mechanisms that 936 induce a server to create state that cannot simply be cleaned up 937 create opportunities for denial-of-service attacks. Servers SHOULD 938 avoid being subject to resource exhaustion based on state created by 939 untrusted sources. But even if this is done, the mitigation may 940 cause a denial-of-service to a legitimate request when it is drowned 941 out by other state-creating requests. Wherever possible, servers 942 should therefore minimize the opportunities to create state for 943 untrusted sources, e.g. by using stateless approaches. 945 Performing segmentation at the application layer is almost always 946 better in this respect than at the transport layer or lower (IP 947 fragmentation, adaptation layer fragmentation), e.g. because there is 948 application layer semantics that can be used for mitigation or 949 because lower layers provide security associations that can prevent 950 attacks. However, it is less common to apply timeouts and keepalive 951 mechanisms at the application layer than at lower layers. Servers 952 MAY want to clean up accumulated state by timing it out (cf. response 953 code 4.08), and clients SHOULD be prepared to run blockwise transfers 954 in an expedient way to minimize the likelihood of running into such a 955 timeout. 957 7.2. Mitigating Amplification Attacks 959 [I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points 960 for use in amplification attacks. 962 A CoAP server can reduce the amount of amplification it provides to 963 an attacker by offering large resource representations only in 964 relatively small blocks. With this, e.g., for a 1000 byte resource, 965 a 10-byte request might result in an 80-byte response (with a 64-byte 966 block) instead of a 1016-byte response, considerably reducing the 967 amplification provided. 969 8. Acknowledgements 971 Much of the content of this draft is the result of discussions with 972 the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions. 973 Tokens were suggested by Gilman Tolle and refined by Klaus Hartke. 975 Charles Palmer provided extensive editorial comments to a previous 976 version of this draft, some of which the authors hope to have covered 977 in this version. Esko Dijk reviewed a more recent version, leading 978 to a number of further editorial improvements. 980 Kepeng Li, Linyi Tian, and Barry Leiba wrote up an early version of 981 the Size Option, which has informed this draft. 983 9. References 985 9.1. Normative References 987 [I-D.ietf-core-coap] 988 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 989 "Constrained Application Protocol (CoAP)", 990 draft-ietf-core-coap-08 (work in progress), October 2011. 992 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 993 Requirement Levels", BCP 14, RFC 2119, March 1997. 995 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 996 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 997 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 999 9.2. Informative References 1001 [I-D.ietf-core-link-format] 1002 Shelby, Z., "CoRE Link Format", 1003 draft-ietf-core-link-format-11 (work in progress), 1004 January 2012. 1006 [REST] Fielding, R., "Architectural Styles and the Design of 1007 Network-based Software Architectures", 2000. 1009 [RFC4919] Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6 1010 over Low-Power Wireless Personal Area Networks (6LoWPANs): 1011 Overview, Assumptions, Problem Statement, and Goals", 1012 RFC 4919, August 2007. 1014 Appendix A. Historical Note 1016 (This appendix to be deleted by the RFC editor.) 1018 An earlier version of this draft used a single option: 1020 +------+----------+-------+--------+--------+---------------+ 1021 | Type | C/E | Name | Format | Length | Default | 1022 +------+----------+-------+--------+--------+---------------+ 1023 | 13 | Critical | Block | uint | 1-3 B | 0 (see below) | 1024 +------+----------+-------+--------+--------+---------------+ 1026 Note that this option number has since been reallocated in 1027 [I-D.ietf-core-coap]; no backwards compatibility is provided after 1028 July 1st, 2011. 1030 Authors' Addresses 1032 Carsten Bormann 1033 Universitaet Bremen TZI 1034 Postfach 330440 1035 Bremen D-28359 1036 Germany 1038 Phone: +49-421-218-63921 1039 Fax: +49-421-218-7000 1040 Email: cabo@tzi.org 1042 Zach Shelby (editor) 1043 Sensinode 1044 Kidekuja 2 1045 Vuokatti 88600 1046 Finland 1048 Phone: +358407796297 1049 Email: zach@sensinode.com