idnits 2.17.1 draft-ietf-core-block-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 11, 2011) is 4673 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 666, but not defined == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-07 ** 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: January 12, 2012 Sensinode 6 July 11, 2011 8 Blockwise transfers in CoAP 9 draft-ietf-core-block-04 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 January 12, 2012. 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. Historical Note . . . . . . . . . . . . . . . . . . . 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 (the _first_ part of 167 the request-response exchange, hence Block1), and the Block2 Option 168 pertains to response payloads (the _second_ part of the request- 169 response exchange). (Note that either option can be used in both 170 requests and responses, see more below.) 172 Implementation of either Block option is intended to be optional. 173 However, when it is present in a CoAP message, it MUST be processed 174 (or the message rejected); therefore it is identified as a critical 175 option. 177 The size of the blocks is not fixed by the protocol. To keep the 178 implementation as simple as possible, the Block options support a 179 small range of power-of-two block sizes, from 2^4 (16) to 2^10 (1024) 180 bytes. One of these seven values can be encoded in three bits (0 for 181 2^4 to 6 for 2^10 bytes), which we call the "SZX" (size exponent); 182 the actual block size is then "1 << (SZX + 4)". (The actual size of 183 the final block in a block-wise transfer may be less than or equal to 184 the power-of-two block size.) 186 When a resource representation is larger than can be comfortably 187 transferred in a single UDP datagram, a Block option can be used to 188 indicate a block-wise transfer. The value of the option is a 1-, 2- 189 or 3-byte integer, the four least significant bits of which indicate 190 the size and whether the current block-wise transfer is the last 191 block being transferred (indicated by the M or "more" bit). The 192 option value divided by sixteen (the NUM field) is the number of the 193 block currently being transferred, starting from zero. The current 194 transfer is therefore about the "size" bytes starting at byte "block 195 number << (SZX + 4)" (although the power-of-two size need not be 196 reached in the final block). The default value of each of the Block 197 options is zero, indicating that the current block is the first 198 (block number 0) and only (M bit not set) block of the transfer; 199 however, there is no explicit size implied by this default value. 201 0 202 0 1 2 3 4 5 6 7 203 +-+-+-+-+-+-+-+-+ 204 | NUM |M| SZX | 205 +-+-+-+-+-+-+-+-+ 207 0 1 208 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 209 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 210 | NUM |M| SZX | 211 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 213 0 1 2 214 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 215 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 216 | NUM |M| SZX | 217 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 219 Figure 1: Block option value 221 (Note that, as an implementation convenience, the option value with 222 the last 4 bits masked out, shifted to the left by the value of SZX, 223 gives the byte position of the block.) 225 NUM: Block Number. The block number is a variable-size (4, 12, or 226 20 bit) unsigned integer (uint, see Appendix A of 227 [I-D.ietf-core-coap]) indicating the block number being requested 228 or provided. Block number 0 indicates the first block of a 229 representation. 231 M: More Flag (not last block). This flag, if unset, indicates that 232 this block is the last in a representation. When set it indicates 233 that there are one or more additional blocks available. When a 234 Block2 Option is used in a request to retrieve a specific block 235 number, the M bit MUST be sent as zero and ignored on reception. 236 (In a Block1 Option in a response, the M flag is used to indicate 237 atomicity, see below.) 239 SZX: Block Size. The block size is a three-bit unsigned integer 240 indicating the size of a block to the power of two. Thus block 241 size = 2^(SZX + 4). The allowed values of SZX are 0 to 6, i.e., 242 the minimum block size is 2^(0+4) = 16 and the maximum is 2^(6+4) 243 = 1024. The value 7 for SZX (which would indicate a block size of 244 2048) is reserved, i.e. MUST NOT be sent and MUST lead to a 4.00 245 Bad Request response code upon reception in a request. 247 The Block options are used in one of three roles: 249 o In a request (e.g., GET), the Block2 Option gives the block number 250 requested to be returned in the response and suggests a block size 251 (in the case of block number 0) or echoes the block size of 252 previous blocks received (in the case of block numbers other than 253 0). In this case, the M bit has no function and MUST be set to 254 zero. 256 o A Block2 Option in a response (e.g., for GET), or a Block1 Option 257 in a request (e.g., PUT or POST), describes what block number is 258 contained in the payload of this message, and whether further 259 blocks are required to complete the transfer of that body (M bit). 260 If the M bit is set, the size of the payload body in bytes MUST 261 indeed be the power of two given by the block size. With certain 262 exceptions given below, all blocks for a REST transfer MUST use 263 the same block size, except for the last block (M bit not set). 265 o In a response, the Block1 Option indicates what block number is 266 being acknowledged (e.g., for a PUT or POST request). In this 267 case, if the M bit is set it indicates that this response does not 268 carry the final response to the request; this can occur when the M 269 bit was set in the request and the server implements the request 270 atomically (i.e., acts only upon reception of the last block of 271 payload). Conversely, if the M bit is unset, it indicates the 272 block-wise request was enacted now, and the response carries the 273 final response to this request (and to any previous ones with the 274 M bit set in the response's Block1 Option in this sequence of 275 block-wise transfers). Finally, the block size given in such a 276 Block1 Option indicates the largest block size preferred by the 277 server for transfers toward the resource that is the same or 278 smaller than the one used in the initial exchange; the client 279 SHOULD use this block size or a smaller one in all further 280 requests in the transfer sequence. 282 2.2. Using the Block Options 284 Using one or both Block options, a single REST operation can be split 285 into multiple CoAP message exchanges. Each of these message 286 exchanges uses their own CoAP Message ID. 288 When a request is answered with a response carrying a Block2 Option 289 with the M bit set, the requester may retrieve additional blocks of 290 the resource representation by sending further requests with the same 291 options and a Block2 Option giving the block number and block size 292 desired. In a request, the client MUST set the M bit of a Block2 293 Option to zero and the server MUST ignore it on reception. 295 To influence the block size used in a response, the requester also 296 uses the Block2 Option, giving the desired size, a block number of 297 zero and an M bit of zero. A server MUST use the block size 298 indicated or a smaller size. Any further block-wise requests for 299 blocks beyond the first one MUST indicate the same block size that 300 was used by the server in the response for the first request that 301 gave a desired size using a Block2 Option. 303 Once the Block2 Option is used by the requester, all requests in a 304 single block-wise transfer MUST ultimately use the same size, except 305 that there may not be enough content to fill the last block (the one 306 returned with the M bit not set). (Note that the client may start 307 using the Block2 Option in a second request after a first request 308 without a Block2 Option resulted in a Block option in the response.) 309 The server SHOULD use the block size indicated in the request option 310 or a smaller size, but the requester MUST take note of the actual 311 block size used in the response it receives to its initial request 312 and proceed to use it in subsequent requests. The server behavior 313 MUST ensure that this client behavior results in the same block size 314 for all responses in a sequence (except for the last one with the M 315 bit not set, and possibly the first one if the initial request did 316 not contain a Block2 Option). 318 Block-wise transfers can be used to GET resources the representations 319 of which are entirely static (not changing over time at all, such as 320 in a schema describing a device), or for dynamically changing 321 resources. In the latter case, the Block2 Option SHOULD be used in 322 conjunction with the ETag Option, to ensure that the blocks being 323 reassembled are from the same version of the representation: The 324 server SHOULD include an ETag option in each response. If an ETag 325 option is available, the client's reassembler, when reassembling the 326 representation from the blocks being exchanged, MUST compare ETag 327 Options. If the ETag Options do not match in a GET transfer, the 328 requester has the option of attempting to retrieve fresh values for 329 the blocks it retrieved first. To minimize the resulting 330 inefficiency, the server MAY cache the current value of a 331 representation for an ongoing sequence of requests, but there is no 332 requirement for the server to establish any state. The client MAY 333 facilitate identifying the sequence by using the Token Option with a 334 non-default value. 336 In a request with a request payload (e.g., PUT or POST), the Block1 337 Option refers to the body in the request. 339 In response to a request with a payload (e.g., a PUT or POST 340 transfer), the block size given in the Block1 Option indicates the 341 block size preference of the server for this resource. Obviously, at 342 this point the first block has already been transferred by the client 343 without benefit of this knowledge. Still, the client SHOULD heed the 344 preference and use the block size preferred by the server or a 345 smaller one. Note that any reduction in the block size may mean that 346 the second request starts with a block number larger than one, as the 347 first request already transferred multiple blocks as counted in the 348 smaller size. 350 In a blockwise transfer of a request payload (e.g., a PUT or POST) 351 that is intended to be implemented in an atomic fashion at the 352 server, the actual creation/replacement takes place at the time the 353 final block, i.e. a block with the M bit unset in the Block1 Option, 354 is received. If not all previous blocks are available at the server 355 at this time, the transfer fails and error code 4.08 (Request Entity 356 Incomplete) MUST be returned. The error code 4.13 (Request Entity 357 Too Large) can be returned at any time by a server that does not 358 currently have the resources to store blocks for a block-wise request 359 payload transfer that it would intend to implement in an atomic 360 fashion. 362 If multiple concurrently proceeding block-wise request payload 363 transfer (e.g., PUT or POST) operations are possible, the requester 364 SHOULD use the Token Option to clearly separate the different 365 sequences. In this case, when reassembling the representation from 366 the blocks being exchanged to enable atomic processing, the 367 reassembler MUST compare any Token Options present (and, as usual, 368 taking an absent Token Option to default to the empty Token). If 369 atomic processing is not desired, there is no need to process the 370 Token Option (but it is still returned in the response as usual). 372 3. Examples 374 This section gives a number of short examples with message flows for 375 a block-wise GET, and for a PUT or POST. These examples demonstrate 376 the basic operation, the operation in the presence of 377 retransmissions, and examples for the operation of the block size 378 negotiation. 380 In all these examples, a Block option is shown in a decomposed way 381 separating the kind of Block option (1 or 2), block number (NUM), 382 more bit (M), and block size exponent (2^(SZX+4)) by slashes. E.g., 383 a Block2 Option value of 33 would be shown as 2/2/0/32), or a Block1 384 Option value of 59 would be shown as 1/3/1/128. 386 The first example (Figure 2) shows a GET request that is split into 387 three blocks. The server proposes a block size of 128, and the 388 client agrees. The first two ACKs contain 128 bytes of payload each, 389 and third ACK contains between 1 and 128 bytes. 391 CLIENT SERVER 392 | | 393 | CON [MID=1234], GET, /status ------> | 394 | | 395 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 396 | | 397 | CON [MID=1235], GET, /status, 2/1/0/128 ------> | 398 | | 399 | <------ ACK [MID=1235], 2.05 Content, 2/1/1/128 | 400 | | 401 | CON [MID=1236], GET, /status, 2/2/0/128 ------> | 402 | | 403 | <------ ACK [MID=1236], 2.05 Content, 2/2/0/128 | 405 Figure 2: Simple blockwise GET 407 In the second example (Figure 3), the client anticipates the 408 blockwise transfer (e.g., because of a size indication in the link- 409 format description) and sends a size proposal. All ACK messages 410 except for the last carry 64 bytes of payload; the last one carries 411 between 1 and 64 bytes. 413 CLIENT SERVER 414 | | 415 | CON [MID=1234], GET, /status, 2/0/0/64 ------> | 416 | | 417 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/64 | 418 | | 419 | CON [MID=1235], GET, /status, 2/1/0/64 ------> | 420 | | 421 | <------ ACK [MID=1235], 2.05 Content, 2/1/1/64 | 422 : : 423 : ... : 424 : : 425 | CON [MID=1238], GET, /status, 2/4/0/64 ------> | 426 | | 427 | <------ ACK [MID=1238], 2.05 Content, 2/4/1/64 | 428 | | 429 | CON [MID=1239], GET, /status, 2/5/0/64 ------> | 430 | | 431 | <------ ACK [MID=1239], 2.05 Content, 2/5/0/64 | 433 Figure 3: Blockwise GET with early negotiation 435 In the third example (Figure 4), the client is surprised by the need 436 for a blockwise transfer, and unhappy with the size chosen 437 unilaterally by the server. As it did not send a size proposal 438 initially, the negotiation only influences the size from the second 439 message exchange onward. Since the client already obtained both the 440 first and second 64-byte block in the first 128-byte exchange, it 441 goes on requesting the third 64-byte block ("2/0/64"). None of this 442 is (or needs to be) understood by the server, which simply responds 443 to the requests as it best can. 445 CLIENT SERVER 446 | | 447 | CON [MID=1234], GET, /status ------> | 448 | | 449 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 450 | | 451 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 452 | | 453 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 454 | | 455 | CON [MID=1236], GET, /status, 2/3/0/64 ------> | 456 | | 457 | <------ ACK [MID=1236], 2.05 Content, 2/3/1/64 | 458 | | 459 | CON [MID=1237], GET, /status, 2/4/0/64 ------> | 460 | | 461 | <------ ACK [MID=1237], 2.05 Content, 2/4/1/64 | 462 | | 463 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 464 | | 465 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 467 Figure 4: Blockwise GET with late negotiation 469 In all these (and the following) cases, retransmissions are handled 470 by the CoAP message exchange layer, so they don't influence the block 471 operations (Figure 5, Figure 6). 473 CLIENT SERVER 474 | | 475 | CON [MID=1234], GET, /status ------> | 476 | | 477 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 478 | | 479 | CON [MID=1235], GE///////////////////////// | 480 | | 481 | (timeout) | 482 | | 483 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 484 | | 485 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 486 : : 487 : ... : 488 : : 489 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 490 | | 491 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 492 Figure 5: Blockwise GET with late negotiation and lost CON 494 CLIENT SERVER 495 | | 496 | CON [MID=1234], GET, /status ------> | 497 | | 498 | <------ ACK [MID=1234], 2.05 Content, 2/0/1/128 | 499 | | 500 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 501 | | 502 | //////////////////////////////////tent, 2/2/1/64 | 503 | | 504 | (timeout) | 505 | | 506 | CON [MID=1235], GET, /status, 2/2/0/64 ------> | 507 | | 508 | <------ ACK [MID=1235], 2.05 Content, 2/2/1/64 | 509 : : 510 : ... : 511 : : 512 | CON [MID=1238], GET, /status, 2/5/0/64 ------> | 513 | | 514 | <------ ACK [MID=1238], 2.05 Content, 2/5/0/64 | 516 Figure 6: Blockwise GET with late negotiation and lost ACK 518 The following examples demonstrate a PUT exchange; a POST exchange 519 looks the same, with different requirements on atomicity/idempotence. 520 To ensure that the blocks relate to the same version of the resource 521 representation carried in the request, the client in Figure 7 sets 522 the Token to "v17" in all requests. Note that, as with the GET, the 523 responses to the requests that have a more bit in the request Block2 524 Option are provisional; only the final response tells the client that 525 the PUT succeeded. 527 CLIENT SERVER 528 | | 529 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 530 | | 531 | <------ ACK [MID=1234], 2.04 Changed, 1/0/1/128 | 532 | | 533 | CON [MID=1235], PUT, /options, v17, 1/1/1/128 ------> | 534 | | 535 | <------ ACK [MID=1235], 2.04 Changed, 1/1/1/128 | 536 | | 537 | CON [MID=1236], PUT, /options, v17, 1/2/0/128 ------> | 538 | | 539 | <------ ACK [MID=1236], 2.04 Changed, 1/2/0/128 | 541 Figure 7: Simple atomic blockwise PUT 543 A stateless server that simply builds/updates the resource in place 544 (statelessly) may indicate this by not setting the more bit in the 545 response (Figure 8); in this case, the response codes are valid 546 separately for each block being updated. This is of course only an 547 acceptable behavior of the server if the potential inconsistency 548 present during the run of the message exchange sequence does not lead 549 to problems, e.g. because the resource being created or changed is 550 not yet or not currently in use. 552 CLIENT SERVER 553 | | 554 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 555 | | 556 | <------ ACK [MID=1234], 2.04 Changed, 1/0/0/128 | 557 | | 558 | CON [MID=1235], PUT, /options, v17, 1/1/1/128 ------> | 559 | | 560 | <------ ACK [MID=1235], 2.04 Changed, 1/1/0/128 | 561 | | 562 | CON [MID=1236], PUT, /options, v17, 1/2/0/128 ------> | 563 | | 564 | <------ ACK [MID=1236], 2.04 Changed, 1/2/0/128 | 566 Figure 8: Simple stateless blockwise PUT 568 Finally, a server receiving a blockwise PUT or POST may want to 569 indicate a smaller block size preference (Figure 9). In this case, 570 the client SHOULD continue with a smaller block size; if it does, it 571 MUST adjust the block number to properly count in that smaller size. 573 CLIENT SERVER 574 | | 575 | CON [MID=1234], PUT, /options, v17, 1/0/1/128 ------> | 576 | | 577 | <------ ACK [MID=1234], 2.04 Changed, 1/0/1/32 | 578 | | 579 | CON [MID=1235], PUT, /options, v17, 1/4/1/32 ------> | 580 | | 581 | <------ ACK [MID=1235], 2.04 Changed, 1/4/1/32 | 582 | | 583 | CON [MID=1236], PUT, /options, v17, 1/5/1/32 ------> | 584 | | 585 | <------ ACK [MID=1235], 2.04 Changed, 1/5/1/32 | 586 | | 587 | CON [MID=1237], PUT, /options, v17, 1/6/0/32 ------> | 588 | | 589 | <------ ACK [MID=1236], 2.04 Changed, 1/6/0/32 | 591 Figure 9: Simple atomic blockwise PUT with negotiation 593 3.1. HTTP Mapping Considerations 595 In this subsection, we give some brief examples for the influence the 596 Block options might have on intermediaries that map between CoAP and 597 HTTP. 599 For mapping CoAP requests to HTTP, the intermediary may want to map 600 the block-wise transfer into a single HTTP transfer. E.g., for a GET 601 request, the intermediary could perform the HTTP request once the 602 first block has been requested and could then fulfill all further 603 block requests out of its cache. A constrained implementation may 604 not be able to cache the entire object and may use a combination of 605 TCP flow control and (in particular if timeouts occur) HTTP range 606 requests to obtain the information necessary for the next block 607 transfer at the right time. 609 For PUT or POST requests, there is more variation in how HTTP servers 610 might implement ranges. Some WebDAV servers do, but in general the 611 CoAP-to-HTTP intermediary will have to try sending the payload of all 612 the blocks of a block-wise transfer within one HTTP request. If 613 enough buffering is available, this request can be started when the 614 last CoAP block is received. A constrained implementation may want 615 to relieve its buffering by already starting to send the HTTP request 616 at the time the first CoAP block is received; any HTTP 408 status 617 code that indicates that the HTTP server became impatient with the 618 resulting transfer can then be mapped into a CoAP 4.08 response code 619 (similarly, 413 maps to 4.13). 621 For mapping HTTP to CoAP, the intermediary may want to map a single 622 HTTP transfer into a block-wise transfer. If the HTTP client is too 623 slow delivering a request body on a PUT or POST, the CoAP server 624 might time out and return a 4.08 response code, which in turn maps 625 well to an HTTP 408 status code (again, 4.13 maps to 413). HTTP 626 range requests received on the HTTP side may be served out of a cache 627 and/or mapped to GET requests that request a sequence of blocks 628 overlapping the range. 630 (Note that, while the semantics of CoAP 4.08 and HTTP 408 differ, 631 this difference is largely due to the different way the two protocols 632 are mapped to transport. HTTP has an underlying TCP connection, 633 which supplies connection state, so a HTTP 408 status code can 634 immediately be used to indicate that a timeout occurred during 635 transmitting a request through that active TCP connection. The CoAP 636 4.08 response code indicates one or more missing blocks, which may be 637 due to timeouts or resource constraints; as there is no connection 638 state, there is no way to deliver such a response immediately; 639 instead, it is delivered on the next block transfer. Still, HTTP 408 640 is probably the best mapping back to HTTP, as the timeout is the most 641 likely cause for a CoAP 4.08. Note that there is no way to 642 distinguish a timeout from a missing block for a server without 643 creating additional state, the need for which we want to avoid.) 645 4. IANA Considerations 647 This draft adds the following option number to the CoAP Option 648 Numbers registry of [I-D.ietf-core-coap]: 650 +--------+--------+-----------+ 651 | Number | Name | Reference | 652 +--------+--------+-----------+ 653 | 17 | Block2 | [RFCXXXX] | 654 | | | | 655 | 19 | Block1 | [RFCXXXX] | 656 +--------+--------+-----------+ 658 Table 2: CoAP Option Numbers 660 This draft adds the following response code to the CoAP Response 661 Codes registry of [I-D.ietf-core-coap]: 663 +------+--------------------------------+-----------+ 664 | Code | Description | Reference | 665 +------+--------------------------------+-----------+ 666 | 136 | 4.08 Request Entity Incomplete | [RFCXXXX] | 667 +------+--------------------------------+-----------+ 669 Table 3: CoAP Response Codes 671 5. Security Considerations 673 Providing access to blocks within a resource may lead to surprising 674 vulnerabilities. Where requests are not implemented atomically, an 675 attacker may be able to exploit a race condition or confuse a server 676 by inducing it to use a partially updated resource representation. 677 Partial transfers may also make certain problematic data invisible to 678 intrusion detection systems; it is RECOMMENDED that an intrusion 679 detection system (IDS) that analyzes resource representations 680 transferred by CoAP implement the Block options to gain access to 681 entire resource representations. Still, approaches such as 682 transferring even-numbered blocks on one path and odd-numbered blocks 683 on another path, or even transferring blocks multiple times with 684 different content and obtaining a different interpretation of 685 temporal order at the IDS than at the server, may prevent an IDS from 686 seeing the whole picture. These kinds of attacks are well understood 687 from IP fragmentation and TCP segmentation; CoAP does not add 688 fundamentally new considerations. 690 Where access to a resource is only granted to clients making use of a 691 specific security association, all blocks of that resource MUST be 692 subject to the same security checks; it MUST NOT be possible for 693 unprotected exchanges to influence blocks of an otherwise protected 694 resource. As a related consideration, where object security is 695 employed, PUT/POST should be implemented in the atomic fashion, 696 unless the object security operation is performed on each access and 697 the creation of unusable resources can be tolerated. 699 5.1. Mitigating Resource Exhaustion Attacks 701 Certain blockwise requests may induce the server to create state, 702 e.g. to create a snapshot for the blockwise GET of a fast-changing 703 resource to enable consistent access to the same version of a 704 resource for all blocks, or to create temporary resource 705 representations that are collected until pressed into service by a 706 final PUT or POST with the more bit unset. All mechanisms that 707 induce a server to create state that cannot simply be cleaned up 708 create opportunities for denial-of-service attacks. Servers SHOULD 709 avoid being subject to resource exhaustion based on state created by 710 untrusted sources. But even if this is done, the mitigation may 711 cause a denial-of-service to a legitimate request when it is drowned 712 out by other state-creating requests. Wherever possible, servers 713 should therefore minimize the opportunities to create state for 714 untrusted sources, e.g. by using stateless approaches. 716 Performing segmentation at the application layer is almost always 717 better in this respect than at the transport layer or lower (IP 718 fragmentation, adaptation layer fragmentation), e.g. because there is 719 application layer semantics that can be used for mitigation or 720 because lower layers provide security associations that can prevent 721 attacks. However, it is less common to apply timeouts and keepalive 722 mechanisms at the application layer than at lower layers. Servers 723 MAY want to clean up accumulated state by timing it out (cf. response 724 code 4.08), and clients SHOULD be prepared to run blockwise transfers 725 in an expedient way to minimize the likelihood of running into such a 726 timeout. 728 5.2. Mitigating Amplification Attacks 730 [I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points 731 for use in amplification attacks. 733 A CoAP server can reduce the amount of amplification it provides to 734 an attacker by offering large resource representations only in 735 relatively small blocks. With this, e.g., for a 1000 byte resource, 736 a 10-byte request might result in an 80-byte response (with a 64-byte 737 block) instead of a 1016-byte response, considerably reducing the 738 amplification provided. 740 6. Acknowledgements 742 Much of the content of this draft is the result of discussions with 743 the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions. 744 Tokens were suggested by Gilman Tolle and refined by Klaus Hartke. 746 Charles Palmer provided extensive editorial comments to a previous 747 version of this draft, some of which the authors hope to have covered 748 in this version. 750 7. References 752 7.1. Normative References 754 [I-D.ietf-core-coap] 755 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 756 "Constrained Application Protocol (CoAP)", 757 draft-ietf-core-coap-07 (work in progress), July 2011. 759 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 760 Requirement Levels", BCP 14, RFC 2119, March 1997. 762 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 763 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 764 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 766 7.2. Informative References 768 [REST] Fielding, R., "Architectural Styles and the Design of 769 Network-based Software Architectures", 2000. 771 Appendix A. Historical Note 773 An earlier version of this draft used a single option: 775 +------+----------+-------+--------+--------+---------------+ 776 | Type | C/E | Name | Format | Length | Default | 777 +------+----------+-------+--------+--------+---------------+ 778 | 13 | Critical | Block | uint | 1-3 B | 0 (see below) | 779 +------+----------+-------+--------+--------+---------------+ 781 Note that this option number has since been reallocated in 782 [I-D.ietf-core-coap]; no backwards compatibility is provided after 783 July 1st, 2011. 785 Authors' Addresses 787 Carsten Bormann 788 Universitaet Bremen TZI 789 Postfach 330440 790 Bremen D-28359 791 Germany 793 Phone: +49-421-218-63921 794 Fax: +49-421-218-7000 795 Email: cabo@tzi.org 797 Zach Shelby (editor) 798 Sensinode 799 Kidekuja 2 800 Vuokatti 88600 801 Finland 803 Phone: +358407796297 804 Email: zach@sensinode.com