idnits 2.17.1 draft-bormann-core-coap-block-01.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 24, 2010) is 4932 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == 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) == Outdated reference: A later version (-21) exists of draft-ietf-core-block-00 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Informational October 24, 2010 5 Expires: April 27, 2011 7 Sliced transfers in CoAP 8 draft-bormann-core-coap-block-01 10 Abstract 12 CoAP is a RESTful transfer protocol for constrained nodes and 13 networks. CoAP is based on datagram transport, which limits the 14 maximum size of resource representations that can be transferred 15 without too much fragmentation. A previous version of this draft 16 defined the Block option. The Block option provides a minimal way to 17 transfer larger representations in a block-wise fashion. It is 18 currently documented in the WG draft draft-ietf-core-block-00.txt 20 This short I-D attempts to pick up some recent discussion on the CoRE 21 mailing list, and defines a more general, but also slightly more 22 complex approach. It is intended as an example for a complete design 23 based on this discussion, to enable a rational assessment of the 24 relative complexities. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on April 27, 2011. 43 Copyright Notice 45 Copyright (c) 2010 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 62 2. Sliced transfers . . . . . . . . . . . . . . . . . . . . . . . 5 63 2.1. The Continuation Options . . . . . . . . . . . . . . . . . 5 64 2.2. Using the Continuation Options . . . . . . . . . . . . . . 6 65 2.3. Option values for Continuation-request and 66 Continuation-response . . . . . . . . . . . . . . . . . . 7 67 2.4. The Message-Size option . . . . . . . . . . . . . . . . . 8 68 3. The Size-Estimate option . . . . . . . . . . . . . . . . . . . 9 69 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 70 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 71 5.1. Mitigating Amplification Attacks . . . . . . . . . . . . . 11 72 5.2. Exposing Server Internals in Continuation-response 73 Values . . . . . . . . . . . . . . . . . . . . . . . . . . 11 74 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 75 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 76 7.1. Normative References . . . . . . . . . . . . . . . . . . . 13 77 7.2. Informative References . . . . . . . . . . . . . . . . . . 13 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 80 1. Introduction 82 The CoRE WG is tasked with standardizing an Application Protocol for 83 Constrained Networks/Nodes, CoAP. This protocol is intended to 84 provide RESTful [REST] services not unlike HTTP [RFC2616], while 85 reducing the complexity of implementation as well as the size of 86 packets exchanged in order to make these services useful in a highly 87 constrained network of themselves highly constrained nodes. 89 This objective requires restraint in a number of sometimes 90 conflicting ways: 92 o reducing implementation complexity in order to minimize code size, 94 o reducing message sizes in order to minimize the number of 95 fragments needed for each message (in turn to maximize the 96 probability of delivery of the message), the amount of 97 transmission power needed and the loading of the limited-bandwidth 98 channel, 100 o reducing requirements on the environment such as stable storage, 101 good sources of randomness or user interaction capabilities. 103 CoAP is based on datagram transports such as UDP, which limit the 104 maximum size of resource representations that can be transferred 105 without creating unreasonable levels of fragmentation. 107 A previous version of this draft defined the Block option. The Block 108 option provides a minimal way to transfer larger representations in a 109 block-wise fashion. It is currently documented in a CoAP WG draft 110 [I-D.ietf-core-block]. 112 Recent discussion on the CoRE mailing list centered around the 113 limitations of the Block approach: 115 o Block is based on fixed block sizes and does not provide for 116 semantic fragmentation of the resource representation. 118 o The choice of block sizes is limited to a power of two. 120 o For continuation transfers, the server only receives a numeric 121 block number and a block size, which only enables it to operate in 122 a stateless fashion if the resource representation can be 123 naturally addressed on such block boundaries. 125 o The negotiation of the desirable message size is quite efficient, 126 but may be simplistic. 128 This short I-D attempts to pick up this discussion and defines a more 129 general, but also slightly more complex approach. It is intended as 130 an example for a complete design based on this discussion, to enable 131 a rational assessment of the relative complexities. 133 1.1. Terminology 135 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 136 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 137 and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119] 138 and indicate requirement levels for compliant CoAP implementations. 140 The term "byte" is used in its now customary sense as a synonym for 141 "octet". 143 2. Sliced transfers 145 Not all resource representations will fit into a single link layer 146 packet of a constrained network. Using fragmentation (either at the 147 adaptation layer or at the IP layer) to enable the transport of 148 larger representations is possible up to the maximum size of the 149 underlying datagram protocol (such as UDP), but the fragmentation/ 150 reassembly process loads the lower layers with conversation state 151 that is better managed in the application layer. 153 This specification proposes a set of CoAP options to enable _sliced_ 154 access to resource representations. The overriding objective is to 155 avoid creating conversation state at the server for sliced GET 156 requests. (It is impossible to fully avoid creating conversation 157 state for POST/PUT, if the creation/replacement of resources is to be 158 atomic; where that property is not needed, there is no need to create 159 server conversation state in this case, either.) 161 Implementation of the options defined in this draft is intended to be 162 optional. However, when one of the Continuation options is present 163 in a CoAP message, it MUST be processed; therefore these options are 164 identified as critical options. 166 In contrast to the Block option, which provides a limited choice of 167 block sizes and requires all the transfers for one single resource 168 representation retrieval to be of the same size, the options defined 169 in this draft enable a transfer to be structured into a sequence of 170 arbitrarily-sized _slices_, which are of independent size and are 171 only limited by the datagram size of the underlying transport as well 172 as the slice size preferences of the communicating nodes. 174 2.1. The Continuation Options 176 When a representation is larger than can be comfortably transferred 177 in a single UDP datagram, the Continuation options can be used to 178 indicate a sliced transfer. The value of both Continuation-request 179 and Continuation-response options is an opaque sequence of bytes that 180 is used to link up one slice transaction with the next in a sequence 181 of transactions. 183 A Continuation-request option in a request indicates that the current 184 transaction is intended as a continuation of the previous transaction 185 that provided the same value for the Continuation-response option in 186 a response. 188 Where a GET request is sliced up, the Continuation-response option in 189 a response indicates that the slice(s) received so far are not the 190 complete resource representation, but an initial prefix of the 191 representation. Further bytes of the representation can be retrieved 192 by supplying the value of the Continuation-response option returned 193 in the Continuation-request option of another request that otherwise 194 looks like a GET request. 196 (TBD: Does the continuation request have to supply the URI and other 197 parameters again along with the Continuation-request option, or does 198 the server make sure the Continuation-response provides all 199 information required, e.g., by sending back a descriptor or by 200 encoding the request parameters in the Continuation-response?) 202 Each continuation response in a sliced transfer carries the response 203 code that, based on information currently available, the server 204 expects the transfer to receive at the end of the entire sequence of 205 slices, e.g. a 200 code (encoded as 80 decimal) for a successful 206 resource representation retrieval. However, only the response code 207 of the last slice transferred (i.e., without a Continuation-response 208 option) is binding. 210 2.2. Using the Continuation Options 212 Using the Continuation options, a single REST operation can be split 213 into multiple CoAP message transactions. Each of these message 214 transactions uses their own CoAP transaction ID. 216 For synchronous responses, the Continuation-request option does not 217 need to be repeated in the response. For an asynchronous response, 218 the server provides both the Continuation-request option and, if 219 applicable, the Continuation-response option. 221 For GET requests, the server simply adds the Continuation-response 222 option to any response for which it is unable or unwilling to include 223 the entire resource representation. The client then echoes back the 224 value of the Continuation-response in the value of a Continuation- 225 request option. The response carrying the last slice of the 226 representation simply does not contain a Continuation-response 227 option; it is distinguishable from a response carrying the entire 228 resource representation by the presence of Continuation-request in 229 the related request (synchronous) or in the response (asynchronous). 231 For PUT and POST requests, a client has to indicate that it requests 232 a Continuation-response option from the server whenever it is unable 233 or unwilling to provide the entire (rest of the) representation in 234 the current transaction, i.e. that the slice(s) transferred so far 235 are only a prefix of the entire representation to be transferred. 236 This is done by supplying a Continuation-required option in the 237 request. The request that carries the last slice of the 238 representation does not contain a Continuation-required option. 240 However, the response to that last forward-transferring request may 241 carry a Continuation-response option, in case the representation 242 returned from the PUT or POST request is larger than can be 243 comfortably transferred in one message. The exchange then continues 244 as it would for a sliced GET request. 246 2.3. Option values for Continuation-request and Continuation-response 248 The structure of the values provided by the server in a Continuation- 249 response option (and echoed back by the client in a Continuation- 250 request option) is not defined by the protocol. The structure of the 251 value is opaque to the client and entirely determined by the server. 252 In particular, the client is not permitted to manipulate or "make up" 253 Continuation-request values. 255 For a stateless server, the structure of the value will be chosen to 256 enable generating the next slice. E.g., for a server enumerating 257 devices, the value might be an identifier for the last device 258 described in the last slice. 260 In order to increase the debuggability of the protocol, there is a 261 suggested structure that can (but need not be) be used whenever it is 262 a good fit. This structure only works when all slices in a transfer 263 (except for the last) use the same slice size, which also is a power 264 of two. If the structure is used, the value of the Continuation- 265 request and Continuation-response options is a sequence of bytes 266 representing an unsigned integer, the three least significant bits of 267 which indicate the size of all slices used in the transfer. The 268 value divided by eight is the number of the slice the Continuation- 269 response pertains to, starting from zero, i.e., the response is about 270 the "size" bytes starting at byte "blocknr << (szx + 3)"; note that 271 the value of the Continuation-request option in the next request 272 echoes the number of the previously transferred block. 274 0 275 0 1 2 3 4 5 6 7 276 +-+-+-+-+-+-+-+-+ 277 | blocknr | szx | 278 +-+-+-+-+-+-+-+-+ 280 0 1 281 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 283 | block nr | szx | 284 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 286 0 1 2 287 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 288 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 289 | block nr | szx | 290 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 292 Figure 1: Suggested structure of the Continuation option values for 293 block-wise transfers, if applicable 295 2.4. The Message-Size option 297 To influence the slice size used in response to a GET request, the 298 requester uses the (elective) Message-Size option, giving the desired 299 maximum size of a message. A server SHOULD use the slice size 300 indicated or a smaller size. 302 To influence the slice size used in a PUT or POST request, the server 303 can provide an (elective) Message-Size option in its first response. 304 For the continuation requests, the client SHOULD use the slice size 305 indicated or a smaller size. Since there is no way for the server to 306 influence the size of the first message, the slice carried in this 307 message should be kept reasonably small (e.g., a size that is 308 commensurate with the overhead of the request or even zero bytes in 309 size). A client MAY cache Message-Size options received from a 310 server and use the cached value as a hint for future PUT or POST 311 transactions to that server. 313 3. The Size-Estimate option 315 (This is new functionality not provided by the Block option.) 317 The party slicing up a resource representation for sliced transfer 318 may have an idea of the size of the entire resource representation in 319 bytes. Providing this size as an estimate may be beneficial for the 320 other party. If provided, it should be sent with the first slice, 321 and SHOULD provide a close upper bound of the total size that will be 322 transferred. In a PUT or POST transfer, both sides MAY provide a 323 Size-Estimate for their respective resource representation to be 324 transferred. 326 4. IANA Considerations 328 This draft adds the following option numbers to Table 2 of 329 [I-D.ietf-core-coap]: 331 +-----+----+--------------------+----------------+--------+---------+ 332 | Typ | C/ | Name | Data type | Length | Default | 333 | e | E | | | | | 334 +-----+----+--------------------+----------------+--------+---------+ 335 | 16 | E | Message-Size | Variable-lengt | 1-2 B | (none) | 336 | | | | h unsigned | | | 337 | | | | integer | | | 338 | | | | | | | 339 | 17 | C | Continuation-reque | Opaque String | (any) | (none) | 340 | | | st | of Bytes | | | 341 | | | | | | | 342 | 18 | E | Size-Estimate | Variable-lengt | 1-4 B | (none) | 343 | | | | h unsigned | | | 344 | | | | integer | | | 345 | | | | | | | 346 | 19 | C | Continuation-respo | Opaque String | (any) | (none) | 347 | | | nse | of Bytes | | | 348 | | | | | | | 349 | 21 | C | Continuation-requi | (none) | 0 | (none) | 350 | | | red | | | | 351 +-----+----+--------------------+----------------+--------+---------+ 353 5. Security Considerations 355 TBD. (Weigh the security implications of application layer sliced 356 transfer against those of adaptation-layer or IP-layer 357 fragmentation.) 359 5.1. Mitigating Amplification Attacks 361 TBD. (This section discusses how CoAP nodes could become implicated 362 in DoS attacks by using the amplifying properties of the protocol, as 363 well as mitigations for this threat.) 365 A CoAP server can reduce the amount of amplification it provides to 366 an attacker by offering large resource representations only in 367 relatively small slices. E.g., for a 1000 byte resource, a 10-byte 368 request might result in an 80-byte response (with a 64-byte block) 369 instead of a 1016-byte response, considerably reducing the 370 amplification provided. 372 5.2. Exposing Server Internals in Continuation-response Values 374 The server should be careful about the values exposed in 375 Continuation-response options: 377 o An attacker might be able to derive information from the value 378 that the server did not intend to make available, such as row 379 numbers in an internal database. This can be mitigated by 380 encrypting the value with a secret only known to the server. 382 o An attacker might attempt to forge Continuation-response values to 383 obtain increased access. Where the structure of the Continuation- 384 response might make this possible, the server should validate it 385 e.g. by including an HMAC computed from a secret only known to the 386 server. If replay attacks might be problem, the server should 387 mitigate them, e.g. by adding a timestamp or a sequence number 388 into the protected data. 390 6. Acknowledgements 392 As mentioned, much of the content of this draft is the result of 393 discussions within the CoRE mailing list, in particular with Robert 394 Quattlebaum (who insisted on variable-length semantic fragmentation) 395 and Peter Bigot. 397 7. References 399 7.1. Normative References 401 [I-D.ietf-core-coap] 402 Shelby, Z., Frank, B., and D. Sturek, "Constrained 403 Application Protocol (CoAP)", draft-ietf-core-coap-02 404 (work in progress), September 2010. 406 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 407 Requirement Levels", BCP 14, RFC 2119, March 1997. 409 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 410 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 411 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 413 7.2. Informative References 415 [I-D.ietf-core-block] 416 Shelby, Z. and C. Bormann, "Blockwise transfers in CoAP", 417 draft-ietf-core-block-00 (work in progress), October 2010. 419 [REST] Fielding, R., "Architectural Styles and the Design of 420 Network-based Software Architectures", 2000. 422 Author's Address 424 Carsten Bormann 425 Universitaet Bremen TZI 426 Postfach 330440 427 Bremen D-28359 428 Germany 430 Phone: +49-421-218-63921 431 Fax: +49-421-218-7000 432 Email: cabo@tzi.org