idnits 2.17.1 draft-ietf-core-block-02.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 (March 14, 2011) is 4790 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 625, 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 Z. Shelby, Ed. 3 Internet-Draft Sensinode 4 Intended status: Standards Track C. Bormann 5 Expires: September 15, 2011 Universitaet Bremen TZI 6 March 14, 2011 8 Blockwise transfers in CoAP 9 draft-ietf-core-block-02 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 option provides 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 September 15, 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 Option . . . . . . . . . . . . . . . . . . . . . 5 56 2.2. Using the Block Option . . . . . . . . . . . . . . . . . . 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 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 69 1. Introduction 71 The CoRE WG is tasked with standardizing an Application Protocol for 72 Constrained Networks/Nodes, CoAP. This protocol is intended to 73 provide RESTful [REST] services not unlike HTTP [RFC2616], while 74 reducing the complexity of implementation as well as the size of 75 packets exchanged in order to make these services useful in a highly 76 constrained network of themselves highly constrained nodes. 78 This objective requires restraint in a number of sometimes 79 conflicting ways: 81 o reducing implementation complexity in order to minimize code size, 83 o reducing message sizes in order to minimize the number of 84 fragments needed for each message (in turn to maximize the 85 probability of delivery of the message), the amount of 86 transmission power needed and the loading of the limited-bandwidth 87 channel, 89 o reducing requirements on the environment such as stable storage, 90 good sources of randomness or user interaction capabilities. 92 CoAP is based on datagram transports such as UDP, which limit the 93 maximum size of resource representations that can be transferred 94 without creating unreasonable levels of IP fragmentation. In 95 addition, not all resource representations will fit into a single 96 link layer packet of a constrained network, which may cause 97 adaptation layer fragmentation even if IP layer fragmentation is not 98 required. Using fragmentation (either at the adaptation layer or at 99 the IP layer) to enable the transport of larger representations is 100 possible up to the maximum size of the underlying datagram protocol 101 (such as UDP), but the fragmentation/reassembly process loads the 102 lower layers with conversation state that is better managed in the 103 application layer. 105 This specification defines a CoAP option to enable _block-wise_ 106 access to resource representations. The Block option provides a 107 minimal way to transfer larger resource representations in a block- 108 wise fashion. The overriding objective is to avoid creating 109 conversation state at the server for block-wise GET requests. (It is 110 impossible to fully avoid creating conversation state for POST/PUT, 111 if the creation/replacement of resources is to be atomic; where that 112 property is not needed, there is no need to create server 113 conversation state in this case, either.) 115 In summary, this specification adds a Block option to CoAP that can 116 be used for block-wise transfers. Benefits of using this option 117 include: 119 o Transfers larger than can be accommodated in constrained-network 120 link-layer packets can be performed in smaller blocks. 122 o No hard-to-manage conversation state is created at the adaptation 123 layer or IP layer for fragmentation. 125 o The transfer of each block is acknowledged, enabling 126 retransmission if required. 128 o Both sides have a say in the block size that actually will be 129 used. 131 o The resulting exchanges are easy to understand using packet 132 analyzer tools and thus quite accessible to debugging. 134 o If needed, the Block option can also be used as is to provide 135 random access to power-of-two sized blocks within a resource 136 representation. 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 140 document are to be interpreted as described in RFC 2119, BCP 14 141 [RFC2119] and indicate requirement levels for compliant CoAP 142 implementations. 144 In this document, the term "byte" is used in its now customary sense 145 as a synonym for "octet". 147 Where bit arithmetic is explained, this document uses the notation 148 familiar from the programming language C, except that the operator 149 "^" stands for exponentiation. 151 2. Block-wise transfers 153 2.1. The Block Option 155 +------+-----+-------+-----------+--------+---------------+ 156 | Type | C/E | Name | Data type | Length | Default | 157 +------+-----+-------+-----------+--------+---------------+ 158 | 13 | C | Block | uint | 1-3 B | 0 (see below) | 159 +------+-----+-------+-----------+--------+---------------+ 161 Implementation of the Block option is intended to be optional. 162 However, when it is present in a CoAP message, it MUST be processed 163 (or the message rejected); therefore it is identified as a critical 164 option. 166 The size of the blocks should not be fixed by the protocol. On the 167 other hand, implementation should be as simple as possible. The 168 Block option therefore supports a small range of power-of-two block 169 sizes, from 2^4 (16) to 2^11 (2048) bytes. One of these eight values 170 can be encoded in three bits (0 for 2^4 to 7 for 2^11 bytes), which 171 we call the "SZX" (size exponent); the actual block size is then "1 172 << (SZX + 4)". 174 When a representation is larger than can be comfortably transferred 175 in a single UDP datagram, the Block option can be used to indicate a 176 block-wise transfer. Block is a 1-, 2- or 3-byte integer, the four 177 least significant bits of which indicate the size and whether the 178 current block-wise transfer is the last block being transferred (M or 179 "more" bit). The option value divided by sixteen is the number of 180 the block currently being transferred, starting from zero, i.e., the 181 current transfer is about the "size" bytes starting at byte "block 182 number << (SZX + 4)". The default value of the Block Option is zero, 183 indicating that the current block is the first (block number 0) and 184 only (M bit not set) block of the transfer; however, there is no 185 explicit size implied by this default value. 187 0 188 0 1 2 3 4 5 6 7 189 +-+-+-+-+-+-+-+-+ 190 | NUM |M| SZX | 191 +-+-+-+-+-+-+-+-+ 193 0 1 194 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 196 | NUM |M| SZX | 197 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 199 0 1 2 200 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 201 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 202 | NUM |M| SZX | 203 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 205 Figure 1: Block option 207 (Note that, as an implementation convenience, the option value with 208 the last 4 bits masked out, shifted to the left by the value of SZX, 209 gives the byte position of the block.) 211 NUM: Block Number. The block number is a variable-size (4, 12, or 212 20 bit) unsigned integer indicating the block number being 213 requested or provided. Block number 0 indicates the first block 214 of a representation. 216 M: More Flag. This flag, if unset, indicates that this block is the 217 last in a representation. When set it indicates that there are 218 one or more additional blocks available. When the block option is 219 used in a request to retrieve a specific block number, the M bit 220 MUST be sent as zero and ignored on reception. 222 SZX: Block Size. The block size is a three-bit unsigned integer 223 indicating the size of a block to the power of two. Thus block 224 size = 2^(SZX + 4). As there are three bits available for SZX, 225 the minimum block size is 2^(0+4) = 16 and the maximum is 2^(7+4) 226 = 2048. 228 The Block option is used in one of three roles: 230 o In the request for a GET, the Block option gives the block number 231 requested and suggests a block size (block number 0) or echoes the 232 block size of previous blocks received (block numbers other than 233 0). 235 o In the response for a GET or in the request for a PUT or POST, the 236 Block option describes what block number is contained in the 237 payload, and whether further blocks are required to complete the 238 transfer of that body (M bit). If the M bit is set, the size of 239 the payload body in bytes MUST indeed be the power of two given by 240 the block size. With certain exceptions given below, all blocks 241 for a REST transfer MUST use the same block size, except for the 242 last block (M bit not set). 244 o In the response for a PUT or POST, the Block option indicates what 245 block number is being acknowledged. In this case, if the M bit is 246 set it indicates that this response does not carry the final 247 response to the request; this can occur when the M bit was set in 248 the request and the server implements PUT/POST atomically (i.e., 249 acts only upon reception of the last block). Conversely, if the M 250 bit is unset, it indicates the block-wise request was enacted now, 251 and the response carries the final response to this request (and 252 to any previous ones with the M bit set in this sequence of block- 253 wise transfers). Finally, the block size given in such a Block 254 option indicates the largest block size preferred by the server 255 for transfers toward the resource that is the same or smaller than 256 the one used in the initial exchange; the client SHOULD use this 257 block size or a smaller one in all further PUT/POST requests in 258 the transfer sequence. 260 2.2. Using the Block Option 262 Using the Block option, a single REST operation can be split into 263 multiple CoAP message exchanges. Each of these message exchanges 264 uses their own CoAP Message ID. 266 When a GET is answered with a response carrying a Block option with 267 the M bit set, the requester may retrieve additional blocks of the 268 resource representation by sending requests with a Block option 269 giving the block number desired. In such a Block option, the M bit 270 MUST be sent as zero and ignored on reception. 272 To influence the block size used in response to a GET request, the 273 requester uses the Block option, giving the desired size, a block 274 number of zero and an M bit of zero. A server SHOULD use the block 275 size indicated or a smaller size. Any further block-wise requests 276 for blocks beyond the first one MUST indicate the same block size 277 that was used by the server in the response for the first request 278 that gave a desired size using a Block option. 280 Once the Block option is used by the requester, all GET requests in a 281 single transfer MUST ultimately use the same size, except that there 282 may not be enough content to fill the last block (the one returned 283 with the M bit not set). (Note that the client may start using the 284 Block option in a second request after a first request without a 285 Block option resulted in a Block option in the response.) The server 286 SHOULD use the block size indicated in the request option or a 287 smaller size, but the requester MUST take note of the actual block 288 size used in the response it receives to its initial GET and proceed 289 to use it in subsequent GETs; the server behavior MUST ensure that 290 this client behavior results in the same block size for all responses 291 in a sequence (except for the last one with the M bit not set, and 292 possibly the first one if the initial request did not contain a Block 293 option). 295 Block-wise transfers can be used to GET resources the representations 296 of which are entirely static (not changing over time at all, such as 297 in a schema describing a device), or for dynamically changing 298 resources. In the latter case, the Block option SHOULD be used in 299 conjunction with the ETag option, to ensure that the blocks being 300 reassembled are from the same version of the representation. When 301 reassembling the representation from the blocks being exchanged, the 302 reassembler MUST compare ETag options. If the ETag options do not 303 match in a GET transfer, the requester has the option of attempting 304 to retrieve fresh values for the blocks it retrieved first. To 305 minimize the resulting inefficiency, the server MAY cache the current 306 value of a representation for an ongoing sequence of requests, but 307 there is no requirement for the server to establish any state. The 308 client MAY facilitate identifying the sequence by using the Token 309 option with a non-default value. 311 In a PUT or POST transfer, the Block option refers to the body in the 312 request, i.e., there is no way to perform a block-wise retrieval of 313 the body of the response. Servers that do need to supply large 314 bodies in response to PUT/POST SHOULD therefore be employing 315 mechanisms such as providing a location for a resource that can be 316 used in a GET to obtain that information. 318 In a PUT or POST transfer response, the block size given in the Block 319 option indicates the block size preference of the server for this 320 resource. Obviously, at this point the first block has already been 321 transferred without benefit of this knowledge. Still, the client 322 SHOULD heed the preference and use the block size preferred by the 323 server or a smaller one. Note that any reduction in the block size 324 may mean that the second request starts with a block number larger 325 than one, as the first request already transferred multiple blocks as 326 counted in the smaller size. 328 In a PUT or POST transfer that is intended to be implemented in an 329 atomic fashion at the server, the actual creation/replacement takes 330 place at the time the final block, i.e. a block with the M bit unset, 331 is received. If not all previous blocks are available at the server 332 at this time, the transfer fails and error code 4.08 (Request Entity 333 Incomplete) MUST be returned. The error code 4.13 (Request Entity 334 Too Large) can be returned at any time by a server that does not 335 currently have the resources to store blocks for a block-wise PUT or 336 POST transfer that it would intend to implement in an atomic fashion. 338 If multiple concurrently proceeding block-wise PUT or POST operations 339 are possible, the requester SHOULD use the Token option to clearly 340 separate the different sequences. In this case, when reassembling 341 the representation from the blocks being exchanged to enable atomic 342 processing, the reassembler MUST compare any Token options present 343 (and, as usual, taking an absent Token option to default to the empty 344 Token). If atomic processing is not desired, there is no need to 345 process the Token option (but it is still returned in the response as 346 usual). 348 3. Examples 350 This section gives a number of short examples with message flows for 351 a block-wise GET, and for a PUT or POST. These examples demonstrate 352 the basic operation, the operation in the presence of 353 retransmissions, and examples for the operation of the block size 354 negotiation. 356 In all these examples, a block option is shown in a decomposed way 357 separating the block number (NUM), more bit (M), and block size 358 exponent (2^(SZX+4)) by slashes. E.g., a block option value of 33 359 would be shown as 2/0/32, or a block option value of 59 would be 360 shown as 3/1/128. 362 The first example (Figure 2) shows a GET request that is split into 363 three blocks. The server proposes a block size of 128, and the 364 client agrees. The first two ACKs contain 128 bytes of payload each, 365 and third ACK contains between 1 and 128 bytes. 367 CLIENT SERVER 368 | | 369 | CON [MID=1234], GET, /status ------> | 370 | | 371 | <------ ACK [MID=1234], 2.00 OK, 0/1/128 | 372 | | 373 | CON [MID=1235], GET, /status, 1/0/128 ------> | 374 | | 375 | <------ ACK [MID=1235], 2.00 OK, 1/1/128 | 376 | | 377 | CON [MID=1236], GET, /status, 2/0/128 ------> | 378 | | 379 | <------ ACK [MID=1236], 2.00 OK, 2/0/128 | 381 Figure 2: Simple blockwise GET 383 In the second example (Figure 3), the client anticipates the 384 blockwise transfer (e.g., because of a size indication in the link- 385 format description) and sends a size proposal. All ACK messages 386 except for the last carry 64 bytes of payload; the last one carries 387 between 1 and 64 bytes. 389 CLIENT SERVER 390 | | 391 | CON [MID=1234], GET, /status, 0/0/64 ------> | 392 | | 393 | <------ ACK [MID=1234], 2.00 OK, 0/1/64 | 394 | | 395 | CON [MID=1235], GET, /status, 1/0/64 ------> | 396 | | 397 | <------ ACK [MID=1235], 2.00 OK, 1/1/64 | 398 : : 399 : ... : 400 : : 401 | CON [MID=1238], GET, /status, 4/0/64 ------> | 402 | | 403 | <------ ACK [MID=1238], 2.00 OK, 4/1/64 | 404 | | 405 | CON [MID=1239], GET, /status, 5/0/64 ------> | 406 | | 407 | <------ ACK [MID=1239], 2.00 OK, 5/0/64 | 409 Figure 3: Blockwise GET with early negotiation 411 In the third example (Figure 4), the client is surprised by the need 412 for a blockwise transfer, and unhappy with the size chosen 413 unilaterally by the server. As it did not send a size proposal 414 initially, the negotiation only influences the size from the second 415 message exchange. Since the client already obtained both the first 416 and second 64-byte block in the first 128-byte exchange, it goes on 417 requesting the third 64-byte block ("2/0/64"). None of this is (or 418 needs to be) understood by the server, which simply responds to the 419 requests as it best can. 421 CLIENT SERVER 422 | | 423 | CON [MID=1234], GET, /status ------> | 424 | | 425 | <------ ACK [MID=1234], 2.00 OK, 0/1/128 | 426 | | 427 | CON [MID=1235], GET, /status, 2/0/64 ------> | 428 | | 429 | <------ ACK [MID=1235], 2.00 OK, 2/1/64 | 430 | | 431 | CON [MID=1236], GET, /status, 3/0/64 ------> | 432 | | 433 | <------ ACK [MID=1236], 2.00 OK, 3/1/64 | 434 | | 435 | CON [MID=1237], GET, /status, 4/0/64 ------> | 436 | | 437 | <------ ACK [MID=1237], 2.00 OK, 4/1/64 | 438 | | 439 | CON [MID=1238], GET, /status, 5/0/64 ------> | 440 | | 441 | <------ ACK [MID=1238], 2.00 OK, 5/0/64 | 443 Figure 4: Blockwise GET with late negotiation 445 In all these (and the following) cases, retransmissions are handled 446 by the CoAP message exchange layer, so they don't influence the block 447 operations (Figure 5, Figure 6). 449 CLIENT SERVER 450 | | 451 | CON [MID=1234], GET, /status ------> | 452 | | 453 | <------ ACK [MID=1234], 2.00 OK, 0/1/128 | 454 | | 455 | CON [MID=1235], GE///////////////////////// | 456 | | 457 | (timeout) | 458 | | 459 | CON [MID=1235], GET, /status, 2/0/64 ------> | 460 | | 461 | <------ ACK [MID=1235], 2.00 OK, 2/1/64 | 462 : : 463 : ... : 464 : : 465 | CON [MID=1238], GET, /status, 5/0/64 ------> | 466 | | 467 | <------ ACK [MID=1238], 2.00 OK, 5/0/64 | 468 Figure 5: Blockwise GET with late negotiation and lost CON 470 CLIENT SERVER 471 | | 472 | CON [MID=1234], GET, /status ------> | 473 | | 474 | <------ ACK [MID=1234], 2.00 OK, 0/1/128 | 475 | | 476 | CON [MID=1235], GET, /status, 2/0/64 ------> | 477 | | 478 | /////////////////////////////////OK, 2/1/64 | 479 | | 480 | (timeout) | 481 | | 482 | CON [MID=1235], GET, /status, 2/0/64 ------> | 483 | | 484 | <------ ACK [MID=1235], 2.00 OK, 2/1/64 | 485 : : 486 : ... : 487 : : 488 | CON [MID=1238], GET, /status, 5/0/64 ------> | 489 | | 490 | <------ ACK [MID=1238], 2.00 OK, 5/0/64 | 492 Figure 6: Blockwise GET with late negotiation and lost ACK 494 The following examples demonstrate a PUT exchange; a POST exchange 495 looks the same, with different requirements on atomicity/idempotence. 496 To ensure that the blocks relate to the same version of the resource 497 representation carried in the request, the client in Figure 7 sets 498 the Token to "v17" in all requests. Note that, as with the GET, the 499 responses to the requests that have a more bit in the request block 500 option are provisional; only the final response tells the client that 501 the PUT succeeded. 503 CLIENT SERVER 504 | | 505 | CON [MID=1234], PUT, /options, v17, 0/1/128 ------> | 506 | | 507 | <------ ACK [MID=1234], 2.04 Changed, 0/1/128 | 508 | | 509 | CON [MID=1235], PUT, /options, v17, 1/1/128 ------> | 510 | | 511 | <------ ACK [MID=1235], 2.04 Changed, 1/1/128 | 512 | | 513 | CON [MID=1236], PUT, /options, v17, 2/0/128 ------> | 514 | | 515 | <------ ACK [MID=1236], 2.04 Changed, 2/0/128 | 517 Figure 7: Simple atomic blockwise PUT 519 A stateless server that simply builds/updates the resource in place 520 (statelessly) may indicate this by not setting the more bit in the 521 response (Figure 8); in this case, the response codes are valid 522 separately for each block being updated. This is of course only an 523 acceptable behavior of the server if the potential inconsistency 524 present during the run of the message exchange sequence does not lead 525 to problems, e.g. because the resource being created or changed is 526 not yet or not currently in use. 528 CLIENT SERVER 529 | | 530 | CON [MID=1234], PUT, /options, v17, 0/1/128 ------> | 531 | | 532 | <------ ACK [MID=1234], 2.04 Changed, 0/0/128 | 533 | | 534 | CON [MID=1235], PUT, /options, v17, 1/1/128 ------> | 535 | | 536 | <------ ACK [MID=1235], 2.04 Changed, 1/0/128 | 537 | | 538 | CON [MID=1236], PUT, /options, v17, 2/0/128 ------> | 539 | | 540 | <------ ACK [MID=1236], 2.04 Changed, 2/0/128 | 542 Figure 8: Simple stateless blockwise PUT 544 Finally, a server receiving a blockwise PUT or POST may want to 545 indicate a smaller block size preference (Figure 9). In this case, 546 the client SHOULD continue with a smaller block size; if it does, it 547 MUST adjust the block number to properly count in that smaller size. 549 CLIENT SERVER 550 | | 551 | CON [MID=1234], PUT, /options, v17, 0/1/128 ------> | 552 | | 553 | <------ ACK [MID=1234], 2.04 Changed, 0/1/32 | 554 | | 555 | CON [MID=1235], PUT, /options, v17, 4/1/32 ------> | 556 | | 557 | <------ ACK [MID=1235], 2.04 Changed, 4/1/32 | 558 | | 559 | CON [MID=1236], PUT, /options, v17, 5/1/32 ------> | 560 | | 561 | <------ ACK [MID=1235], 2.04 Changed, 5/1/32 | 562 | | 563 | CON [MID=1237], PUT, /options, v17, 6/0/32 ------> | 564 | | 565 | <------ ACK [MID=1236], 2.04 Changed, 6/0/32 | 567 Figure 9: Simple atomic blockwise PUT with negotiation 569 3.1. HTTP Mapping Considerations 571 In this subsection, we give some brief examples for the influence the 572 Block Option might have on intermediaries that map between CoAP and 573 HTTP. 575 For mapping CoAP requests to HTTP, the intermediary may want to map 576 the block-wise transfer into a single HTTP transfer. E.g., for a GET 577 request, the intermediary could perform the HTTP request once the 578 first block has been requested and could then fulfill all further 579 block requests out of its cache. A constrained implementation may 580 not be able to cache the entire object and may use a combination of 581 TCP flow control and (in particular if timeouts occur) HTTP range 582 requests to obtain the information necessary for the next block 583 transfer at the right time. 585 For PUT or POST requests, there is more variation in how HTTP servers 586 might implement ranges. Some WebDAV servers do, but in general the 587 CoAP-to-HTTP intermediary will have to try sending the payload of all 588 the blocks of a block-wise transfer within one HTTP request. If 589 enough buffering is available, this request can be started when the 590 last CoAP block is received. A constrained implementation may want 591 to relieve its buffering by already starting to send the HTTP request 592 at the time the first CoAP block is received; any HTTP 408 status 593 code that indicates that the HTTP server became impatient with the 594 resulting transfer can then be mapped into a CoAP 4.08 response code 595 (similarly, 413 maps to 4.13). 597 For mapping HTTP to CoAP, the intermediary may want to map a single 598 HTTP transfer into a block-wise transfer. If the HTTP client is too 599 slow delivering a request body on a PUT or POST, the CoAP server 600 might time out and return a 4.08 response code, which in turn maps 601 well to an HTTP 408 status code (again, 4.13 maps to 413). HTTP 602 range requests received on the HTTP side may be served out of a cache 603 and/or mapped to GET requests that request a sequence of blocks 604 overlapping the range. 606 4. IANA Considerations 608 This draft adds the following option number to the CoAP Option 609 Numbers registry of [I-D.ietf-core-coap]: 611 +--------+-------+-----------+ 612 | Number | Name | Reference | 613 +--------+-------+-----------+ 614 | 13 | Block | [RFCXXXX] | 615 +--------+-------+-----------+ 617 Table 1: CoAP Option Numbers 619 This draft adds the following response code to the CoAP Response 620 Codes registry of [I-D.ietf-core-coap]: 622 +------+--------------------------------+-----------+ 623 | Code | Description | Reference | 624 +------+--------------------------------+-----------+ 625 | 136 | 4.08 Request Entity Incomplete | [RFCXXXX] | 626 +------+--------------------------------+-----------+ 628 Table 2: CoAP Response Codes 630 5. Security Considerations 632 Providing access to blocks within a resource may lead to surprising 633 vulnerabilities. Where requests are not implemented atomically, an 634 attacker may be able to exploit a race condition or confuse a server 635 by inducing it to use a partially updated resource representation. 636 Partial transfers may also make certain problematic data invisible to 637 intrusion detection systems; it is RECOMMENDED that an intrusion 638 detection system (IDS) that analyzes resource representations 639 transferred by CoAP implement the Block option to gain access to 640 entire resource representations. Still, approaches such as 641 transferring even-numbered blocks on one path and odd-numbered blocks 642 on another path, or even transferring blocks multiple times with 643 different content and obtaining a different interpretation of 644 temporal order at the IDS than at the server, may prevent an IDS from 645 seeing the whole picture. These kinds of attacks are well understood 646 from IP fragmentation and TCP segmentation; CoAP does not add 647 fundamentally new considerations. 649 Where access to a resource is only granted to clients making use of a 650 specific security association, all blocks of that resource MUST be 651 subject to the same security checks; it MUST NOT be possible for 652 unprotected exchanges to influence blocks of an otherwise protected 653 resource. As a related consideration, where object security is 654 employed, PUT/POST should be implemented in the atomic fashion, 655 unless the object security operation is performed on each access and 656 the creation of unusable resources can be tolerated. 658 5.1. Mitigating Resource Exhaustion Attacks 660 Certain blockwise requests may induce the server to create state, 661 e.g. to create a snapshot for the blockwise GET of a fast-changing 662 resource to enable consistent access to the same version of a 663 resource for all blocks, or to create temporary resource 664 representations that are collected until pressed into service by a 665 final PUT or POST with the more bit unset. All mechanisms that 666 induce a server to create state that cannot simply be cleaned up 667 create opportunities for denial-of-service attacks. Servers SHOULD 668 avoid being subject to resource exhaustion based on state created by 669 untrusted sources. But even if this is done, the mitigation may 670 cause a denial-of-service to a legitimate request when it is drowned 671 out by other state-creating requests. Wherever possible, servers 672 should therefore minimize the opportunities to create state for 673 untrusted sources, e.g. by using stateless approaches. 675 Performing segmentation at the application layer is almost always 676 better in this respect than at the transport layer or lower (IP 677 fragmentation, adaptation layer fragmentation), e.g. because there is 678 application layer semantics that can be used for mitigation or 679 because lower layers provide security associations that can prevent 680 attacks. However, it is less common to apply timeouts and keepalive 681 mechanisms at the application layer than at lower layers. Servers 682 MAY want to clean up accreted state by timing it out (cf. response 683 code 4.08), and clients SHOULD be prepared to run blockwise transfers 684 in an expedient way to minimize the likelihood of running into such a 685 timeout. 687 5.2. Mitigating Amplification Attacks 689 [I-D.ietf-core-coap] discusses the susceptibility of CoAP end-points 690 for use in amplification attacks. 692 A CoAP server can reduce the amount of amplification it provides to 693 an attacker by offering large resource representations only in 694 relatively small blocks. With this, e.g., for a 1000 byte resource, 695 a 10-byte request might result in an 80-byte response (with a 64-byte 696 block) instead of a 1016-byte response, considerably reducing the 697 amplification provided. 699 6. Acknowledgements 701 Much of the content of this draft is the result of discussions with 702 the [I-D.ietf-core-coap] authors, and via many CoRE WG discussions. 703 Tokens were suggested by Gilman Tolle and refined by Klaus Hartke. 705 7. References 707 7.1. Normative References 709 [I-D.ietf-core-coap] 710 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 711 "Constrained Application Protocol (CoAP)", 712 draft-ietf-core-coap-05 (work in progress), March 2011. 714 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 715 Requirement Levels", BCP 14, RFC 2119, March 1997. 717 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 718 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 719 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 721 7.2. Informative References 723 [REST] Fielding, R., "Architectural Styles and the Design of 724 Network-based Software Architectures", 2000. 726 Authors' Addresses 728 Zach Shelby (editor) 729 Sensinode 730 Kidekuja 2 731 Vuokatti 88600 732 Finland 734 Phone: +358407796297 735 Email: zach@sensinode.com 737 Carsten Bormann 738 Universitaet Bremen TZI 739 Postfach 330440 740 Bremen D-28359 741 Germany 743 Phone: +49-421-218-63921 744 Fax: +49-421-218-7000 745 Email: cabo@tzi.org