idnits 2.17.1 draft-ietf-core-block-00.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 18, 2010) is 4910 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) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-02 ** 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: April 21, 2011 Universitaet Bremen TZI 6 October 18, 2010 8 Blockwise transfers in CoAP 9 draft-ietf-core-block-00 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 April 21, 2011. 36 Copyright Notice 38 Copyright (c) 2010 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 . . . . . . . . . . . . . . . . . . . . . 4 55 2.1. The Block Option . . . . . . . . . . . . . . . . . . . . . 4 56 2.2. Using the Block Option . . . . . . . . . . . . . . . . . . 6 57 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 58 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 59 4.1. Mitigating Amplification Attacks . . . . . . . . . . . . . 10 60 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 61 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 62 6.1. Normative References . . . . . . . . . . . . . . . . . . . 12 63 6.2. Informative References . . . . . . . . . . . . . . . . . . 12 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 66 1. Introduction 68 The CoRE WG is tasked with standardizing an Application Protocol for 69 Constrained Networks/Nodes, CoAP. This protocol is intended to 70 provide RESTful [REST] services not unlike HTTP [RFC2616], while 71 reducing the complexity of implementation as well as the size of 72 packets exchanged in order to make these services useful in a highly 73 constrained network of themselves highly constrained nodes. 75 This objective requires restraint in a number of sometimes 76 conflicting ways: 78 o reducing implementation complexity in order to minimize code size, 80 o reducing message sizes in order to minimize the number of 81 fragments needed for each message (in turn to maximize the 82 probability of delivery of the message), the amount of 83 transmission power needed and the loading of the limited-bandwidth 84 channel, 86 o reducing requirements on the environment such as stable storage, 87 good sources of randomness or user interaction capabilities. 89 CoAP is based on datagram transports such as UDP, which limit the 90 maximum size of resource representations that can be transferred 91 without creating unreasonable levels of fragmentation. The Block 92 option provides a minimal way to transfer larger resource 93 representations in a block-wise fashion. 95 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 96 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 97 and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119] 98 and indicate requirement levels for compliant CoAP implementations. 100 2. Block-wise transfers 102 Not all resource representations will fit into a single link layer 103 packet of a constrained network. Using fragmentation (either at the 104 adaptation layer or at the IP layer) to enable the transport of 105 larger representations is possible up to the maximum size of the 106 underlying datagram protocol (such as UDP), but the fragmentation/ 107 reassembly process loads the lower layers with conversation state 108 that is better managed in the application layer. 110 This specification proposes an option to enable _block-wise_ access 111 to resource representations. The overriding objective is to avoid 112 creating conversation state at the server for block-wise GET 113 requests. (It is impossible to fully avoid creating conversation 114 state for POST/PUT, if the creation/replacement of resources is to be 115 atomic; where that property is not needed, there is no need to create 116 server conversation state in this case, either.) 118 Implementation of the Block option is intended to be optional. 119 However, when it is present in a CoAP message, it MUST be processed; 120 therefore it is identified as a critical option. 122 The size of the blocks should not be fixed by the protocol. On the 123 other hand, implementation should be as simple as possible. The 124 Block option therefore supports a small range of power-of-two block 125 sizes, from 2^4 (16) to 2^11 (2048) bytes. One of these eight values 126 can be encoded in three bits (0 for 2^4 to 7 for 2^11 bytes), the 127 "SZX" (size exponent); the actual block size is then "1 << (SZX + 128 4)". 130 2.1. The Block Option 132 When a representation is larger than can be comfortably transferred 133 in a single UDP datagram, the Block option can be used to indicate a 134 block-wise transfer. Block is a 1-, 2- or 3-byte integer, the four 135 least significant bits of which indicate the size and whether the 136 current block-wise transfer is the last block being transferred (M or 137 "more" bit). The value divided by sixteen is the number of the block 138 currently being transferred, starting from zero, i.e., the current 139 transfer is about the "size" bytes starting at "block number << (SZX 140 + 4)". The default value of the Block Option is zero, indicating 141 that the current block is the first (block number 0) and only (M bit 142 not set) block of the transfer; however, there is no explicit size 143 implied by this default value. 145 0 146 0 1 2 3 4 5 6 7 147 +-+-+-+-+-+-+-+-+ 148 | NUM |M| SZX | 149 +-+-+-+-+-+-+-+-+ 151 0 1 152 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 153 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 154 | NUM |M| SZX | 155 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 157 0 1 2 158 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 159 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 160 | NUM |M| SZX | 161 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 163 Figure 1: Block option 165 (Note that the option with the last 4 bits masked out, shifted to the 166 left by the value of SZX, gives the byte position of the block.) 168 NUM: Block Number. The block number is a variable 4-20 bit unsigned 169 integer indicating the block number being requested or provided. 170 Block number 0 indicates the first block of a representation. 172 M: More Flag. This flag indicates if this block is the last in a 173 representation when set. When not set it indicates that there are 174 one or more blocks available. When the block option is used to 175 retrieve a specific block number the M bit MUST be sent as zero 176 and ignored on reception. 178 SZX: Block Size. The block size indicates the size of a block to 179 the power of two. Thus block size = 2^(SZX + 4). Thus the 180 minimum block size is 16 and the maximum is 2048. 182 The Block option is used in one of three roles: 184 o In the request for a GET, the Block option gives the block number 185 requested and suggests a block size (block number 0) or echoes the 186 block size of previous blocks received (block numbers other than 187 0). 189 o In the response for a GET or in the request for a PUT or POST, the 190 Block option describes what block number is contained in the 191 payload, and whether further blocks are part of that body (M bit). 192 If the M bit is set, the size of the payload body in bytes MUST 193 indeed be the power of two given by the block size. All blocks 194 for a REST transaction MUST use the same block size, except for 195 the last block (M bit not set). 197 o In the response for a PUT or POST, the Block option indicates what 198 block number is being acknowledged. In this case, the M bit is 199 set to indicate that this response does not carry the final 200 response to the request; this can occur when the M bit was set in 201 the request and the server implements PUT/POST atomically (i.e., 202 acts only upon reception of the last block). 204 2.2. Using the Block Option 206 Using the Block option, a single REST operation can be split into 207 multiple CoAP message transactions. Each of these message 208 transactions uses their own CoAP transaction ID. 210 When a GET is answered with a response carrying a Block option with 211 the M bit set, the requestor may retrieve additional blocks of the 212 resource representation by sending requests with a Block option 213 giving the block number desired. In such a Block option, the M bit 214 MUST be sent as zero and ignored on reception. 216 To influence the block size used in response to a GET request, the 217 requestor uses the Block option, giving the desired size, a block 218 number of zero and an M bit of zero. A server SHOULD use the block 219 size indicated or a smaller size. Any further block-wise requests 220 for blocks beyond the first one MUST indicate the same block size 221 that was already used in the response for the first one. 223 If the Block option is used by the requestor, all GET requests in a 224 single transaction (except for the last one with the M bit not set) 225 MUST ultimately use the same size. The server SHOULD use the block 226 size indicated in the request option or a smaller size, but the 227 requestor MUST take note of the actual block size used in the 228 response it receives to its initial GET and proceed to use it in 229 subsequent GETs; the server behavior MUST ensure that this client 230 behavior results in the same block size for all responses in a 231 sequence (except for the last one with the M bit not set). 233 Block-wise transfers can be used to GET resources the representations 234 of which are entirely static (not changing over time at all, such as 235 in a schema describing a device), or for dynamically changing 236 resources. In the latter case, the Block option SHOULD be used in 237 conjunction with the Etag option, to ensure that the blocks being 238 reassembled are from the same version of the representation. When 239 reassembling the representation from the blocks being exchanged, the 240 reassembler MUST compare Etag options. If the Etag options do not 241 match in a GET transfer, the requestor has the option of attempting 242 to retrieve fresh values for the blocks it retrieved first. To 243 minimize the resulting inefficiency, the server MAY cache the current 244 value of a representation for an ongoing sequence of requests, but 245 there is no requirement for the server to establish any state. The 246 client MAY facilitate identifying the sequence by using the Token 247 option. 249 In a PUT or POST transfer, the Block option refers to the body in the 250 request, i.e., there is no way to perform a block-wise retrieval of 251 the body of the response. Servers that do need to supply large 252 bodies in response to PUT/POST SHOULD therefore be employing 253 redirects. 255 In a PUT or POST transfer that is intended to be implemented in an 256 atomic fashion at the server, the actual creation/replacement takes 257 place at the time a block with the M bit unset is received. If not 258 all previous blocks are available at the server at this time, the 259 transfer fails and error code 4__ (TBD) MUST be returned. The error 260 code 4__ can also be returned at any time by a server that does not 261 currently have the resources to store blocks for a block-wise PUT or 262 POST transfer that it would intend to implement in an atomic fashion. 264 If multiple concurrently proceeding block-wise PUT or POST operations 265 are possible, the requestor SHOULD use the Token option to clearly 266 separate the different sequences. In this case, when reassembling 267 the representation from the blocks being exchanged to enable atomic 268 processing, the reassembler MUST compare any Token options present 269 (taking an absent Token option to default to the empty Token). If 270 atomic processing is not desired, there is no need to check the Token 271 option. 273 In summary, this specification: Adds a Block Option that can be used 274 for block-wise transfers. 276 Benefits: Transfers larger than can be accommodated in constrained- 277 network link-layer packets can be performed in smaller blocks. 279 No hard-to-manage conversation state is created at the adaptation 280 layer or IP layer for fragmentation. 282 The transfer of each block is acknowledged, enabling 283 retransmission if required. 285 Both sides have a say in the block size that actually will be 286 used. 288 TBD: Give examples with detailed message flows for a block-wise GET, 289 PUT and POST. 291 3. IANA Considerations 293 This draft adds the following option number to Table 2 of 294 [I-D.ietf-core-coap]: 296 +------+-----+-------+----------------+--------+--------------------+ 297 | Type | C/E | Name | Data type | Length | Default | 298 +------+-----+-------+----------------+--------+--------------------+ 299 | 13 | C | Block | Unsigned | 1-3 B | 0 (see | 300 | | | | Integer | | Section 2.1) | 301 +------+-----+-------+----------------+--------+--------------------+ 303 4. Security Considerations 305 TBD. (Weigh the security implications of application layer block- 306 wise transfer against those of adaptation-layer or IP-layer 307 fragmentation.) 309 4.1. Mitigating Amplification Attacks 311 TBD. (This section discusses how CoAP nodes could become implicated 312 in DoS attacks by using the amplifying properties of the protocol, as 313 well as mitigations for this threat.) 315 A CoAP server can reduce the amount of amplification it provides to 316 an attacker by offering large resource representations only in 317 relatively small blocks. E.g., for a 1000 byte resource, a 10-byte 318 request might result in an 80-byte response (with a 64-byte block) 319 instead of a 1016-byte response, considerably reducing the 320 amplification provided. 322 5. Acknowledgements 324 Of course, much of the content of this draft is the result of 325 discussions with the [I-D.ietf-core-coap] authors. Tokens were 326 suggested by Gilman Tolle and refined by Klaus Hartke. 328 6. References 330 6.1. Normative References 332 [I-D.ietf-core-coap] 333 Shelby, Z., Frank, B., and D. Sturek, "Constrained 334 Application Protocol (CoAP)", draft-ietf-core-coap-02 335 (work in progress), September 2010. 337 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 338 Requirement Levels", BCP 14, RFC 2119, March 1997. 340 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 341 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 342 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 344 6.2. Informative References 346 [REST] Fielding, R., "Architectural Styles and the Design of 347 Network-based Software Architectures", 2000. 349 Authors' Addresses 351 Zach Shelby (editor) 352 Sensinode 353 Kidekuja 2 354 Vuokatti 88600 355 FINLAND 357 Phone: +358407796297 358 Email: zach@sensinode.com 360 Carsten Bormann 361 Universitaet Bremen TZI 362 Postfach 330440 363 Bremen D-28359 364 Germany 366 Phone: +49-421-218-63921 367 Fax: +49-421-218-7000 368 Email: cabo@tzi.org