idnits 2.17.1 draft-ietf-core-block-03.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 (May 3, 2011) is 4739 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 663, but not defined == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-05 ** 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: November 5, 2011 Sensinode 6 May 3, 2011 8 Blockwise transfers in CoAP 9 draft-ietf-core-block-03 11 Abstract 13 CoAP is a RESTful transfer protocol for constrained nodes and 14 networks. CoAP is based on datagram transport, which limits the 15 maximum size of resource representations that can be transferred 16 without too much fragmentation. The Block options provide a minimal 17 way to transfer larger representations in a block-wise fashion. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on November 5, 2011. 36 Copyright Notice 38 Copyright (c) 2011 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 5 55 2.1. The Block Options . . . . . . . . . . . . . . . . . . . . 5 56 2.2. Using the Block Options . . . . . . . . . . . . . . . . . 7 57 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 58 3.1. HTTP Mapping Considerations . . . . . . . . . . . . . . . 15 59 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 60 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 61 5.1. Mitigating Resource Exhaustion Attacks . . . . . . . . . . 18 62 5.2. Mitigating Amplification Attacks . . . . . . . . . . . . . 19 63 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20 64 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 65 7.1. Normative References . . . . . . . . . . . . . . . . . . . 21 66 7.2. Informative References . . . . . . . . . . . . . . . . . . 21 67 Appendix A. Backwards Compatibility . . . . . . . . . . . . . . . 22 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 70 1. Introduction 72 The CoRE WG is tasked with standardizing an Application Protocol for 73 Constrained Networks/Nodes, CoAP. This protocol is intended to 74 provide RESTful [REST] services not unlike HTTP [RFC2616], while 75 reducing the complexity of implementation as well as the size of 76 packets exchanged in order to make these services useful in a highly 77 constrained network of themselves highly constrained nodes. 79 This objective requires restraint in a number of sometimes 80 conflicting ways: 82 o reducing implementation complexity in order to minimize code size, 84 o reducing message sizes in order to minimize the number of 85 fragments needed for each message (in turn to maximize the 86 probability of delivery of the message), the amount of 87 transmission power needed and the loading of the limited-bandwidth 88 channel, 90 o reducing requirements on the environment such as stable storage, 91 good sources of randomness or user interaction capabilities. 93 CoAP is based on datagram transports such as UDP, which limit the 94 maximum size of resource representations that can be transferred 95 without creating unreasonable levels of IP fragmentation. In 96 addition, not all resource representations will fit into a single 97 link layer packet of a constrained network, which may cause 98 adaptation layer fragmentation even if IP layer fragmentation is not 99 required. Using fragmentation (either at the adaptation layer or at 100 the IP layer) to enable the transport of larger representations is 101 possible up to the maximum size of the underlying datagram protocol 102 (such as UDP), but the fragmentation/reassembly process loads the 103 lower layers with conversation state that is better managed in the 104 application layer. 106 This specification defines a pair of CoAP options to enable _block- 107 wise_ access to resource representations. The Block options provide 108 a minimal way to transfer larger resource representations in a block- 109 wise fashion. The overriding objective is to avoid creating 110 conversation state at the server for block-wise GET requests. (It is 111 impossible to fully avoid creating conversation state for POST/PUT, 112 if the creation/replacement of resources is to be atomic; where that 113 property is not needed, there is no need to create server 114 conversation state in this case, either.) 116 In summary, this specification adds a pair of Block options to CoAP 117 that can be used for block-wise transfers. Benefits of using these 118 options include: 120 o Transfers larger than can be accommodated in constrained-network 121 link-layer packets can be performed in smaller blocks. 123 o No hard-to-manage conversation state is created at the adaptation 124 layer or IP layer for fragmentation. 126 o The transfer of each block is acknowledged, enabling 127 retransmission if required. 129 o Both sides have a say in the block size that actually will be 130 used. 132 o The resulting exchanges are easy to understand using packet 133 analyzer tools and thus quite accessible to debugging. 135 o If needed, the Block options can also be used as is to provide 136 random access to power-of-two sized blocks within a resource 137 representation. 139 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 140 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 141 document are to be interpreted as described in RFC 2119, BCP 14 142 [RFC2119] and indicate requirement levels for compliant CoAP 143 implementations. 145 In this document, the term "byte" is used in its now customary sense 146 as a synonym for "octet". 148 Where bit arithmetic is explained, this document uses the notation 149 familiar from the programming language C, except that the operator 150 "^" stands for exponentiation. 152 2. Block-wise transfers 154 2.1. The Block Options 156 +------+----------+--------+--------+--------+---------------+ 157 | Type | C/E | Name | Format | Length | Default | 158 +------+----------+--------+--------+--------+---------------+ 159 | 19 | Critical | Block1 | uint | 1-3 B | 0 (see below) | 160 | | | | | | | 161 | 17 | Critical | Block2 | uint | 1-3 B | 0 (see below) | 162 +------+----------+--------+--------+--------+---------------+ 164 Table 1: Block Option Numbers 166 The Block1 Option pertains to request payloads, and the Block2 Option 167 pertains to response payloads. (Note that either option can be used 168 in both requests and responses, see more below.) 170 Implementation of either Block option is intended to be optional. 171 However, when it is present in a CoAP message, it MUST be processed 172 (or the message rejected); therefore it is identified as a critical 173 option. 175 The size of the blocks should not be fixed by the protocol. On the 176 other hand, implementation should be as simple as possible. The 177 Block options therefore support a small range of power-of-two block 178 sizes, from 2^4 (16) to 2^10 (1024) bytes. One of these eight values 179 can be encoded in three bits (0 for 2^4 to 6 for 2^10 bytes), which 180 we call the "SZX" (size exponent); the actual block size is then "1 181 << (SZX + 4)". (The actual size of the final block in a block-wise 182 transfer may be less than or equal to the power-of-two block size.) 184 When a resource representation is larger than can be comfortably 185 transferred in a single UDP datagram, a Block option can be used to 186 indicate a block-wise transfer. The value of the option is a 1-, 2- 187 or 3-byte integer, the four least significant bits of which indicate 188 the size and whether the current block-wise transfer is the last 189 block being transferred (indicated by the M or "more" bit). The 190 option value divided by sixteen (the NUM field) is the number of the 191 block currently being transferred, starting from zero. The current 192 transfer is therefore about the "size" bytes starting at byte "block 193 number << (SZX + 4)" (although the power-of-two size need not be 194 reached in the final block). The default value of each of the Block 195 options is zero, indicating that the current block is the first 196 (block number 0) and only (M bit not set) block of the transfer; 197 however, there is no explicit size implied by this default value. 199 0 200 0 1 2 3 4 5 6 7 201 +-+-+-+-+-+-+-+-+ 202 | NUM |M| SZX | 203 +-+-+-+-+-+-+-+-+ 205 0 1 206 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 207 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 208 | NUM |M| SZX | 209 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 211 0 1 2 212 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 213 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 214 | NUM |M| SZX | 215 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 217 Figure 1: Block option value 219 (Note that, as an implementation convenience, the option value with 220 the last 4 bits masked out, shifted to the left by the value of SZX, 221 gives the byte position of the block.) 223 NUM: Block Number. The block number is a variable-size (4, 12, or 224 20 bit) unsigned integer indicating the block number being 225 requested or provided. Block number 0 indicates the first block 226 of a representation. 228 M: More Flag. This flag, if unset, indicates that this block is the 229 last in a representation. When set it indicates that there are 230 one or more additional blocks available. When a Block2 Option is 231 used in a request to retrieve a specific block number, the M bit 232 MUST be sent as zero and ignored on reception. (In a Block1 233 Option in a response, the M flag is used to indicate atomicity, 234 see below.) 236 SZX: Block Size. The block size is a three-bit unsigned integer 237 indicating the size of a block to the power of two. Thus block 238 size = 2^(SZX + 4). The allowed values of SZX are 0 to 6, i.e., 239 the minimum block size is 2^(0+4) = 16 and the maximum is 2^(6+4) 240 = 1024. The value 7 for SZX (which would indicate a block size of 241 2048) is reserved, i.e. MUST NOT be sent and MUST lead to a 4.00 242 Bad Request response code upon reception in a request. 244 The Block options are used in one of three roles: 246 o In a request (e.g., GET), the Block2 Option gives the block number 247 requested to be returned in the response and suggests a block size 248 (in the case of block number 0) or echoes the block size of 249 previous blocks received (in the case of block numbers other than 250 0). In thise case, the M bit has no function and MUST be set to 251 zero. 253 o A Block2 Option in a response (e.g., for GET), or a Block1 Option 254 in a request (e.g., PUT or POST), describes what block number is 255 contained in the payload of this message, and whether further 256 blocks are required to complete the transfer of that body (M bit). 257 If the M bit is set, the size of the payload body in bytes MUST 258 indeed be the power of two given by the block size. With certain 259 exceptions given below, all blocks for a REST transfer MUST use 260 the same block size, except for the last block (M bit not set). 262 o In a response, the Block1 Option indicates what block number is 263 being acknowledged (e.g., for a PUT or POST request). In this 264 case, if the M bit is set it indicates that this response does not 265 carry the final response to the request; this can occur when the M 266 bit was set in the request and the server implements the request 267 atomically (i.e., acts only upon reception of the last block of 268 payload). Conversely, if the M bit is unset, it indicates the 269 block-wise request was enacted now, and the response carries the 270 final response to this request (and to any previous ones with the 271 M bit set in the response's Block1 Option in this sequence of 272 block-wise transfers). Finally, the block size given in such a 273 Block1 Option indicates the largest block size preferred by the 274 server for transfers toward the resource that is the same or 275 smaller than the one used in the initial exchange; the client 276 SHOULD use this block size or a smaller one in all further 277 requests in the transfer sequence. 279 2.2. Using the Block Options 281 Using one or both Block options, a single REST operation can be split 282 into multiple CoAP message exchanges. Each of these message 283 exchanges uses their own CoAP Message ID. 285 When a request is answered with a response carrying a Block2 Option 286 with the M bit set, the requester may retrieve additional blocks of 287 the resource representation by sending further requests with the same 288 options and a Block2 Option giving the block number and block size 289 desired. In a request, the client MUST set the M bit of a Block2 290 Option to zero and the server MUST ignore it on reception. 292 To influence the block size used in a response, the requester also 293 uses the Block2 Option, giving the desired size, a block number of 294 zero and an M bit of zero. A server MUST use the block size 295 indicated or a smaller size. Any further block-wise requests for 296 blocks beyond the first one MUST indicate the same block size that 297 was used by the server in the response for the first request that 298 gave a desired size using a Block2 Option. 300 Once the Block2 Option is used by the requester, all requests in a 301 single block-wise transfer MUST ultimately use the same size, except 302 that there may not be enough content to fill the last block (the one 303 returned with the M bit not set). (Note that the client may start 304 using the Block2 Option in a second request after a first request 305 without a Block2 Option resulted in a Block option in the response.) 306 The server SHOULD use the block size indicated in the request option 307 or a smaller size, but the requester MUST take note of the actual 308 block size used in the response it receives to its initial request 309 and proceed to use it in subsequent requests. The server behavior 310 MUST ensure that this client behavior results in the same block size 311 for all responses in a sequence (except for the last one with the M 312 bit not set, and possibly the first one if the initial request did 313 not contain a Block2 Option). 315 Block-wise transfers can be used to GET resources the representations 316 of which are entirely static (not changing over time at all, such as 317 in a schema describing a device), or for dynamically changing 318 resources. In the latter case, the Block2 Option SHOULD be used in 319 conjunction with the ETag Option, to ensure that the blocks being 320 reassembled are from the same version of the representation: The 321 server SHOULD include an ETag option in each response. If an ETag 322 option is available, the client's reassembler, when reassembling the 323 representation from the blocks being exchanged, MUST compare ETag 324 Options. If the ETag Options do not match in a GET transfer, the 325 requester has the option of attempting to retrieve fresh values for 326 the blocks it retrieved first. To minimize the resulting 327 inefficiency, the server MAY cache the current value of a 328 representation for an ongoing sequence of requests, but there is no 329 requirement for the server to establish any state. The client MAY 330 facilitate identifying the sequence by using the Token Option with a 331 non-default value. 333 In a request with a request payload (e.g., PUT or POST), the Block1 334 Option refers to the body in the request. 336 In response to a request with a payload (e.g., a PUT or POST 337 transfer), the block size given in the Block1 Option indicates the 338 block size preference of the server for this resource. Obviously, at 339 this point the first block has already been transferred by the client 340 without benefit of this knowledge. Still, the client SHOULD heed the 341 preference and use the block size preferred by the server or a 342 smaller one. Note that any reduction in the block size may mean that 343 the second request starts with a block number larger than one, as the 344 first request already transferred multiple blocks as counted in the 345 smaller size. 347 In a blockwise transfer of a request payload (e.g., a PUT or POST) 348 that is intended to be implemented in an atomic fashion at the 349 server, the actual creation/replacement takes place at the time the 350 final block, i.e. a block with the M bit unset in the Block1 Option, 351 is received. If not all previous blocks are available at the server 352 at this time, the transfer fails and error code 4.08 (Request Entity 353 Incomplete) MUST be returned. The error code 4.13 (Request Entity 354 Too Large) can be returned at any time by a server that does not 355 currently have the resources to store blocks for a block-wise request 356 payload transfer that it would intend to implement in an atomic 357 fashion. 359 If multiple concurrently proceeding block-wise request payload 360 transfer (e.g., PUT or POST) operations are possible, the requester 361 SHOULD use the Token Option to clearly separate the different 362 sequences. In this case, when reassembling the representation from 363 the blocks being exchanged to enable atomic processing, the 364 reassembler MUST compare any Token Options present (and, as usual, 365 taking an absent Token Option to default to the empty Token). If 366 atomic processing is not desired, there is no need to process the 367 Token Option (but it is still returned in the response as usual). 369 3. Examples 371 This section gives a number of short examples with message flows for 372 a block-wise GET, and for a PUT or POST. These examples demonstrate 373 the basic operation, the operation in the presence of 374 retransmissions, and examples for the operation of the block size 375 negotiation. 377 In all these examples, a Block option is shown in a decomposed way 378 separating the kind of Block option (1 or 2), block number (NUM), 379 more bit (M), and block size exponent (2^(SZX+4)) by slashes. E.g., 380 a Block2 Option value of 33 would be shown as 2/2/0/32), or a Block1 381 Option value of 59 would be shown as 1/3/1/128. 383 The first example (Figure 2) shows a GET request that is split into 384 three blocks. The server proposes a block size of 128, and the 385 client agrees. The first two ACKs contain 128 bytes of payload each, 386 and third ACK contains between 1 and 128 bytes. 388 CLIENT SERVER 389 | | 390 | CON [MID=1234], GET, /status ------> | 391 | | 392 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 393 | | 394 | CON [MID=1235], GET, /status, 2/1/0/128 ------> | 395 | | 396 | <------ ACK [MID=1235], 2.05 Content, 2/1/1/128 | 397 | | 398 | CON [MID=1236], GET, /status, 2/2/0/128 ------> | 399 | | 400 | <------ ACK [MID=1236], 2.05 Content, 2/2/0/128 | 402 Figure 2: Simple blockwise GET 404 In the second example (Figure 3), the client anticipates the 405 blockwise transfer (e.g., because of a size indication in the link- 406 format description) and sends a size proposal. All ACK messages 407 except for the last carry 64 bytes of payload; the last one carries 408 between 1 and 64 bytes. 410 CLIENT SERVER 411 | | 412 | CON [MID=1234], GET, /status, 2/0/0/64 ------> | 413 | | 414 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/64 | 415 | | 416 | CON [MID=1235], GET, /status, 2/1/0/64 ------> | 417 | | 418 | <------ ACK [MID=1235], 2.05 Content, 2/1/1/64 | 419 : : 420 : ... : 421 : : 422 | CON [MID=1238], GET, /status, 2/4/0/64 ------> | 423 | | 424 | <------ ACK [MID=1238], 2.05 Content, 2/4/1/64 | 425 | | 426 | CON [MID=1239], GET, /status, 2/5/0/64 ------> | 427 | | 428 | <------ ACK [MID=1239], 2.05 Content, 2/5/0/64 | 430 Figure 3: Blockwise GET with early negotiation 432 In the third example (Figure 4), the client is surprised by the need 433 for a blockwise transfer, and unhappy with the size chosen 434 unilaterally by the server. As it did not send a size proposal 435 initially, the negotiation only influences the size from the second 436 message exchange onward. Since the client already obtained both the 437 first and second 64-byte block in the first 128-byte exchange, it 438 goes on requesting the third 64-byte block ("2/0/64"). None of this 439 is (or needs to be) understood by the server, which simply responds 440 to the requests as it best can. 442 CLIENT SERVER 443 | | 444 | CON [MID=1234], GET, /status ------> | 445 | | 446 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 447 | | 448 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 449 | | 450 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 451 | | 452 | CON [MID=1236], GET, /status, 2/3/0/64 ------> | 453 | | 454 | <------ ACK [MID=1236], 2.05 Content, 2/3/1/64 | 455 | | 456 | CON [MID=1237], GET, /status, 2/4/0/64 ------> | 457 | | 458 | <------ ACK [MID=1237], 2.05 Content, 2/4/1/64 | 459 | | 460 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 461 | | 462 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 464 Figure 4: Blockwise GET with late negotiation 466 In all these (and the following) cases, retransmissions are handled 467 by the CoAP message exchange layer, so they don't influence the block 468 operations (Figure 5, Figure 6). 470 CLIENT SERVER 471 | | 472 | CON [MID=1234], GET, /status ------> | 473 | | 474 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 475 | | 476 | CON [MID=1235], GE///////////////////////// | 477 | | 478 | (timeout) | 479 | | 480 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 481 | | 482 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 483 : : 484 : ... : 485 : : 486 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 487 | | 488 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 489 Figure 5: Blockwise GET with late negotiation and lost CON 491 CLIENT SERVER 492 | | 493 | CON [MID=1234], GET, /status ------> | 494 | | 495 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 496 | | 497 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 498 | | 499 | //////////////////////////////////tent, 2/2/1/64 | 500 | | 501 | (timeout) | 502 | | 503 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 504 | | 505 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 506 : : 507 : ... : 508 : : 509 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 510 | | 511 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 513 Figure 6: Blockwise GET with late negotiation and lost ACK 515 The following examples demonstrate a PUT exchange; a POST exchange 516 looks the same, with different requirements on atomicity/idempotence. 517 To ensure that the blocks relate to the same version of the resource 518 representation carried in the request, the client in Figure 7 sets 519 the Token to "v17" in all requests. Note that, as with the GET, the 520 responses to the requests that have a more bit in the request Block2 521 Option are provisional; only the final response tells the client that 522 the PUT succeeded. 524 CLIENT SERVER 525 | | 526 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 527 | | 528 | <------ ACK [MID=1234], 2.04 Changed, 1/0/1/128 | 529 | | 530 | CON [MID=1235], PUT, /options, v17, 1/1/1/128 ------> | 531 | | 532 | <------ ACK [MID=1235], 2.04 Changed, 1/1/1/128 | 533 | | 534 | CON [MID=1236], PUT, /options, v17, 1/2/0/128 ------> | 535 | | 536 | <------ ACK [MID=1236], 2.04 Changed, 1/2/0/128 | 538 Figure 7: Simple atomic blockwise PUT 540 A stateless server that simply builds/updates the resource in place 541 (statelessly) may indicate this by not setting the more bit in the 542 response (Figure 8); in this case, the response codes are valid 543 separately for each block being updated. This is of course only an 544 acceptable behavior of the server if the potential inconsistency 545 present during the run of the message exchange sequence does not lead 546 to problems, e.g. because the resource being created or changed is 547 not yet or not currently in use. 549 CLIENT SERVER 550 | | 551 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 552 | | 553 | <------ ACK [MID=1234], 2.04 Changed, 1/0/0/128 | 554 | | 555 | CON [MID=1235], PUT, /options, v17, 1/1/1/128 ------> | 556 | | 557 | <------ ACK [MID=1235], 2.04 Changed, 1/1/0/128 | 558 | | 559 | CON [MID=1236], PUT, /options, v17, 1/2/0/128 ------> | 560 | | 561 | <------ ACK [MID=1236], 2.04 Changed, 1/2/0/128 | 563 Figure 8: Simple stateless blockwise PUT 565 Finally, a server receiving a blockwise PUT or POST may want to 566 indicate a smaller block size preference (Figure 9). In this case, 567 the client SHOULD continue with a smaller block size; if it does, it 568 MUST adjust the block number to properly count in that smaller size. 570 CLIENT SERVER 571 | | 572 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 573 | | 574 | <------ ACK [MID=1234], 2.04 Changed, 1/0/1/32 | 575 | | 576 | CON [MID=1235], PUT, /options, v17, 1/4/1/32 ------> | 577 | | 578 | <------ ACK [MID=1235], 2.04 Changed, 1/4/1/32 | 579 | | 580 | CON [MID=1236], PUT, /options, v17, 1/5/1/32 ------> | 581 | | 582 | <------ ACK [MID=1235], 2.04 Changed, 1/5/1/32 | 583 | | 584 | CON [MID=1237], PUT, /options, v17, 1/6/0/32 ------> | 585 | | 586 | <------ ACK [MID=1236], 2.04 Changed, 1/6/0/32 | 588 Figure 9: Simple atomic blockwise PUT with negotiation 590 3.1. HTTP Mapping Considerations 592 In this subsection, we give some brief examples for the influence the 593 Block options might have on intermediaries that map between CoAP and 594 HTTP. 596 For mapping CoAP requests to HTTP, the intermediary may want to map 597 the block-wise transfer into a single HTTP transfer. E.g., for a GET 598 request, the intermediary could perform the HTTP request once the 599 first block has been requested and could then fulfill all further 600 block requests out of its cache. A constrained implementation may 601 not be able to cache the entire object and may use a combination of 602 TCP flow control and (in particular if timeouts occur) HTTP range 603 requests to obtain the information necessary for the next block 604 transfer at the right time. 606 For PUT or POST requests, there is more variation in how HTTP servers 607 might implement ranges. Some WebDAV servers do, but in general the 608 CoAP-to-HTTP intermediary will have to try sending the payload of all 609 the blocks of a block-wise transfer within one HTTP request. If 610 enough buffering is available, this request can be started when the 611 last CoAP block is received. A constrained implementation may want 612 to relieve its buffering by already starting to send the HTTP request 613 at the time the first CoAP block is received; any HTTP 408 status 614 code that indicates that the HTTP server became impatient with the 615 resulting transfer can then be mapped into a CoAP 4.08 response code 616 (similarly, 413 maps to 4.13). 618 For mapping HTTP to CoAP, the intermediary may want to map a single 619 HTTP transfer into a block-wise transfer. If the HTTP client is too 620 slow delivering a request body on a PUT or POST, the CoAP server 621 might time out and return a 4.08 response code, which in turn maps 622 well to an HTTP 408 status code (again, 4.13 maps to 413). HTTP 623 range requests received on the HTTP side may be served out of a cache 624 and/or mapped to GET requests that request a sequence of blocks 625 overlapping the range. 627 (Note that, while the semantics of CoAP 4.08 and HTTP 408 differ, 628 this difference is largely due to the different way the two protocols 629 are mapped to transport. HTTP has an underlying TCP connection, 630 which supplies connection state, so a HTTP 408 status code can 631 immediately be used to indicate that a timeout occurred during 632 transmitting a request through that active TCP connection. The CoAP 633 4.08 response code indicates one or more missing blocks, which may be 634 due to timeouts or resource constraints; as there is no connection 635 state, there is no way to deliver such a response immediately; 636 instead, it is delivered on the next block transfer. Still, HTTP 408 637 is probably the best mapping back to HTTP, as the timeout is the most 638 likely cause for a CoAP 4.08. Note that there is no way to 639 distinguish a timeout from a missing block for a server without 640 creating additional state, the need for which we want to avoid.) 642 4. IANA Considerations 644 This draft adds the following option number to the CoAP Option 645 Numbers registry of [I-D.ietf-core-coap]: 647 +--------+--------+-----------+ 648 | Number | Name | Reference | 649 +--------+--------+-----------+ 650 | 17 | Block2 | [RFCXXXX] | 651 | | | | 652 | 19 | Block1 | [RFCXXXX] | 653 +--------+--------+-----------+ 655 Table 2: CoAP Option Numbers 657 This draft adds the following response code to the CoAP Response 658 Codes registry of [I-D.ietf-core-coap]: 660 +------+--------------------------------+-----------+ 661 | Code | Description | Reference | 662 +------+--------------------------------+-----------+ 663 | 136 | 4.08 Request Entity Incomplete | [RFCXXXX] | 664 +------+--------------------------------+-----------+ 666 Table 3: CoAP Response Codes 668 5. Security Considerations 670 Providing access to blocks within a resource may lead to surprising 671 vulnerabilities. Where requests are not implemented atomically, an 672 attacker may be able to exploit a race condition or confuse a server 673 by inducing it to use a partially updated resource representation. 674 Partial transfers may also make certain problematic data invisible to 675 intrusion detection systems; it is RECOMMENDED that an intrusion 676 detection system (IDS) that analyzes resource representations 677 transferred by CoAP implement the Block options to gain access to 678 entire resource representations. Still, approaches such as 679 transferring even-numbered blocks on one path and odd-numbered blocks 680 on another path, or even transferring blocks multiple times with 681 different content and obtaining a different interpretation of 682 temporal order at the IDS than at the server, may prevent an IDS from 683 seeing the whole picture. These kinds of attacks are well understood 684 from IP fragmentation and TCP segmentation; CoAP does not add 685 fundamentally new considerations. 687 Where access to a resource is only granted to clients making use of a 688 specific security association, all blocks of that resource MUST be 689 subject to the same security checks; it MUST NOT be possible for 690 unprotected exchanges to influence blocks of an otherwise protected 691 resource. As a related consideration, where object security is 692 employed, PUT/POST should be implemented in the atomic fashion, 693 unless the object security operation is performed on each access and 694 the creation of unusable resources can be tolerated. 696 5.1. Mitigating Resource Exhaustion Attacks 698 Certain blockwise requests may induce the server to create state, 699 e.g. to create a snapshot for the blockwise GET of a fast-changing 700 resource to enable consistent access to the same version of a 701 resource for all blocks, or to create temporary resource 702 representations that are collected until pressed into service by a 703 final PUT or POST with the more bit unset. All mechanisms that 704 induce a server to create state that cannot simply be cleaned up 705 create opportunities for denial-of-service attacks. Servers SHOULD 706 avoid being subject to resource exhaustion based on state created by 707 untrusted sources. But even if this is done, the mitigation may 708 cause a denial-of-service to a legitimate request when it is drowned 709 out by other state-creating requests. Wherever possible, servers 710 should therefore minimize the opportunities to create state for 711 untrusted sources, e.g. by using stateless approaches. 713 Performing segmentation at the application layer is almost always 714 better in this respect than at the transport layer or lower (IP 715 fragmentation, adaptation layer fragmentation), e.g. because there is 716 application layer semantics that can be used for mitigation or 717 because lower layers provide security associations that can prevent 718 attacks. However, it is less common to apply timeouts and keepalive 719 mechanisms at the application layer than at lower layers. Servers 720 MAY want to clean up accreted state by timing it out (cf. response 721 code 4.08), and clients SHOULD be prepared to run blockwise transfers 722 in an expedient way to minimize the likelihood of running into such a 723 timeout. 725 5.2. Mitigating Amplification Attacks 727 [I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points 728 for use in amplification attacks. 730 A CoAP server can reduce the amount of amplification it provides to 731 an attacker by offering large resource representations only in 732 relatively small blocks. With this, e.g., for a 1000 byte resource, 733 a 10-byte request might result in an 80-byte response (with a 64-byte 734 block) instead of a 1016-byte response, considerably reducing the 735 amplification provided. 737 6. Acknowledgements 739 Much of the content of this draft is the result of discussions with 740 the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions. 741 Tokens were suggested by Gilman Tolle and refined by Klaus Hartke. 743 Charles Palmer provided extensive editorial comments to a previous 744 version of this draft, some of which the authors hope to have covered 745 in this version. 747 7. References 749 7.1. Normative References 751 [I-D.ietf-core-coap] 752 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 753 "Constrained Application Protocol (CoAP)", 754 draft-ietf-core-coap-05 (work in progress), March 2011. 756 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 757 Requirement Levels", BCP 14, RFC 2119, March 1997. 759 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 760 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 761 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 763 7.2. Informative References 765 [REST] Fielding, R., "Architectural Styles and the Design of 766 Network-based Software Architectures", 2000. 768 Appendix A. Backwards Compatibility 770 (This section to be removed by RFC editor or on July 1st, 2011.) 772 An earlier version of this draft used a single option: 774 +------+----------+-------+--------+--------+---------------+ 775 | Type | C/E | Name | Format | Length | Default | 776 +------+----------+-------+--------+--------+---------------+ 777 | 13 | Critical | Block | uint | 1-3 B | 0 (see below) | 778 +------+----------+-------+--------+--------+---------------+ 780 This option was interpreted as either Block1 or Block2 depending on 781 context: 783 o In the request for a GET, the original Block Option was 784 interpreted as a Block2 Option, i.e. to give the block number 785 requested and suggest a block size (block number 0) or echo the 786 block size of previous blocks received (block numbers other than 787 0). 789 o In the response for a GET, the original Block Option was 790 interpreted as a Block2 Option, i.e. to describes what block 791 number is contained in the response payload, and whether further 792 blocks are required to complete the transfer of that body (M bit). 794 o In the request for a PUT or POST, the original Block Option was 795 interpreted as a Block1 Option, i.e. to describes what block 796 number is contained in the request payload, and whether further 797 blocks are required to complete the transfer of that body (M bit). 799 o In the response for a PUT or POST, the original Block Option was 800 interpreted as a Block1 Option, i.e. to indicate what block number 801 is being acknowledged and to indicate whether the response is 802 final (M bit). 804 In summary, the semantics was dependent on the method code in a 805 request, and on the method code of the corresponding request in a 806 response. This lack of a direction indication also made it 807 impossible to transfer large PUT/POST responses in a block-wise 808 manner, because the original Block Option was already "spent" for 809 block-wise transfer of the request payload. 811 For interoperability with implementations of the previous draft- 812 block, implementations may honor original Block Options (option 813 number 13) until July 1st, 2011, at which time the option number 13 814 will be available for reallocation. 816 Authors' Addresses 818 Carsten Bormann 819 Universitaet Bremen TZI 820 Postfach 330440 821 Bremen D-28359 822 Germany 824 Phone: +49-421-218-63921 825 Fax: +49-421-218-7000 826 Email: cabo@tzi.org 828 Zach Shelby (editor) 829 Sensinode 830 Kidekuja 2 831 Vuokatti 88600 832 Finland 834 Phone: +358407796297 835 Email: zach@sensinode.com