idnits 2.17.1 draft-bormann-coap-misc-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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 5 characters in excess of 72. 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 (June 30, 2010) is 5021 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-02) exists of draft-hartke-coap-observe-00 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-00 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group C. Bormann 3 Internet-Draft K. Hartke 4 Intended status: Informational Universitaet Bremen TZI 5 Expires: January 1, 2011 June 30, 2010 7 Miscellaneous additions to CoAP 8 draft-bormann-coap-misc-02 10 Abstract 12 This short I-D makes a number of partially interrelated proposals how 13 to solve certain problems in the CoRE WG's main protocol, CoAP. 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on January 1, 2011. 32 Copyright Notice 34 Copyright (c) 2010 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. A Compact Accept Option . . . . . . . . . . . . . . . . . . . 4 51 3. Representing Durations . . . . . . . . . . . . . . . . . . . . 6 52 3.1. Pseudo-Floating Point . . . . . . . . . . . . . . . . . . 6 53 3.2. A Duration Type for CoAP . . . . . . . . . . . . . . . . . 8 54 4. URI encoding . . . . . . . . . . . . . . . . . . . . . . . . . 9 55 4.1. An efficient stateless URI encoding . . . . . . . . . . . 9 56 4.2. Stateful URI compression . . . . . . . . . . . . . . . . . 11 57 5. Block-wise transfers . . . . . . . . . . . . . . . . . . . . . 13 58 5.1. The Block Option . . . . . . . . . . . . . . . . . . . . . 13 59 6. Option Encoding . . . . . . . . . . . . . . . . . . . . . . . 17 60 6.1. A More Efficient Option Encoding . . . . . . . . . . . . . 17 61 6.2. Critical Options . . . . . . . . . . . . . . . . . . . . . 18 62 6.3. Payload-Length Option . . . . . . . . . . . . . . . . . . 18 63 6.4. Problems with specific options . . . . . . . . . . . . . . 19 64 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 65 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 66 8.1. Amplification Attacks . . . . . . . . . . . . . . . . . . 22 67 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 68 9.1. Normative References . . . . . . . . . . . . . . . . . . . 23 69 9.2. Informative References . . . . . . . . . . . . . . . . . . 23 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24 72 1. Introduction 74 The CoRE WG is tasked with standardizing an Application Protocol for 75 Constrained Networks/Nodes, CoAP. This protocol is intended to 76 provide RESTful [REST] services not unlike HTTP [RFC2616], while 77 reducing the complexity of implementation as well as the size of 78 packets exchanged in order to make these services useful in a highly 79 constrained network of themselves highly constrained nodes. 81 This objective requires restraint in a number of sometimes 82 conflicting ways: 84 o reducing implementation complexity in order to minimize code size, 86 o reducing message sizes in order to minimize the number of 87 fragments needed for each message (in turn to maximize the 88 probability of delivery of the message), the amount of 89 transmission power needed and the loading of the limited-bandwidth 90 channel, 92 o reducing requirements on the environment such as stable storage, 93 good sources of randomness or user interaction capabilities. 95 This draft attempts to address a number of problems not yet 96 adequately solved in [I-D.ietf-core-coap]. The solutions proposed to 97 these problems are somewhat interrelated and are therefore presented 98 in one draft. 100 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 101 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 102 and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119] 103 and indicate requirement levels for compliant CoAP implementations. 105 2. A Compact Accept Option 107 A resource may be available in a number of representations. Without 108 some information from the client, a server has no easy way to decide 109 which of these would be best served. HTTP has an Accept: request 110 header that a client can use to indicate the media types supported, 111 allowing the server to decide. This header is somewhat unpopular as, 112 for a web browser, there are too many media types to choose from, so 113 -- even with wildcards -- there is no meaningful information to put 114 there. (This has changed a bit for AJAX calls, which may indeed have 115 a specific media type preference.) It is unlikely that machine-to- 116 machine communication would have the same problem. 118 A similar function to the HTTP Accept: header could be added to CoAP 119 as an option in a much simpler way. The CoAP Accept option would 120 simple carry a value that is a sequence of octets, each of which is 121 an acceptable media type for the client, in the order of preference 122 (see Figure 1). If no Accept option is given, the client does not 123 express a preference. 125 0 126 0 1 2 3 4 5 6 7 127 +-+-+-+-+-+-+-+-+ 128 | mediatype | 129 +-+-+-+-+-+-+-+-+ 131 0 1 132 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 133 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 134 | mediatype1 | mediatype2 | etc. 135 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 137 Figure 1: Accept option value: A sequence of media types 139 Accept also has to be given an option type code, e.g. 7, in Table 2 140 of [I-D.ietf-core-coap]. 142 The other addition that would be required is an error code that 143 mirrors HTTP's "415 Unsupported Media Type". This is indeed already 144 listed as CoAP Code 35 in Table 3 of [I-D.ietf-core-coap]. 146 Proposal: Add an Accept Option. 148 Benefits: A Server does not need to specify one URI each for every 149 possible media type that it wants to serve a resource under. 151 Open Issues: For coap-00, this would have needed a way to handle 152 two-byte media types (easiest if these can be made self- 153 describing, at the cost of about 3 bits in the sub-type field; 154 Figure 2). 156 An self-describing representation for long mediatypes could look like 157 this: 159 0 160 0 1 2 3 4 5 6 7 161 +-+-+-+-+-+-+-+-+ 162 | top | sub | (1-byte: unchanged) 163 +-+-+-+-+-+-+-+-+ 165 0 1 166 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 167 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 168 | 000 | top | sub | (2-byte) 169 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 171 Figure 2: A self-describing media type representation 173 3. Representing Durations 175 Various message types used in CoAP need the representation of 176 *durations*, i.e. of the length of a timespan. In SI units, these 177 are measured in seconds. Where CPU power and memory is abundant, a 178 duration can almost always be adequately represented by a non- 179 negative floating-point number representing that number of seconds. 180 Historically, many APIs have also used an integer representation, 181 which limits both the resolution (e.g., if the integer represents the 182 duration in seconds) and often the range (integer machine types have 183 range limits that may become relevant). UNIX's "time_t" (which is 184 used for both absolute time and durations) originally was a signed 185 32-bit value of seconds, but was later complemented by an additional 186 integer to add microsecond ("struct timeval") and then later 187 nanosecond ("struct timespec") resolution. 189 Three decisions need to be made for each application of the concept 190 of duration: 192 o the *resolution*. What rounding error is acceptable? 194 o the *range*. What is the maximum duration that needs to be 195 represented? 197 o the *number of bits* that can be expended. 199 Obviously, these decisions are interrelated. Typically, a large 200 range needs a large number of bits, unless resolution is traded. For 201 most applications, the actual requirement for resolution are limited 202 for longer durations, but can be more acute for shorter durations. 204 3.1. Pseudo-Floating Point 206 Constrained systems typically avoid the use of floating-point (FP) 207 values, as 209 o simple CPUs often don't have support for floating-point datatypes 211 o software floating-point libraries are expensive in code size and 212 slow. 214 In addition, floating-point datatypes used to be a significant 215 element of market differentiation in CPU design; it has taken the 216 industry a long time to agree on a standard floating point 217 representation. 219 These issues have led to protocols that try to constrain themselves 220 to integer representation even where the ability of a floating point 221 representation to trade range for resolution would be beneficial. 223 The idea of introducing _pseudo-FP_ is to obtain the increased range 224 provided by embedding an exponent, without necessarily getting stuck 225 with hardware datatypes or inefficient software floating-point 226 libraries. 228 For the purposes of this draft, we define an (n,e)-pseudo-FP as a 229 fixed-length value of n bits, e of which may be used for an exponent. 230 Figure 3 illustrates an (8,4)-pseudo-FP value. 232 0 1 2 3 4 5 6 7 233 +---+---+---+---+---+---+---+---+ 234 | 0... value | 235 +---+---+---+---+---+---+---+---+ 237 +---+---+---+---+---+---+---+---+ 238 | 1... mantissa | exponent | 239 +---+---+---+---+---+---+---+---+ 241 Figure 3: An (8,4) pseudo-FP representation 243 If the high bit is clear, the entire n-bit value (including the high 244 bit) is the decoded value. If the high bit is set, the mantissa 245 (including the high bit, but with the exponent field cleared out) is 246 shifted left by the exponent to yield the decoded value. 248 The (n,e)-pseudo-FP format can be decoded with a single line of code 249 (plus a couple of constant definition), as demonstrated in Figure 4. 251 #define N 8 252 #define E 4 253 #define HIBIT (1 << (N - 1)) 254 #define EMASK ((1 << E) - 1) 255 #define MMASK ((1 << N) - 1 - EMASK) 257 #define DECODE_8_4(r) (r < HIBIT ? r : (r & MMASK) << (r & EMASK)) 259 Figure 4: Decoding an (8,4) pseudo-FP value 261 Only non-negative numbers can be represented by this format. It is 262 designed to provide full integer resolution for values from 0 to 263 2^(n-1)-1, i.e., 0 to 127 in the (8,4) case, and a mantissa of n-e 264 bits from 2^(n-1) to (2^n-2^e)*2^(2^e-1), i.e., 128 to 7864320 in the 265 (8,4) case. By choosing e carefully, resolution can be traded 266 against range. 268 Note that a pseudo-FP encoder needs to consider rounding; different 269 applications of durations may favor rounding up or rounding down the 270 value encoded in the message. This requires a little more than a 271 single line of code (which is left as an exercise to the reader, as 272 the most efficient expression depends on hardware details). 274 3.2. A Duration Type for CoAP 276 CoAP needs durations in a number of places. In [I-D.ietf-core-coap], 277 durations occur in the option "Subscription-lifetime" as well as in 278 the option "Max-age". (Note that the option "Date" is not a 279 duration, but a point in time.) Other durations of this kind may be 280 added later. 282 Most durations relevant to CoAP are best expressed with a minimum 283 resolution of one second. More detailed resolutions are unlikely to 284 provide much benefit. 286 The range of lifetimes and caching ages are probably best kept below 287 the order of magnitude of months. An (8,4)-pseudo-FP has the maximum 288 value of 7864320, which is about 91 days; this appears to be adequate 289 for a subscription lifetime and probably even for a maximum cache 290 age. (If a larger range for the latter is indeed desired, an (8,5)- 291 pseudo-FP could be used; this would last 15 milleniums, at the cost 292 of having only 3 bits of accuracy for values larger than 127 293 seconds.) 295 Proposal: A single duration type is used throughout CoAP, based on 296 an (8,4)-pseudo-FP giving a duration in seconds. 298 Benefits: Implementations can use a single piece of code for 299 managing all CoAP-related durations. 301 In addition, length information never needs to be managed for 302 durations that are embedded in other data structures: All 303 durations are expressed by a single byte. 305 Open Issues: It might be worthwhile to reserve one duration value, 306 e.g. 0xFF, for an indefinite duration. 308 4. URI encoding 310 In HTTP-based systems, URIs can reach significant lengths. While 311 CoAP-based systems may be able to sidestep the most egregious 312 excesses (mostly by simply applying REST principles), a URI such as 314 /.well-known/resources 316 can use up one third of the available payload in a CoAP message 317 transported in a single 6LoWPAN packet. Is there a way to encode 318 these URIs in a more efficient way? 320 Several proposals have been made on the CoRE mailing list, e.g. 321 applying the principle of base64-encoding [RFC4648] in reverse and 322 using only 6 bits per character. However, due to rounding errors and 323 occasional characters that are not in the 64-character subset chosen 324 to be efficiently encodable, the actual gains are limited. 325 Similarly, using 7 bits per character (assuming URIs contain only 326 ASCII characters) only gives a best-case gain of 12.5 %, and that 327 only in the case the URI is a multiple of 8 characters long. On the 328 other hand, the complexity (and danger of subtle interoperability 329 problems) is not entirely trivial. 331 We will proceed by first proposing an URI encoding that is slightly 332 more efficient than the abovementioned ones, then rejecting even that 333 for its unconvincing cost-benefit ratio, and finally taking up 334 Henning Schulzrinne's proposal to add state. 336 4.1. An efficient stateless URI encoding 338 There is very little redundancy by repetition in a typical URI, 339 rendering popular compression methods such as LZ77 (as implemented in 340 in the widely used DEFLATE algorithm [RFC1951]) rather ineffective. 342 For the short, non-repetitive data structures that URIs tend to be, 343 efficient stateless compression is pretty much confined to Huffman 344 (or, for even more complexity, arithmetic) coding. The complexity 345 can be reduced significantly by moving to n-ary Huffman coding, i.e., 346 optimizing not to the bit level, but to a larger level of 347 granularity. Informal experiments by the author show that a 16ary 348 Huffman coding is close to optimal for reasonable URI lengths. In 349 other words, basing the encoding on nibbles (4-bit half-bytes) is 350 both nearly optimal and relatively inexpensive to implement. 352 The actual letter frequencies that will occur in CoAP URIs are hard 353 to predict. As a stopgap, the author has analyzed an HTTP-based URI 354 corpus and found the following characters to occur with high 355 frequency: 357 %.aeinorst 359 In the encoding proposed, each of these ten highly-compressed 360 characters is represented by a single 4-bit nibble. As the % 361 character is used for hexadecimal encoding in URIs, two additional 362 nibbles are used to provide the numeric value of the two hexadecimal 363 numbers following the % character (the original URI will only be 364 properly reconstituted if these are upper-case as they should be 365 according to section 2.1 of the URI specification [RFC3986]; the 366 encoder can choose to send all three characters in dual-nibble format 367 if that matters). An encoder could also map non-ASCII characters to 368 this three-nibble form, even though they are not allowed in URIs. 369 This gives compatibility with the %-encoding required by [RFC3986]. 371 All other characters are represented by both of their nibbles. The 372 resulting sequence of nibbles is reconstituted into a sequence of 373 bytes in most-significant-nibble-first order. Any unused nibble in 374 the last byte of an encoding is set to 0. (Upon decoding, this 375 padding can be readily distinguished from another % combination as 376 this would require another byte after the last byte.) The encoding 377 is summarized in Figure 5. 379 0 1 380 0 1 2 3 4 5 6 7 8 9 0 1 381 +---+---+---+---+ 382 | 1, 8-F | .aeinorst 383 +---+---+---+---+ 189ABCDEF 385 +---+---+---+---+---+---+---+---+ 386 | 2-7 | 0-F | other ASCII 387 +---+---+---+---+---+---+---+---+ 389 +---+---+---+---+---+---+---+---+---+---+---+---+ 390 | 0 | 0-F | 0-F | %HH 391 +---+---+---+---+---+---+---+---+---+---+---+---+ 393 Figure 5: A nibble-based URI encoding 395 An example encoding for "/.well-known/resources" (where the initial 396 slash is left out, as proposed for abs-path URIs) is given in 397 Figure 6. While the more than 28 % savings in this example may seem 398 just an accident, the HTTP-based corpus indeed shows an average 399 savings of about 21.8 %, i.e. the sum of the lengths of the encoded 400 version of all URIs in the corpus is about 78.2 % of the sum of the 401 length of all URIs. (The savings should be noticeably higher with a 402 more RESTful selection of URIs than was available for this 403 experiment.) 404 0 1 2 405 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 406 / . w e l l - k n o w n / r e s o u r c e s 408 2e 77 65 6c 6c 2d 6b 6e 6f 77 6e 2f 72 65 73 6f 75 72 63 65 73 409 -> 410 1 77 9 6c 6c 2d 6b b c 77 b 2f d 9 e c 75 d 63 9 e 411 = 17 79 6c 6c 2d 6b bc 77 b2 fd 9e c7 5d 63 9e 413 Figure 6: Nibble-based URI encoding: 21 -> 15 bytes 415 4.2. Stateful URI compression 417 Is the approximately 25 % average saving achievable with Huffman- 418 based URI compression schemes worth the complexity? Probably not, 419 because much higher average savings can be achieved by introducing 420 state. 422 Henning Schulzrinne has proposed for a server to be able to supply a 423 shortened URI once a resource has been requested using the full- 424 length URI. Let's call such a shortened referent a _Temporary 425 Resource Identifier_, _TeRI_ for short. This could be expressed by a 426 response option as shown in Figure 7. 428 0 429 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 430 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 431 | duration | TeRI... 432 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 434 Figure 7: Option for offering a TeRI in a response 436 The TeRI offer option indicates that the server promises to offer 437 this resources under the TeRI given for at least the time given as 438 the duration. Another TeRI offer can be made later to extend the 439 duration. 441 Once a TeRI for a URI is known (and still within its lifetime), the 442 client can supply a TeRI instead of a URI in its requests. The same 443 option format as an offer could be used to allow the client to 444 indicate how long it believes the TeRI will still be valid (so that 445 the server can decide when to update the lifetime duration). TeRIs 446 in requests could be distinguished from URIs e.g. by using a 447 different option number. 449 Proposal: Add a TeRI option (e.g., number 2) that can be used in 450 CoAP requests and responses. 452 Add a way to indicate a TeRI and its duration in a link-value. 454 Do not add any form of stateless URI encoding. 456 Benefits: Much higher reduction of message size than any stateless 457 URI encoding could achieve. 459 As the use of TeRIs is entirely optional, minimal complexity nodes 460 can get by without implementing them. 462 5. Block-wise transfers 464 Not all resource representations will fit into a single link layer 465 packet of a constrained network. Using fragmentation (either at the 466 adaptation layer or at the IP layer) to enable the transport of 467 larger representations is possible up to the maximum size of a UDP 468 datagram, but the fragmentation/reassembly process loads the lower 469 layers with conversation state that is better managed in the 470 application layer. 472 This section proposes options to enable _block-wise_ access to 473 resource representations. The overriding objective is to avoid 474 creating conversation state at the server for block-wise GET 475 requests. (It is impossible to fully avoid creating conversation 476 state for POST/PUT, if the creation/replacement of resources is to be 477 atomic; where that property is not needed, there is no need to create 478 server conversation state in this case, either.) Also, 479 implementation of these options is intended to be optional. (The 480 details of which parts of the behavior need to be mandatory to enable 481 that optionality still are TBD, see below.) 483 The size of the blocks should not be fixed by the protocol. On the 484 other hand, implementation should be as simple as possible. We 485 therefore propose a small range of power-of-two block sizes, from 2^4 486 (16) to 2^11 (2048) bytes. One of these eight values can be encoded 487 in three bits (0 for 2^4 to 7 for 2^11 bytes), the "szx" (size 488 exponent); the actual block size is then "1 << (szx + 4)". 490 5.1. The Block Option 492 When a representation is larger than can be comfortably transferred 493 in a single UDP datagram, the Block option can be used to indicate a 494 block-wise transfer. Block is a 1-, 2- or 3-byte integer, the four 495 least significant bits of which indicate the size and whether the 496 current block-wise transfer is the last block being transferred (M or 497 "more" bit). The value divided by sixteen is the number of the block 498 currently being transferred, starting from zero, i.e., the current 499 transfer is about the "size" bytes starting at "blocknr << (szx + 500 4)". The default value of the Block option is zero, indicating that 501 the current block is the first (block number 0) and only (M bit not 502 set) block of the transfer; however, there is no explicit size 503 implied by this default value. 505 0 506 0 1 2 3 4 5 6 7 507 +-+-+-+-+-+-+-+-+ 508 |blocknr|M| szx | 509 +-+-+-+-+-+-+-+-+ 511 0 1 512 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 513 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 514 | block nr |M| szx | 515 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 517 0 1 2 518 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 519 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 520 | block nr |M| szx | 521 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 523 Figure 8: Block option 525 (Note that the option with the last 4 bits masked out, shifted to the 526 left by the value of szx, gives the byte position of the block. The 527 author is not too sure whether that particularly is a feature.) 529 The block option is used in one of three roles: 531 o In the request for a GET, it gives the block number requested and 532 suggests a block size (block number 0) or echoes the block size of 533 previous blocks received (block numbers other than 0). 535 o In the response for a GET or in the request for a PUT or POST, it 536 describes what block number is contained in the payload, and 537 whether further blocks are part of that body (M bit). If the M 538 bit is set, the size of the payload body in bytes MUST indeed be 539 the power of two given by the block size. All blocks for a 540 transaction MUST use the same block size, except for the last 541 block (M bit not set). 543 o In the response for a PUT or POST, it indicates what block number 544 is being acknowledged. In this case, the M bit is set to indicate 545 that this response does not carry the final response to the 546 request; this can occur when the M bit was set in the request and 547 the server implements PUT/POST atomically (only with the receptin 548 of the last block). 550 In all cases, the block number logically extends the transaction ID, 551 i.e. the same transaction ID can be used for all exchanges for a 552 block-wise transfer. (For GET, and for PUT/POST where atomic 553 semantics are not needed, the requester is free to use different 554 transactions IDs for each block if desired.) 556 When a GET is answered with a response carrying a Block option with 557 the M bit set, the requestor may retrieve additional blocks by 558 sending requests with a Block option giving the block number desired. 559 In such a Block option, the M bit MUST be sent as zero and ignored on 560 reception. 562 To influence the block size used in response to a GET request, the 563 requestor uses the Block option, giving the desired size, a block 564 number of zero and an M bit of zero. A server SHOULD use the block 565 size indicated or a smaller size. Any further block-wise requests 566 for blocks beyond the first one MUST indicate the block size used in 567 the response for the first one. 569 If the Block option is used by the requestor, all GET requests in a 570 single transaction MUST use the same size. The server SHOULD use the 571 block size indicated in the request option, but the requestor MUST 572 take note of the actual block size used in the response; the server 573 MUST ensure that it uses the same block size for all responses in a 574 transaction (except for the last one with the M bit not set). [TBD: 575 decide whether the Block option can only be used in a response if a 576 Block option was in the request. Such a minimal block option could 577 be of length zero, i.e., would occupy just one byte for the type/ 578 length information, but is a bit redundant, so it would be nice to 579 leave this requirement out, but then every GET requestor has the 580 burden of having to cope with receiving Block options.] 582 Block-wise transfers SHOULD be used in conjunction with the Etag 583 option, unless the representation being exchanged is entirely static 584 (not changing over time at all, such as in a schema describing a 585 device). When reassembling the representation from the blocks being 586 exchanged, the reassembler MUST compare Etag options. If the Etag 587 options do not match in a GET transfer, the requestor has the option 588 of attempting to retrieve fresh values for the blocks it retrieved 589 first. To minimize the resulting inefficiency, the server MAY cache 590 the current value of a representation for an ongoing transaction, but 591 there is no requirement for the server to establish any state. The 592 server may offer a TeRI with the initial block to reduce the size of 593 further block-wise GET requests; this TeRI MAY be short-lived and 594 specific to the version of the representation being retrieved (which 595 would in effect freeze the representation of the resource 596 specifically for the purposes of this block-wise transfer). 598 In a PUT or POST transfer, the block option refers to the body in the 599 request, i.e., there is no way to perform a block-wise retrieval of 600 the body of the response. Servers that do need to supply large 601 bodies in response to PUT/POST SHOULD therefore be employing 602 redirects, possibly offering a TeRI. 604 In a PUT or POST transfer that is intended to be implemented in an 605 atomic fashion at the server, the actual creation/replacement takes 606 place at the time a block with the M bit unset is received. If not 607 all previous blocks are available at the server at this time, the 608 transfer fails and error code 4__ (TBD) MUST be returned. The error 609 code 4__ can also be returned at any time by a server that does not 610 currently have the resources to store blocks for a block-wise PUT or 611 POST transfer that it would intend to implement in an atomic fashion. 612 [TBD: a way for a server to derive the equivalent of an Etag for the 613 request body, so that when these do not match in a PUT or POST 614 transfer, the reassembler MUST discard older blocks. For now, the 615 transaction ID will have to suffice.] 617 Proposal: Add a Block option (e.g., number 8) that can be used for 618 block-wise transfers. 620 Benefits: Transfers larger than can be accommodated in constrained- 621 network link-layer packets can be performed in smaller blocks. 623 No hard-to-manage conversation state is created at the adaptation 624 layer or IP layer for fragmentation. 626 The transfer of each block is acknowledged, enabling 627 retransmission if required. 629 Both sides have a say in the block size that actually will be 630 used. 632 6. Option Encoding 634 The option encoding in [I-D.ietf-core-coap] is neither particularly 635 flexible nor particularly efficient. One important, easily 636 overlooked disadvantage of the encoding is the large number of ways 637 in which the same information can be encoded. This unneeded 638 variability causes problems in interoperability and increases both 639 coding and testing efforts required. 641 6.1. A More Efficient Option Encoding 643 The basic idea of the proposed encoding is to reduce the number of 644 ways the same information can be encoded as far as possible (but not 645 further). This both simplifies decoding (e.g., an implementation 646 that only ever uses short URIs never has to implement long options, 647 because these can only be used with long lengths) and 648 interoperability testing (there is only one way to say a specific 649 thing, so there aren't multiple ways that need testing). 651 One of the undesired variations in packets is the ordering of the 652 options. In this draft, we therefore mandate a total ordering of 653 options, ordered by the option number. 655 As an interesting consequence, the option numbers can now be 656 expressed in delta coding, in turn requiring fewer bits to encode the 657 option number. This frees a number of bits for the length, making 658 the likelihood of actually needing the two-byte form of the option 659 header much smaller. 661 To further reduce variation, the length of the value (as always, not 662 including the option header) is now encoded in such a way that there 663 is only one way to express a given length: The short form (one-byte 664 option tag) can express length values from 0 to 14, and the long form 665 is used for values of 15 to 15+255=270, inclusively (Figure 9). 667 0 1 2 3 4 5 6 7 668 +---+---+---+---+---+---+---+---+ 669 | option delta | length | 0..14 670 +---+---+---+---+---+---+---+---+ 672 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 673 | option delta | 1 1 1 1 | length - 15 | 15..270 674 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 676 Figure 9: Option delta/length representation with small range 678 The small option delta of 0..15 in this encoding limits the 679 difference in option value between two adjacent options (or the value 680 of the option number of the first option). While realistic sequences 681 of options rarely will have a problem here, option numbers 14, 28, 682 ... are reserved for no-op options with no body (implementations will 683 automatically ignore these with zero additional code; see Section 6.2 684 why the reserved values are not 15, 30, ...). Note that the 685 resulting delta that reaches the interim nop option may have any 686 number, e.g., for including option 2 and 27 in one message, the 687 sequence would be: 689 o delta = 2 (option 2, body) 691 o delta = 12 (option 14 = no-op, no body) 693 o delta = 13 (option 27, body) 695 In the unlikely case that only option 40 is needed, the sequence 696 would be: 698 o delta = 14 (option 14 = no-op, no body) 700 o delta = 14 (option 28 = no-op, bo body) 702 o delta = 12 (option 40, body) 704 6.2. Critical Options 706 CoAP is designed to enable the definition of additional options by 707 later extensions. Typically, new options are designed in such a way 708 that they can simply be ignored if not understood, i.e. new options 709 are _elective_. However, some new options may be _critical_, i.e., 710 there is no good way to process the message if the option is not 711 understood. (Actually, half of the options currently on the table 712 are critical in nature.) 714 In the option encoding proposed, odd-numbered options indicate a 715 critical option; even-numbered options indicate elective options. 716 (Note that, again, the even/odd distinction is on the option number 717 resulting from the decoding, not the delta value actually embedded in 718 the packet.) 720 Implementing this proposal requires some renumbering of options from 721 [I-D.ietf-core-coap]. 723 6.3. Payload-Length Option 725 Not all transport mappings may provide an unambiguous length of the 726 CoAP message. For UDP, it may also be desirable to pack more than 727 one CoAP message into one UDP payload (aggregation); in that case, 728 for all but the last message there needs to be a way to delimit the 729 payload of that message. 731 We propose a new option, the Payload-Length option. If this option 732 is present, the value of this option is an unsigned integer giving 733 the length of the payload of the message (note that this integer can 734 be zero for a zero-length payload, which can in turn be represented 735 by a zero-length option value). (In the UDP aggregation case, what 736 would have been in the payload of this message after "payload-length" 737 bytes is then actually one or more additional messages.) 739 6.4. Problems with specific options 741 Problem: The Uri option currently does not provide a way to 742 distinguish an "absolute-URI" from an "absolute-path" [RFC3986], 743 as the leading slash is omitted from the latter. (Ticket #12.) 745 Proposal: Split the option into two variants: "Uri-Full" and 746 "Uri-Path". None (= "Uri-Path" with option value ''), one of 747 these, but never both can be present. 749 7. IANA Considerations 751 This draft adds the following option numbers to Table 2 of 752 [I-D.ietf-core-coap]: 754 +------+-----+--------+----------------------------+--------+-------+ 755 | Type | C/E | Name | Data type | Length | Rules | 756 +------+-----+--------+----------------------------+--------+-------+ 757 | 2 | E | TeRI | Duration + Sequence of | 2-n B | | 758 | | | | Bytes | | | 759 | | | | | | | 760 | 7 | E | Accept | Sequence of bytes | 1-n B | | 761 | | | | | | | 762 | 8 | C | Block | Unsigned Integer | 1-3 B | | 763 +------+-----+--------+----------------------------+--------+-------+ 765 With the new option encoding and the proposal for essential options, 766 the total list becomes: 768 +------+-----+----------------+------------------+--------+---------+ 769 | Type | C/E | Name | Data type | Length | Rules | 770 +------+-----+----------------+------------------+--------+---------+ 771 | 0 | E | TeRI | Duration + | 2-n B | | 772 | | | | Sequence of | | | 773 | | | | Bytes | | | 774 | | | | | | | 775 | 1 | C | Uri-Path | String | 1-n B | | 776 | | | | | | | 777 | 2 | E | Accept | Sequence of | 1-n B | | 778 | | | | Bytes | | | 779 | | | | | | | 780 | 3 | C | Uri-Full | String | 1-n B | | 781 | | | | | | | 782 | 4 | E | Max-age | Duration | 1 B | | 783 | | | | | | | 784 | 5 | C | Content-type | Unsigned Integer | 1-2 B | | 785 | | | | | | | 786 | 6 | E | Etag | Sequence of | 1-4 B | | 787 | | | | Bytes | | | 788 | | | | | | | 789 | 8 | E | Date | Unsigned Integer | 4-6 B | (with | 790 | | | | (?) | | body) | 791 | | | | | | | 792 | 13 | C | Block | Unsigned Integer | 1-3 B | | 793 | | | | | | | 794 | 14.. | E | Nop | None | 0 B | | 795 | | | | | | | 796 | 15 | C | Payload-length | Unsigned Integer | 0-2 B | | 797 +------+-----+----------------+------------------+--------+---------+ 799 (The upper limit of "n" indicates that the size is limited only by 800 the options encoding.) Odd option numbers indicate critical options, 801 even option numbers indicate elective options. Option numbers 14, 802 28, 42, ... (any number divisible by 14) are reserved (they are 803 elective and therefore ignored by all implementations). 805 (Subscription-related options are discussed in 806 [I-D.hartke-coap-observe], so the following option from 807 [I-D.ietf-core-coap] is not further discussed here: 809 +-----+-----+-----------------------+----------+--------+-----------+ 810 | Typ | C/E | Name | Data | Length | Rules | 811 | e | | | type | | | 812 +-----+-----+-----------------------+----------+--------+-----------+ 813 | 6 | E | Subscription-lifetime | Duration | 1 B | With | 814 | | | | | | SUBSCRIBE | 815 | | | | | | or its | 816 | | | | | | response | 817 +-----+-----+-----------------------+----------+--------+-----------+ 819 8. Security Considerations 821 TBD. (Weigh the security implications of application layer block- 822 wise transfer against those of adaptation-layer or IP-layer 823 fragmentation. Discuss the implications of TeRIs. Also: Discuss 824 nodes without clocks.) 826 8.1. Amplification Attacks 828 TBD. (This section discusses how CoAP nodes could become implicated 829 in DoS attacks by using the amplifying properties of the protocol, as 830 well as mitigations for this threat.) 832 9. References 834 9.1. Normative References 836 [I-D.hartke-coap-observe] 837 Hartke, K. and C. Bormann, "Observing Resources in CoAP", 838 draft-hartke-coap-observe-00 (work in progress), 839 June 2010. 841 [I-D.ietf-core-coap] 842 Shelby, Z., Frank, B., and D. Sturek, "Constrained 843 Application Protocol (CoAP)", draft-ietf-core-coap-00 844 (work in progress), June 2010. 846 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 847 Requirement Levels", BCP 14, RFC 2119, March 1997. 849 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 850 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 851 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 853 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 854 Resource Identifier (URI): Generic Syntax", STD 66, 855 RFC 3986, January 2005. 857 9.2. Informative References 859 [REST] Fielding, R., "Architectural Styles and the Design of 860 Network-based Software Architectures", 2000. 862 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 863 version 1.3", RFC 1951, May 1996. 865 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 866 Encodings", RFC 4648, October 2006. 868 Authors' Addresses 870 Carsten Bormann 871 Universitaet Bremen TZI 872 Postfach 330440 873 Bremen D-28359 874 Germany 876 Phone: +49-421-218-63921 877 Fax: +49-421-218-7000 878 Email: cabo@tzi.org 880 Klaus Hartke 881 Universitaet Bremen TZI 882 Postfach 330440 883 Bremen D-28359 884 Germany 886 Phone: +49-421-218-63908 887 Fax: +49-421-218-7000 888 Email: hartke@tzi.org