idnits 2.17.1 draft-bormann-coap-misc-19.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 == Line 1303 has weird spacing: '... code mid...' -- The document date (July 16, 2012) is 4295 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 ---------------------------------------------------------------------------- == Missing Reference: 'RFCXXXX' is mentioned on line 863, but not defined -- Looks like a reference, but probably isn't: '0' on line 1662 == Unused Reference: 'CoRE201' is defined on line 929, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-10 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-05 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-20 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-20 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 4 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 17, 2013 July 16, 2012 7 Miscellaneous additions to CoAP 8 draft-bormann-coap-misc-19 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, the 14 Constrained Application Protocol (CoAP). The current version has 15 been resubmitted to keep information about these proposals available; 16 the proposals are not all fleshed out at this point in time. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 17, 2013. 35 Copyright Notice 37 Copyright (c) 2012 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 2. Getting rid of artificial limitations . . . . . . . . . . . . 5 54 2.1. Option Length encoding beyond 270 bytes . . . . . . . . . 5 55 3. Registered Option . . . . . . . . . . . . . . . . . . . . . . 8 56 3.1. A Separate Suboption Number Space . . . . . . . . . . . . 8 57 3.2. Opening Up the Option Number Space . . . . . . . . . . . . 9 58 3.2.1. Long Jump construct . . . . . . . . . . . . . . . . . 10 59 3.2.2. Discussion . . . . . . . . . . . . . . . . . . . . . . 11 60 3.2.3. Example . . . . . . . . . . . . . . . . . . . . . . . 12 61 3.2.4. IANA considerations . . . . . . . . . . . . . . . . . 12 62 4. Patience, Leisure, and Pledge . . . . . . . . . . . . . . . . 13 63 4.1. Patience . . . . . . . . . . . . . . . . . . . . . . . . . 13 64 4.2. Leisure . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 4.3. Pledge . . . . . . . . . . . . . . . . . . . . . . . . . . 14 66 4.4. Option Formats . . . . . . . . . . . . . . . . . . . . . . 14 67 5. Observing Resources in CoAP . . . . . . . . . . . . . . . . . 16 68 6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 69 6.1. Requesting a Tunnel with CONNECT . . . . . . . . . . . . . 19 70 6.2. Using a CONNECT Tunnel . . . . . . . . . . . . . . . . . . 19 71 6.3. Closing down a CONNECT Tunnel . . . . . . . . . . . . . . 20 72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 73 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 74 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 23 75 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 76 10.1. Normative References . . . . . . . . . . . . . . . . . . . 24 77 10.2. Informative References . . . . . . . . . . . . . . . . . . 24 78 Appendix A. The Nursery (Things that still need to ripen a 79 bit) . . . . . . . . . . . . . . . . . . . . . . . . 26 80 A.1. Envelope Options . . . . . . . . . . . . . . . . . . . . . 26 81 A.2. Payload-Length Option . . . . . . . . . . . . . . . . . . 27 82 A.3. URI Authorities with Binary Adresses . . . . . . . . . . . 27 83 A.4. Length-aware number encoding (o256) . . . . . . . . . . . 28 84 A.5. SMS encoding . . . . . . . . . . . . . . . . . . . . . . . 30 85 A.5.1. ASCII-optimized SMS encoding . . . . . . . . . . . . . 31 86 Appendix B. The Cemetery (Things we won't do) . . . . . . . . . . 34 87 B.1. Example envelope option: solving #230 . . . . . . . . . . 34 88 B.2. Example envelope option: proxy-elective options . . . . . 35 89 B.3. Stateful URI compression . . . . . . . . . . . . . . . . . 35 90 B.4. Beyond 270 bytes in a single option . . . . . . . . . . . 36 91 B.5. Beyond 15 options . . . . . . . . . . . . . . . . . . . . 37 92 B.5.1. Implementation considerations . . . . . . . . . . . . 39 93 B.5.2. What should we do now? . . . . . . . . . . . . . . . . 40 94 B.5.3. Alternatives . . . . . . . . . . . . . . . . . . . . . 40 95 B.5.4. Alternative: Going to a delimiter model . . . . . . . 40 96 B.6. Implementing the option delimiter for 15 or more 97 options . . . . . . . . . . . . . . . . . . . . . . . . . 40 99 Appendix C. Experimental Options . . . . . . . . . . . . . . . . 42 100 C.1. Options indicating absolute time . . . . . . . . . . . . . 42 101 C.2. Representing Durations . . . . . . . . . . . . . . . . . . 43 102 C.3. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 44 103 C.4. Pseudo-Floating Point . . . . . . . . . . . . . . . . . . 45 104 C.5. A Duration Type for CoAP . . . . . . . . . . . . . . . . . 46 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 107 1. Introduction 109 The CoRE WG is tasked with standardizing an Application Protocol for 110 Constrained Networks/Nodes, CoAP [I-D.ietf-core-coap]. This protocol 111 is intended to provide RESTful [REST] services not unlike HTTP 112 [RFC2616], while reducing the complexity of implementation as well as 113 the size of packets exchanged in order to make these services useful 114 in a highly constrained network of themselves highly constrained 115 nodes. 117 This objective requires restraint in a number of sometimes 118 conflicting ways: 120 o reducing implementation complexity in order to minimize code size, 122 o reducing message sizes in order to minimize the number of 123 fragments needed for each message (in turn to maximize the 124 probability of delivery of the message), the amount of 125 transmission power needed and the loading of the limited-bandwidth 126 channel, 128 o reducing requirements on the environment such as stable storage, 129 good sources of randomness or user interaction capabilities. 131 This draft attempts to address a number of problems not yet 132 adequately solved in [I-D.ietf-core-coap]. The solutions proposed to 133 these problems are somewhat interrelated and are therefore presented 134 in one draft. 136 The appendix contains the "CoAP cemetery" (possibly later to move 137 into its own draft), documenting roads that the WG decided not to 138 take, in order to spare readers from reinventing them in vain. 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 142 document are to be interpreted as described in [RFC2119]. 144 The term "byte" is used in its now customary sense as a synonym for 145 "octet". 147 2. Getting rid of artificial limitations 149 _Artificial limitations_ are limitations of a protocol or system that 150 are not rooted in limitations of actual capabilities, but in 151 arbitrary design decisions. Proper system design tries to avoid 152 artificial limitations, as these tend to cause complexity in systems 153 that need to work with these limitations. 155 E.g., the original UNIX filesystem had an artificial limitation of 156 the length of a path name component to 14 bytes. This led to a 157 cascade of workarounds in programs that manipulate file names: E.g., 158 systematically replacing a ".el" extension in a filename with a 159 ".elc" for the compiled file might exceed the limit, so all ".el" 160 files were suddenly limited to 13-byte filenames. 162 Note that, today, there still is a limitation in most file system 163 implementations, typically at 255. This just happens to be high 164 enough to rarely be of real-world concern; we will refer to this case 165 as a "painless" artificial limitation. 167 CoAP-08 had two highly recognizable artificial limitations in its 168 protocol encoding 170 o The number of options in a single message is limited to 15 max. 172 o The length of an option is limited to 270 max. 174 It has been argued that the latter limitation causes few problems, 175 just as the 255-byte path name component limitation in filenames 176 today causes few problems. Appendix B.4 provided a design to extend 177 this; as a precaution to future extensions of this kind, the current 178 encoding for length 270 (eight ones in the extension byte) could be 179 marked as reserved today. Since, Matthias Kovatsch has proposed a 180 simpler scheme that seems to gain favor in the WG, see Section 2.1. 182 The former limitation has been solved in CoAP-09. A historical 183 discussion of other approaches for going beyond 15 options is in 184 Appendix B.5. Appendix B.6 discusses implementation. 186 2.1. Option Length encoding beyond 270 bytes 188 For option lengths beyond 270 bytes, we reserve the value 255 of an 189 extension byte to mean "add 255, read another extension byte" 190 Figure 1. While this causes the length of the option header to grow 191 linearly with the size of the option value, only 0.4 % of that size 192 is used. With a focus on short options, this encoding is justified. 194 for 15..269: 195 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 196 | Option Delta | 1 1 1 1 | Length - 15 | 197 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 198 | Option Value ... 199 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 201 for 270..524: 202 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 203 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 204 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 205 | Length - 270 | Option Value ... 206 +---+---+---+---+---+---+---+---+ 207 | 208 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 210 for 525..779: 211 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 212 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 213 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 214 | 1 1 1 1 1 1 1 1 | Length - 525 | 215 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 216 | Option Value ... 217 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 219 for 780..1034: 220 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 221 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 222 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 223 | 1 1 1 1 1 1 1 1 | 1 1 1 1 1 1 1 1 | 224 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 225 | Length - 780 | Option Value ... 226 +---+---+---+---+---+---+---+---+ 227 | 228 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 230 Figure 1: Options beyond 270 bytes 232 Options that are longer than 1034 bytes MUST NOT be sent; an option 233 that has 255 (all one bits) in the field called "Length - 780" MUST 234 be rejected upon reception as an invalid option. 236 In the process, the maximum length of all options that are currently 237 set at 270 should now be set to a carefully chosen value. With the 238 purely encoding-based limit gone, Uri-Proxy should now be restored to 239 be a non-repeatable option. 241 A first proposal for a new set of per-option length restrictions 242 follows: 244 +--------+---------------------+-----+------+--------+--------+ 245 | number | name | min | max | type | repeat | 246 +--------+---------------------+-----+------+--------+--------+ 247 | 1 | content_type | 0 | 2 | uint | - | 248 | | | | | | | 249 | 2 | max_age | 0 | 4 | uint | - | 250 | | | | | | | 251 | 3 | proxy_uri | 1 | 1023 | string | - | 252 | | | | | | | 253 | 4 | etag | 1 | 8 | opaque | yes | 254 | | | | | | | 255 | 5 | uri_host | 1 | 255 | string | - | 256 | | | | | | | 257 | 6 | location_path | 0 | 255 | string | yes | 258 | | | | | | | 259 | 7 | uri_port | 0 | 2 | uint | - | 260 | | | | | | | 261 | 8 | location_query | 0 | 255 | string | yes | 262 | | | | | | | 263 | 9 | uri_path | 0 | 255 | string | yes | 264 | | | | | | | 265 | 10 | observe | 0 | 2 | uint | - | 266 | | | | | | | 267 | 11 | token | 1 | 8 | opaque | - | 268 | | | | | | | 269 | 12 | accept | 0 | 2 | uint | yes | 270 | | | | | | | 271 | 13 | if_match | 0 | 8 | opaque | yes | 272 | | | | | | | 273 | 14 | registered_elective | 1 | 1023 | opaque | yes | 274 | | | | | | | 275 | 15 | uri_query | 1 | 255 | string | yes | 276 | | | | | | | 277 | 17 | block2 | 0 | 3 | uint | - | 278 | | | | | | | 279 | 18 | size | 0 | 4 | uint | - | 280 | | | | | | | 281 | 19 | block1 | 0 | 3 | uint | - | 282 | | | | | | | 283 | 21 | if_none_match | 0 | 0 | empty | - | 284 | | | | | | | 285 | 25 | registered_critical | 1 | 1023 | opaque | yes | 286 +--------+---------------------+-----+------+--------+--------+ 288 (Option 14 with a length of 0 is a fencepost only.) 290 3. Registered Option 292 CoAP's option encoding is highly efficient, but works best with small 293 option numbers that do not require much fenceposting. The CoAP 294 Option Number Registry therefore has a relatively heavyweight 295 registration requirement: "IETF Review" as described in [RFC5226]. 297 However, there is also considerable benefit in a much looser registry 298 policy, enabling a first-come-first-served policy for a relatively 299 large option number space. 301 Here, we discuss two solutions that enable such a registry. One is 302 to define a separate mechanism for registered options, discussed in 303 Section 3.1. Alternatively, we could make it easier to use a larger 304 main option number space, discussed in Section 3.2. 306 3.1. A Separate Suboption Number Space 308 This alternative defines a separate space of suboption numbers, with 309 an expert review [RFC5226] (or even first-come-first-served) 310 registration policy. If expert review is selected for this registry, 311 it would be with a relatively loose policy delegated to the expert. 312 This draft proposes leaving the registered suboption numbers 0-127 to 313 expert review with a policy that mainly focuses on the availability 314 of a specification, and 128-16383 for first-come-first-served where 315 essentially only a name is defined. 317 The "registered" options are used in conjunction with this suboption 318 number registry. They use two normal CoAP option numbers, one for 319 options with elective semantics (Registered-Elective) and one for 320 options with critical semantics (Registered-Critical). The suboption 321 numbers are not separate, i.e. one registered suboption number might 322 have some elective semantics and some other critical semantics (e.g., 323 for the request and the response leg of an exchange). The option 324 value starts with an SDNV [RFC6256] of the registered suboption 325 number. (Note that there is no need for an implementation to 326 understand SDNVs, it can treat the prefixes as opaque. One could 327 consider the SDNVs as a suboption prefix allocation guideline for 328 IANA as opposed to a number encoding.) 330 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 331 |1 0 0 0 0 0 0 1|0 1 1 1 0 0 1 1| value... | 332 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 333 \___SDNV of registered number___/ 335 Figure 2: Example option value for registered option 337 Note that a Registered Option cannot be empty, because there would be 338 no space for the SDNV. Also, the empty option 14 is reserved for 339 fenceposting ([I-D.ietf-core-coap], section 3.2). (Obviously, once a 340 Registered-Elective Option is in use, there is never a need for a 341 fence-post for option number 14.) 343 The Registered-Elective and Registered-Critical Options are 344 repeatable. 346 +-----+----------+---------------------+---------+--------+---------+ 347 | No. | C/E | Name | Format | Length | Default | 348 +-----+----------+---------------------+---------+--------+---------+ 349 | 14 | Elective | Registered-Elective | (see | 1-1023 | (none) | 350 | | | | above) | B | | 351 | | | | | | | 352 | 25 | Critical | Registered-Critical | (see | 1-1023 | (none) | 353 | | | | above) | B | | 354 +-----+----------+---------------------+---------+--------+---------+ 356 This solves CoRE issue #214 [CoRE214]. (How many options we need 357 will depend on the resolution of #241 [CoRE241].) 359 3.2. Opening Up the Option Number Space 361 The disadvantage of the registered-... options is that there is a 362 significant syntactic difference between options making use of this 363 space and the usual standard options. This creates a problem not 364 unlike that decried in [RFC6648]. 366 The alternative discussed in this section reduces the distance by 367 opening up the main Option number space instead. 369 There is still a significant incentive to use low-numbered Options. 370 However, the proposal reduces the penalty for using a high-numbered 371 Option to two or three bytes. More importantly, using a cluster of 372 related high-numbered options only carries a total penalty of two or 373 three bytes. 375 The main reason high-numbered options are expensive to use and thus 376 the total space is relatively limited is that the option delta 377 mechanism only allows increasing the current option number by up to 378 14 per one-byte fencepost. To use, e.g., Option number 1234 together 379 with the usual set of low-numbered Options, one needs to insert 88 380 fence-post bytes. This is prohibitive. 382 Enabling first-come-first-served probably requires easily addressing 383 a 16-bit option number space, with some potential increase later in 384 the lifetime of the protocol (say, 10 to 15 years from now). 386 To enable the use of large option numbers, one needs a way to advance 387 the Option number in bigger steps than possible by the Option Delta. 388 So we propose a new construct, the Long Jump construct, to move the 389 Option number forward. 391 3.2.1. Long Jump construct 393 The following construct can occur in front of any Option: 395 0 1 2 3 4 5 6 7 396 +---+---+---+---+---+---+---+---+ 397 | 1 1 1 1 | 0 0 0 1 | 0xf1 398 +---+---+---+---+---+---+---+---+ 399 | Long Jump Value | (Delta/8)-2 400 +---+---+---+---+---+---+---+---+ 402 0 1 2 3 4 5 6 7 403 +---+---+---+---+---+---+---+---+ 404 | 1 1 1 1 | 0 0 1 0 | 0xf2 405 +---+---+---+---+---+---+---+---+ 406 | Long Jump Value, MSB | 407 +---+---+---+---+---+---+---+---+ (Delta/8)-258 408 | Long Jump Value, LSB | 409 +---+---+---+---+---+---+---+---+ 411 Figure 3: Long Jump Format 413 This construct is not by itself an Option. It can occur in front of 414 any Option to increase the current Option number that then goes into 415 its Option number calculation. The increase is done in multiples of 416 eight. More specifically, the actual addition to the current Option 417 number is computed as follows: 419 Delta = ((Long Jump Value) + N) * 8 421 where N is 2 for the one-byte version and N is 258 for the two-byte 422 version. 424 A Long Jump MUST be followed by an actual Option, i.e., it MUST NOT 425 be followed by another Long Jump or an end-of-options indicator. A 426 message violating this MUST be rejected as malformed. 428 Long Jumps do NOT count as Options in the Option Count field of the 429 header (i.e., they cannot by themselves end the Option sequence). 431 3.2.2. Discussion 433 Adding a mechanism at this late stage creates concerns of backwards 434 compatibility. A message sender never needs to implement long-jumps 435 unless it wants to make use of a high-numbered option. So this 436 mechanism can be added once a high-numbered option is added. A 437 message receiver, though, would more or less unconditionally have to 438 implement the mechanism, leading to unconditional additional 439 complexity. There are good reasons to minimize this, as follows: 441 o The increase in multiples of eight allows looking at an option and 442 finding out whether it is critical or not even if the Long Jump 443 value has just been skipped (as opposed to having been processed 444 fully). (It also allows accessing up to approximately 2048 445 options with a two-byte Long Jump.) This allows a basic 446 implementation that does not implement any high-numbered options 447 to simply ignore long jumps and any elective options behind them, 448 while still properly reacting to critical options. 450 o There is probably a good reason to disallow long-jumps that lead 451 to an option number of 42 and less, enabling simple receivers to 452 do the above simplification. 454 o It might seem obvious to remove the fenceposting mechanism 455 altogether in favor of long jumps. This is not advisable: 456 Fenceposting already has zero implementation effort at the 457 receiver, and the overhead at the sender is very limited (it is 458 just a third kind of jump, at one byte per jump). Beyond 42, 459 senders can ignore the existence of fenceposts if they want 460 (possibly obviating the need for more complex base-14 arithmetic). 462 There is no need for a finer granularity than 8, as the Option 463 construct following can also specify a Delta of 0..14. (A 464 granularity of 16 will require additional fenceposting where an 465 option delta of 15 would happen to be required otherwise, which we 466 have reserved. It can be argued that 16 is still the better choice, 467 as fenceposting is already in the code path.) 469 The Long Jump construct takes 0xf1 and 0xf2 from the space available 470 for initial bytes of Options. (Note that we previously took 0xf0 to 471 indicate end-of-options for OC=15.) 473 Varying N with the length as defined above makes it unambiguous 474 whether a one- or two-byte Long Jump is to be used. Setting N=2 for 475 the one-byte version makes it clear that a Delta of 8 is to be 476 handled the usual way (i.e., by Option Delta itself and/or 477 fenceposting). If the delta is not small and not 7 modulo 8, there 478 is still a choice between using the smaller multiple of 8 and a 479 larger Delta in the actual Option or v.v., this biases the choice 480 towards a larger Long Jump and a smaller following Delta, which is 481 also easier to implement as it reduces the number of choice points. 483 3.2.3. Example 485 The following sequence of bytes would encode a Uri-Path Option of 486 "foo" followed by Options 1357 (value "bar") and 1360 (value "baz"): 488 93 65 6f 6f Option 9 (0 + 9, "foo") 489 f1 a6 Long Jump by 1344 490 43 62 61 72 Option 1357 (9 + 1344 + 4, "bar") 491 33 62 61 7a Option 1360 (1357 + 3, "baz") 493 Figure 4: Example using a Long Jump construct 495 where f1 a6 is the long jump forward by (0xa6+2)*8=1344 option 496 numbers. The total option count (OC) for the CoAP header is 3. Note 497 that even if f1 a6 is skipped, the 1357 (which then appears as an 498 Option number 13) is clearly visible as Critical. 500 3.2.4. IANA considerations 502 With the scheme proposed above, we could have three tiers of Option 503 Numbers: 505 +---------------+-------------------------+ 506 | Option Number | Policy [RFC5226] | 507 +---------------+-------------------------+ 508 | 0..255 | Standards Action | 509 | | | 510 | 256..2047 | Designated Expert | 511 | | | 512 | 2048..65535 | First Come First Served | 513 +---------------+-------------------------+ 515 For the inventor of a new option, this would provide a small 516 incentive to go through the designated expert for some minimal cross- 517 checking in order to be able to use the two-byte long-jump. 519 4. Patience, Leisure, and Pledge 521 A number of options might be useful for controlling the timing of 522 interactions. 524 (This section also addresses core-coap ticket #177.) 526 4.1. Patience 528 A client may have a limited time period in which it can actually make 529 use of the response for a request. Using the Patience option, it can 530 provide an (elective) indication how much time it is willing to wait 531 for the response from the server, giving the server license to ignore 532 or reject the request if it cannot fulfill it in this period. 534 If the server knows early that it cannot fulfill the request in the 535 time requested, it MAY indicate this with a 5.04 "Timeout" response. 536 For non-safe methods (such as PUT, POST, DELETE), the server SHOULD 537 indicate whether it has fulfilled the request by either responding 538 with 5.04 "Timeout" (and not further processing the request) or by 539 processing the request normally. 541 Note that the value of the Patience option should be chosen such that 542 the client will be able to make use of the result even in the 543 presence of the expected network delays for the request and the 544 response. Similarly, when a proxy receives a request with a Patience 545 option and cannot fulfill that request from its cache, it may want to 546 adjust the value of the option before forwarding it to an upstream 547 server. 549 (TBD: The various cases that arise when combining Patience with 550 Observe.) 552 The Patience option is elective. Hence, a client MUST be prepared to 553 receive a normal response even after the chosen Patience period (plus 554 an allowance for network delays) has elapsed. 556 4.2. Leisure 558 Servers generally will compute an internal value that we will call 559 Leisure, which indicates the period of time that will be used for 560 responding to a request. A Patience option, if present, can be used 561 as an upper bound for the Leisure. Leisure may be non-zero for 562 congestion control reasons, in particular for responses to multicast 563 requests. For these, the server should have a group size estimate G, 564 a target rate R (which both should be chosen conservatively) and an 565 estimated response size S; a rough lower bound for Leisure can then 566 be computed as follows: 568 lb_Leisure = S * G / R 570 Figure 5: Computing a lower bound for the Leisure 572 E.g., for a multicast request with link-local scope on an 2.4 GHz 573 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 574 conservatively) set to 100, S to 100 bytes, and the target rate to 8 575 kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10 576 seconds. 578 To avoid response implosion, responses to multicast requests SHOULD 579 be dithered within a Leisure period chosen by the server to fall 580 between these two bounds. 582 Currently, we don't foresee a need to signal a value for Leisure from 583 client to server (beyond the signalling provided by Patience) or from 584 server to client, but an appropriate Option might be added later. 586 4.3. Pledge 588 In a basic observation relationship [I-D.ietf-core-observe], the 589 server makes a pledge to keep the client in the observation 590 relationship for a resource at least until the max-age for the 591 resource is reached. 593 To save the client some effort in re-establishing observation 594 relationships each time max-age is reached, the server MAY want to 595 extend its pledge beyond the end of max-age by signalling in a 596 response/notification an additional time period using the Pledge 597 Option, in parallel to the Observe Option. 599 The Pledge Option MUST NOT be used unless the server can make a 600 reasonable promise not to lose the observation relationship in this 601 time frame. 603 Currently, we don't foresee a need to signal a value for Pledge from 604 client to server, but an appropriate behavior might be added later 605 for this option when sent in a request. 607 4.4. Option Formats 609 +-----+----------+----------+-----------------+--------+---------+ 610 | No. | C/E | Name | Format | Length | Default | 611 +-----+----------+----------+-----------------+--------+---------+ 612 | 22 | Elective | Patience | Duration in mis | 1 B | (none) | 613 | | | | | | | 614 | 24 | Elective | Pledge | Duration in s | 1 B | 0 | 615 +-----+----------+----------+-----------------+--------+---------+ 617 All timing options use the Duration data type (see Appendix C.2), 618 however Patience (and Leisure, if that ever becomes an option) uses a 619 timebase of mibiseconds (mis = 1/1024 s) instead of seconds. (This 620 reduces the range of the Duration from ~ 91 days to 128 minutes.) 622 Implementation note: As there are no strong accuracy requirements on 623 the clocks employed, making use of any existing time base of 624 milliseconds is a valid implementation approach (2.4 % off). 626 None of the options may be repeated. 628 5. Observing Resources in CoAP 630 (Co-Author for this section: Matthias Kovatsch) 632 There are two open issues related to -observe 633 [I-D.ietf-core-observe]: 635 o mixing freshness and observation lifetime, and 637 o non-cacheable resources. 639 To solve the first issue, we think that -observe should be clarified 640 as follows: 642 A server sends at least some notifications as confirmable messages. 643 Each confirmable notification is an opportunity for the server to 644 check if the client is still there. If the client acknowledges the 645 notification, it is assumed to be well and alive and still interested 646 in the resource. If it rejects the message with a reset message or 647 if it doesn't respond, it is assumed not longer to be interested and 648 is removed from the list of observers. So an observation 649 relationship can potentially go on forever, if the client 650 acknowledges each confirmable notification. If the server doesn't 651 send a notification for a while and wants to check if the client is 652 still there, it may send a confirmable notification with the current 653 resource state to check that. 655 So there is no mixing of freshness and lifetime going on. 657 The other issue is a bit less trivial to solve. The problem is that 658 normal CoAP and -observe actually have very different freshness 659 models: 661 Normally, when a client wants to know the current state of a 662 resource, it retrieves a representation, uses it and stores it in its 663 cache. Later, when it wants to know the current state again, it can 664 either use the stored representation provided that it's still fresh, 665 or retrieve a new representation, use it and store it in its cache. 667 If a server knows when the state of the resource will change the next 668 time, it can set the Max-Age of the representation to an accurate 669 time span. So the change of the resource state will coincide with 670 the expiration of the freshness of the representation stored in the 671 client's cache (ignoring network latency). 673 But if the resource changes its state unpredictably at any time, the 674 server can set the Max-Age only to an estimate. If the state then 675 actually changes before the freshness expires, the client wrongly 676 believes it has fresh information. Conversely, if the freshness 677 expires and the client wants to know the current state, the client 678 wrongly believes it has to make a new request although the 679 representation is actually still fresh (this is defused by ETag 680 validation). 682 -observe doesn't have these kinds of problems: the server does not 683 have to predict when the resource will change its state the next 684 time. It just sends a notification when it does. The new 685 representation invalidates the old representation stored in the 686 client's cache. So the client always has a fresh representation that 687 it can use when it wants to know the current resource state without 688 ever having to make a request. An explicit Max-Age is not needed for 689 determining freshness. 691 But -observe has a different set of problems: 693 The first problem is that the resource may change its state more 694 often than there is bandwidth available or the client can handle. 695 Thus, -observe cannot make any guarantee that a client will see every 696 state change. The solution is that -observe guarantees that the 697 client will eventually see the latest state change, and follows a 698 best effort approach to enable the client to see as many state 699 changes as possible. 701 The second problem is that, when a notification doesn't arrive for a 702 while, the client does not know if the resource did not change its 703 state or if the server lost its state and forgot that the client is 704 interested in the resource. We propose the following solution: With 705 each notification that the server sends, it makes a promise to send 706 another notification, and that it will send this next notification at 707 latest after a certain time span. This time span is included with 708 each notification. So when no notification arrives for a while and 709 the time span has not expired yet, the client assumes that the 710 resource did not change its state. If the time span has expired, no 711 notification has arrived and the client wants to know the current 712 state of the resource, it has to make a new request. 714 The third problem is that, when an intermediary is observing a 715 resource and wants to create a response from a representation stored 716 in its cache, it needs to specify a Max-Age. But the intermediary 717 cannot predict when it will receive the next notification, because 718 the next notification can arrive at any time. Unlike the origin 719 server, it also doesn't have the application-specific knowledge that 720 the origin server has. We propose the following solution: With each 721 notification a server sends, it includes a value that an intermediary 722 should use to calculate the Max-Age. 724 To summarize: 726 o A notification doesn't have a Max-Age; it's fresh until the next 727 notification arrives. A notification is the promise for another 728 notification that will arrive at latest after Next-Notification- 729 At-Latest. This value is included with every notification. The 730 promise includes that the server attempts to transmit a 731 notification to the client for the promised time span, even if the 732 client does not seem to respond, e.g., due to a temporary network 733 outage. 735 o A notification also contains another value, called Max-Age-Hint. 736 This value is used by a cache to calculate a Max-Age for the 737 representation if needed. In a cache, the Max-Age-Hint of a 738 representation is counted down like Max-Age. When it reaches 739 zero, however, the representation can be still used to satisfy 740 requests, but is non-cacheable (i.e., Max-Age is 0). The Max-Age- 741 Hint must be less than or equal to Next-Notification-At-Latest. 743 We see two possible ways to encode Next-Notification-At-Latest and 744 Max-Age-Hint in a message: 746 o The first way is to require the values of Next-Notification-At- 747 Latest and Max-Age-Hint to be the same, although they are 748 conceptually unrelated. Then, a single option in the message can 749 be used to hold both values. 751 o The second way is to include two options, one for Next- 752 Notification-At-Latest and one for Max-Age-Hint. Since Next- 753 Notification-At-Latest is less than or equal to Max-Age-Hint, the 754 first option should indicates Max-Age-Hint, and the second option 755 Next-Notification-At-Latest minus Max-Age-Hint with a default 756 value of 0. 758 6. CONNECT 760 [RFC2817] defines the HTTP CONNECT method to establish a TCP tunnel 761 through a proxy so that end-to-end TLS connections can be made 762 through the proxy. Recently, a requirement for similar functionality 763 has been discussed for CoAP. This section defines a straw-man 764 CONNECT method and related methods and response codes for CoAP. 766 (IANA considerations for this section TBD.) 768 6.1. Requesting a Tunnel with CONNECT 770 CONNECT is allocated as a new method code in the "CoAP Method Codes" 771 registry. When a client makes a CONNECT request to an intermediary, 772 the intermediary evaluates the Uri-Host, Uri-Port, and/or the 773 authority part of the Proxy-Uri Options in a way that is defined by 774 the security policy of the intermediary. If the security policy 775 allows the allocation of a tunnel based on these parameters, the 776 method returns an empty payload and a response code of 2.30 Tunnel 777 Established. Other possible response codes include 4.03 Forbidden. 779 It may be the case that the intermediary itself can only reach the 780 requested origin server through another intermediary. In this case, 781 the first intermediary SHOULD make a CONNECT request of that next 782 intermediary, requesting a tunnel to the authority. A proxy MUST NOT 783 respond with any 2.xx status code unless it has either a direct or 784 tunnel connection established to the authority. 786 An origin server which receives a CONNECT request for itself MAY 787 respond with a 2.xx status code to indicate that a tunnel is 788 established to itself. 790 Code 2.30 "Tunnel Established" is allocated as a new response code in 791 the "CoAP Response Codes" registry. 793 6.2. Using a CONNECT Tunnel 795 Any successful (2.xx) response to a CONNECT request indicates that 796 the intermediary has established a tunnel to the requested host and 797 port. The tunnel is bound to the requesting end-point and the Token 798 supplied in the request (as always, the default Token is admissible). 799 The tunnel can be used by the client by making a DATAGRAM request. 801 DATAGRAM is allocated as a new method code in the "CoAP Method Codes" 802 registry. When a client makes a DATAGRAM request to an intermediary, 803 the intermediary looks up the tunnel bound to the client end-point 804 and Token supplied in the DATAGRAM request (no other Options are 805 permitted). If a tunnel is found and the intermediary's security 806 policy permits, the intermediary forwards the payload of the DATAGRAM 807 request as the UDP payload towards the host and port established for 808 the tunnel. No response is defined for this request (note that the 809 request can be given as a CON or NON request; for CON, there will be 810 an ACK on the message layer if the tunnel exists). 812 The security policy on the intermediary may restrict the allowable 813 payloads based on its security policy, possibly considering host and 814 port. An inadmissible payload SHOULD cause a 4.03 Forbidden response 815 with a diagnostic message as payload. 817 The UDP payload of any datagram received from the tunnel and admitted 818 by the security policy is forwarded to the client as the payload of a 819 2.31 "Datagram Received" response. The response does not carry any 820 Option except for Token, which identifies the tunnel towards the 821 client. 823 Code 2.31 "Datagram Received" is allocated as a new response code in 824 the "CoAP Response Codes" registry. 826 An origin server that has established a tunnel to itself processes 827 the CoAP payloads of related DATAGRAM requests as it would process an 828 incoming UDP payload, and forwards what would be outgoing UDP 829 payloads in 2.31 "Datagram Received" responses. 831 6.3. Closing down a CONNECT Tunnel 833 A 2.31 "Datagram Received" response may be replied to with a RST, 834 which closes down the tunnel. Similarly, the Token used in the 835 tunnel may be reused by the client for a different purpose, which 836 also closes down the tunnel. 838 7. IANA Considerations 840 This draft adds option numbers to Table 2 of [I-D.ietf-core-coap]: 842 +--------+---------------------+-----------+ 843 | Number | Name | Reference | 844 +--------+---------------------+-----------+ 845 | 14 | Registered-Elective | [RFCXXXX] | 846 | | | | 847 | 22 | Patience | [RFCXXXX] | 848 | | | | 849 | 24 | Pledge | [RFCXXXX] | 850 | | | | 851 | 25 | Registered-Critical | [RFCXXXX] | 852 +--------+---------------------+-----------+ 854 Table 1: New CoAP Option Numbers 856 This draft adds a suboption registry, initially empty. 858 +------------+-----------------------------+-----------+ 859 | Number | Name | Reference | 860 +------------+-----------------------------+-----------+ 861 | 0..127 | (allocate on export review) | [RFCXXXX] | 862 | | | | 863 | 128..16383 | (allocate fcfs) | [RFCXXXX] | 864 +------------+-----------------------------+-----------+ 866 Table 2: CoAP Suboption Numbers 868 8. Security Considerations 870 TBD. 872 9. Acknowledgements 874 This work was partially funded by the Klaus Tschira Foundation and by 875 Intel Corporation. 877 Of course, much of the content of this draft is the result of 878 discussions with the [I-D.ietf-core-coap] authors. 880 Patience and Leisure were influenced by a mailing list discussion 881 with Esko Dijk, Kepeng Li, and Salvatore Loreto - thanks! 883 10. References 885 10.1. Normative References 887 [I-D.ietf-core-coap] 888 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 889 "Constrained Application Protocol (CoAP)", 890 draft-ietf-core-coap-10 (work in progress), June 2012. 892 [I-D.ietf-core-observe] 893 Hartke, K., "Observing Resources in CoAP", 894 draft-ietf-core-observe-05 (work in progress), March 2012. 896 [I-D.ietf-httpbis-p1-messaging] 897 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 898 1: Message Routing and Syntax"", 899 draft-ietf-httpbis-p1-messaging-20 (work in progress), 900 July 2012. 902 [I-D.ietf-httpbis-p4-conditional] 903 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 904 4: Conditional Requests", 905 draft-ietf-httpbis-p4-conditional-20 (work in progress), 906 July 2012. 908 [I-D.ietf-httpbis-p6-cache] 909 Fielding, R., Lafon, Y., Nottingham, M., and J. Reschke, 910 "HTTP/1.1, part 6: Caching", 911 draft-ietf-httpbis-p6-cache-20 (work in progress), 912 July 2012. 914 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 915 Requirement Levels", BCP 14, RFC 2119, March 1997. 917 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 918 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 919 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 921 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 922 Encodings", RFC 4648, October 2006. 924 [RFC6256] Eddy, W. and E. Davies, "Using Self-Delimiting Numeric 925 Values in Protocols", RFC 6256, May 2011. 927 10.2. Informative References 929 [CoRE201] "Multiple Location options need to be processed as a 930 unit", CoRE ticket #201, 2012, 931 . 933 [CoRE214] "Adopt vendor-defined option into core-coap", CoRE 934 ticket #214, 2012, 935 . 937 [CoRE230] "Multiple Location options need to be processed as a 938 unit", CoRE ticket #230, 2012, 939 . 941 [CoRE241] "Proxy Safe & Cache Key indication for options", CoRE 942 ticket #241, 2012, 943 . 945 [REST] Fielding, R., "Architectural Styles and the Design of 946 Network-based Software Architectures", 2000. 948 [RFC1924] Elz, R., "A Compact Representation of IPv6 Addresses", 949 RFC 1924, April 1996. 951 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 952 HTTP/1.1", RFC 2817, May 2000. 954 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 955 Interchange", RFC 5198, March 2008. 957 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 958 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 959 May 2008. 961 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 962 "Deprecating the "X-" Prefix and Similar Constructs in 963 Application Protocols", BCP 178, RFC 6648, June 2012. 965 Appendix A. The Nursery (Things that still need to ripen a bit) 967 A.1. Envelope Options 969 As of [I-D.ietf-core-coap], options can take one of four types, two 970 of which are mostly identical: 972 o uint: A non-negative integer which is represented in network byte 973 order using a variable number of bytes (see [I-D.ietf-core-coap] 974 Appendix A); 976 o string: a sequence of bytes that is nominally a Net-Unicode string 977 [RFC5198]; 979 o opaque: a sequence of bytes. 981 o empty (not explicitly identified as a fourth type in 982 [I-D.ietf-core-coap]). 984 It turns out some options would benefit from some internal structure. 985 Also, it may be a good idea to be able to bundle multiple options 986 into one, in order to ensure consistency for a set of elective 987 options that need to be processed all or nothing (i.e., the option 988 becomes critical as soon as another option out of the set is 989 processed, too). 991 In this section, we introduce a fifth CoAP option type: Envelope 992 options. 994 An envelope option is a sequence of bytes that looks and is 995 interpreted exactly like a CoAP sequence of options. Instead of an 996 option count or an end-of-option marker, the sequence of options is 997 terminated by the end of the envelope option. 999 The nested options (options inside the envelope option) may come from 1000 the same number space as the top-level CoAP options, or the envelope 1001 option may define its own number space - this choice needs to be 1002 defined for each envelope option. 1004 If the top-level number space is used, the envelope option typically 1005 will restrict the set of options that actually can be used in the 1006 envelope. In particular, it is unlikely that an envelope option will 1007 allow itself inside the envelope (this would be a recursive option). 1009 Envelope options are a general, but simple mechanism. Some of its 1010 potential uses are illustrated by two examples in the cemetery: 1011 Appendix B.1 and Appendix B.2. (Each of these examples has its own 1012 merits and demerits, which led us to decide not to pursue either of 1013 them right now, but this should be discussed separately from the 1014 concept of Envelope options employed in the examples.) 1016 A.2. Payload-Length Option 1018 Not all transport mappings may provide an unambiguous length of the 1019 CoAP message. For UDP, it may also be desirable to pack more than 1020 one CoAP message into one UDP payload (aggregation); in that case, 1021 for all but the last message there needs to be a way to delimit the 1022 payload of that message. 1024 This can be solved using a new option, the Payload-Length option. If 1025 this option is present, the value of this option is an unsigned 1026 integer giving the length of the payload of the message (note that 1027 this integer can be zero for a zero-length payload, which can in turn 1028 be represented by a zero-length option value). (In the UDP 1029 aggregation case, what would have been in the payload of this message 1030 after "payload-length" bytes is then actually one or more additional 1031 messages.) 1033 A.3. URI Authorities with Binary Adresses 1035 One problem with the way URI authorities are represented in the URI 1036 syntax is that the authority part can be very bulky if it encodes an 1037 IPv6 address in ASCII. 1039 Proposal: Provide an option "Uri-Authority-Binary" that can be an 1040 even number of bytes between 2 and 18 except 12 or 14. 1042 o If the number of bytes is 2, the destination IP address of the 1043 packet transporting the CoAP message is implied. 1045 o If the number of bytes is 4 or 6, the first four bytes of the 1046 option value are an IPv4 address in binary. 1048 o If the number of bytes is 8 or 10, the first eight bytes are the 1049 lower 64 bits of an IPv6 address; the upper eight bytes are 1050 implied from the destination address of the packet transporting 1051 the CoAP message. 1053 o If the number of bytes is 16 or 18, the first 16 bytes are an IPv6 1054 address. 1056 o If two more bytes remain, this is a port number (as always in 1057 network byte order). 1059 The resulting authority is (conceptually translated into ASCII and) 1060 used in place of an Uri-Authority option, or inserted into a Proxy- 1061 Uri. Examples: 1063 +-------------+------------------+---------+------------------------+ 1064 | Proxy-Uri | Uri-Authority-Bi | Uri-Pat | URI | 1065 | | nary | h | | 1066 +-------------+------------------+---------+------------------------+ 1067 | (none) | (none) | (none) | "/" | 1068 | | | | | 1069 | (none) | (none) | 'temp' | "/temp" | 1070 | | | | | 1071 | (none) | 2 bytes: 61616 | 'temp' | "coap://[DA]:61616/tem | 1072 | | | | p" | 1073 | | | | | 1074 | (none) | 16 bytes: | temp | "coap://[2000::1]/temp | 1075 | | 2000::1 | | " | 1076 | | | | | 1077 | 'http://' | 10 bytes: | (none) | "http://[DA::123:45]:6 | 1078 | | ::123:45 + 616 | | 16" | 1079 | | | | | 1080 | 'http:///te | 18 bytes: | (none) | "http://[2000::1]:616/ | 1081 | mp' | 2000::1 + 616 | | temp" | 1082 +-------------+------------------+---------+------------------------+ 1084 A.4. Length-aware number encoding (o256) 1086 The number encoding defined in Appendix A of [I-D.ietf-core-coap] has 1087 one significant flaw: Every number has an infinite number of 1088 representations, which can be derived by adding leading zero bytes. 1089 This runs against the principle of minimizing unnecessary choice. 1090 The resulting uncertainty in encoding ultimately leads to unnecessary 1091 interoperability failures. (It also wastes a small fraction of the 1092 encoding space, i.e., it wastes bytes.) 1094 We could solve the first, but not the second, by outlawing leading 1095 zeroes, but then we have to cope with error cases caused by illegal 1096 values, another source of interoperability problems. 1098 The number encoding "o256" defined in this section avoids this flaw. 1099 The suggestion is not to replace CoAP's "uint" encoding wholesale 1100 (CoAP is already too widely implemented for such a change), but to 1101 consider this format for new options. 1103 The basic requirements for such an encoding are: 1105 o numbers are encoded as a sequence of zero or more bytes 1107 o each number has exactly one encoding 1108 o for a < b, encoding-size(a) <= encoding-size(b) -- i.e., with 1109 larger numbers, the encoding only gets larger, never smaller 1110 again. 1112 o within each encoding size (0 bytes, 1 byte, etc.), lexicographical 1113 ordering of the bytes is the same as numeric ordering 1115 Obviously, there is only one encoding that satisfies all these 1116 requirements. As illustrated by Figure 6, this is unambiguously 1117 derived by 1119 1. enumerating all possible byte sequences, ordered by length and 1120 within the same length in lexicographic ordering, and, 1122 2. assigning sequential cardinals. 1124 0x'' -> 0 1125 0x'00' -> 1 1126 0x'01' -> 2 1127 0x'02' -> 3 1128 ... 1129 0x'fe' -> 255 1130 0x'ff' -> 256 1131 0x'0000' -> 257 1132 0x'0001' -> 258 1133 ... 1134 0x'fefd' -> 65534 1135 0x'fefe' -> 65535 1136 0x'feff' -> 65536 1137 ... 1138 0x'ffff' -> 65792 1139 0x'000000' -> 65793 1140 0x'000001' -> 65794 1142 Figure 6: Enumerating byte sequences by length and then lexicographic 1143 order 1145 This results in an exceedingly simple algorithm: each byte is 1146 interpreted in the base-256 place-value system, but stands for a 1147 number between 1 and 256 instead of 0 to 255. We therefore call this 1148 encoding "o256" (one-to-256). 0 is always encoded in zero bytes; 1 to 1149 256 is one byte, 257 (0x101) to 65792 (0x10100) is two bytes, 65793 1150 (0x10101) to 16843008 (0x1010100) is three bytes, etc. 1152 To further illustrate the algorithmic simplicity, pseudocode for 1153 encoding and decoding is given in Figure 7 and Figure 8, respectively 1154 (in the encoder, "prepend" stands for adding a byte at the _leading_ 1155 edge, the requirement for which is a result of the network byte 1156 order). Note that this differs only in a single subtraction/addition 1157 (resp.) of one from the canonical algorithm for Appendix A uints. 1159 while num > 0 1160 num -= 1 1161 prepend(num & 0xFF) 1162 num >>= 8 1163 end 1165 Figure 7: o256 encoder (pseudocode) 1167 num = 0 1168 each_byte do |b| 1169 num <<= 8 1170 num += b + 1 1171 end 1173 Figure 8: o256 decoder (pseudocode) 1175 On a more philosophical note, it can be observed that o256 solves the 1176 inverse problem of Self-Delimiting Numeric Values (SDNV) [RFC6256]: 1177 SDNV encodes variable-length numbers together with their length 1178 (allowing decoding without knowing their length in advance, deriving 1179 delimiting information from the number encoding). o256 encodes 1180 variable-length numbers when there is a way to separately convey the 1181 length (as in CoAP options), encoding (and later deriving) a small 1182 part of the numeric value into/from that size information. 1184 A.5. SMS encoding 1186 For use in SMS applications, CoAP messages can be transferred using 1187 SMS binary mode. However, there is operational experience showing 1188 that some environments cannot successfully send a binary mode SMS. 1190 For transferring SMS in character mode (7-bit characters), base64- 1191 encoding [RFC4648] is an obvious choice. 3 bytes of message (24 bits) 1192 turn into 4 characters, which cosume 28 bits. The overall overhead 1193 is approximately 17 %; the maximum message size is 120 bytes (160 SMS 1194 characters). 1196 If a more compact encoding is desired, base85 encoding can be 1197 employed (however, probably not the version defined in [RFC1924] -- 1198 instead, the version used in tools such as btoa and PDF should be 1199 chosen). However, this requires division operations. Also, the 1200 base85 character set includes several characters that cannot be 1201 transferred in a single 7-bit unit in SMS and/or are known to cause 1202 operational problems. A modified base85 character set can be defined 1203 to solve the latter problem. 4 bytes of message (32 bits) turn into 5 1204 characters, which consume 35 bits. The overall overhead is 1205 approximately 9.3 %; the resulting maximum message size is 128 bytes 1206 (160 SMS characters). 1208 Base64 and base85 do not make use of the fact that much CoAP data 1209 will be ASCII-based. Therefore, we define the following experimental 1210 SMS encoding. 1212 A.5.1. ASCII-optimized SMS encoding 1214 Not all 128 theoretically possible SMS characters are operationally 1215 free of problems. We therefore define: 1217 Shunned code characters: @ sign, as it maps to 0x00 1219 LF and CR signs (0x0A, 0x0D) 1221 uppercase C cedilla (0x09), as it is often mistranslated in 1222 gateways 1224 ESC (0x1B), as it is used in certain character combinations only 1226 Some ASCII characters cannot be transferred in the base SMS character 1227 set, as their code positions are taken by non-ASCII characters. 1228 These are simply encoded with their ASCII code positions, e.g., an 1229 underscore becomes a section mark (even though underscore has a 1230 different code position in the SMS character set). 1232 Equivalently translated input bytes: $, @, [, \, ], ^, _, `, {, |, 1233 }, ~, DEL 1235 In other words, bytes 0x20 to 0x7F are encoded into the same code 1236 positions in the 7-bit character set. 1238 Out of the remaining code characters, the following SMS characters 1239 are available for encoding: 1241 Non-equivalently translated (NET) code characters: 0x01 to 0x08, (8 1242 characters) 1244 0x0B, 0x0C, (2 characters) 1246 0x0E to 0x1A, (13 characters) 1247 0x1C to 0x1F, (4 characters) 1249 Of the 27 NET code characters, 18 are taken as prefix characters (see 1250 below), and 8 are defined as directly translated characters: 1252 Directly translated bytes: Equivalently translated input bytes are 1253 represented as themselves 1255 0x00 to 0x07 are represented as 0x01 to 0x08 1257 This leaves 0x08 to 0x1F and 0x80 to 0xFF. Of these, the bytes 0x80 1258 to 0x87 and 0xA0 to 0xFF are represented as the bytes 0x00 to 0x07 1259 (represented by characters 0x01 to 0x08) and 0x20 to 0x7F, with a 1260 prefix of 1 (see below). The characters 0x08 to 0x1F are represented 1261 as the characters 0x28 to 0x3F with a prefix of 2 (see below). The 1262 characters 0x88 to 0x9F are represented as the characters 0x48 to 1263 0x5F with a prefix of 2 (see below). (Characters 0x01 to 0x08, 0x20 1264 to 0x27, 0x40 to 0x47, and 0x60 to 0x7f with a prefix of 2 are 1265 reserved for future extensions, which could be used for some 1266 backreferencing or run-length compression.) 1268 Bytes that do not need a prefix (directly translated bytes) are sent 1269 as is. Any byte that does need a prefix (i.e., 1 or 2) is preceded 1270 by a prefix character, which provides a prefix for this and the 1271 following two bytes as follows: 1273 +------+-----+---+------+-----+ 1274 | 0x0B | 100 | | 0x15 | 200 | 1275 +------+-----+---+------+-----+ 1276 | 0x0C | 101 | | 0x16 | 201 | 1277 | | | | | | 1278 | 0x0E | 102 | | 0x17 | 202 | 1279 | | | | | | 1280 | 0x0F | 110 | | 0x18 | 210 | 1281 | | | | | | 1282 | 0x10 | 111 | | 0x19 | 211 | 1283 | | | | | | 1284 | 0x11 | 112 | | 0x1A | 212 | 1285 | | | | | | 1286 | 0x12 | 120 | | 0x1C | 220 | 1287 | | | | | | 1288 | 0x13 | 121 | | 0x1D | 221 | 1289 | | | | | | 1290 | 0x14 | 122 | | 0x1E | 222 | 1291 +------+-----+---+------+-----+ 1293 (This leaves one non-shunned character, 0x1F, for future extension.) 1294 The coding overhead of this encoding for random bytes is similar to 1295 Base85, without the need for a division/multiplication. For bytes 1296 that are mostly ASCII characters, the overhead can easily become 1297 negative. (Conversely, for bytes that are more likely to be non- 1298 ASCII than in a random sequence of bytes, the overhead becomes 1299 greater.) 1301 So, for instance, for the CoAP message in Figure 9: 1303 ver tt code mid 1304 1 ack 2.05 17033 1305 content_type 40 1306 token sometok 1307 3c 2f 3e 3b 74 69 74 6c 65 3d 22 47 65 6e 65 72 |;title="Gener| 1308 61 6c 20 49 6e 66 6f 22 3b 63 74 3d 30 2c 3c 2f |al Info";ct=0,;if="clock"| 1310 3b 72 74 3d 22 54 69 63 6b 73 22 3b 74 69 74 6c |;rt="Ticks";titl| 1311 65 3d 22 49 6e 74 65 72 6e 61 6c 20 43 6c 6f 63 |e="Internal Cloc| 1312 6b 22 3b 63 74 3d 30 2c 3c 2f 61 73 79 6e 63 3e |k";ct=0,| 1313 3b 63 74 3d 30 |;ct=0 | 1315 Figure 9: CoAP response message as captured and decoded 1317 The 116 byte unencoded message is shown as ASCII characters in 1318 Figure 10 (\xDD stands for the byte with the hex digits DD): 1320 bEB\x89\x11(\xA7sometok;title="General Info";ct=0, 1321 ;if="clock";rt="Ticks";title="Internal Clock";ct=0,;ct=0 1323 Figure 10: CoAP response message shown as unencoded characters 1325 The equivalent SMS encoding is shown as equivalent-coded SMS 1326 characters in Figure 11 (7 bits per character, \x12 is a 220 prefix 1327 and \x0B is a 100 prefix, the rest is shown in equivalent encoding), 1328 adding two characters of prefix overhead, for a total length of 118 1329 7-bit characters or 104 (103.25 plus padding) bytes: 1331 bEB\x12I1(\x0B'sometok;title="General Info";ct=0, 1332 ;if="clock";rt="Ticks";title="Internal Clock";ct=0,;ct=0 1334 Figure 11: CoAP response message shown as SMS-encoded characters 1336 Appendix B. The Cemetery (Things we won't do) 1338 This annex documents roads that the WG decided not to take, in order 1339 to spare readers from reinventing them in vain. 1341 B.1. Example envelope option: solving #230 1343 Ticket #230 [CoRE230] points out a design flaw of 1344 [I-D.ietf-core-coap]: When we split the elective Location option of 1345 draft -01 into multiple elective options, we made it possible that an 1346 implementation might process some of these and ignore others, leading 1347 to an incorrect interpretation of the Location expressed by the 1348 server. 1350 There are several more or less savory solutions to #230. 1352 Each of the elective options that together make up the Location could 1353 be defined in such a way that it makes a requirement on the 1354 processing of the related option (essentially revoking their elective 1355 status once the option under consideration is actually processed). 1356 This falls flat as soon as another option is defined that would also 1357 become part of the Location: existing implementations would not know 1358 that the new option is also part of the cluster that is re- 1359 interpreted as critical. The potential future addition of Location- 1360 Host and Location-Port makes this a valid consideration. 1362 A better solution would be to define an elective Envelope Option 1363 called Location. Within a Location Option, the following top-level 1364 options might be allowed (now or in the future): 1366 o Uri-Host 1368 o Uri-Port 1370 o Uri-Path 1372 o Uri-Query 1374 This would unify the code for interpreting the top-level request 1375 options that indicate the request URI with the code that interprets 1376 the Location URI. 1378 The four options listed are all critical, while the envelope is 1379 elective. This gives exactly the desired semantics: If the envelope 1380 is processed at all (which is elective), the nested options are 1381 critical and all need to be processed. 1383 B.2. Example envelope option: proxy-elective options 1385 Another potential application of envelope options is motivated by the 1386 observation that new critical options might not be implemented by all 1387 proxies on the CoAP path to an origin server. So that this does not 1388 become an obstacle to introducing new critical options that are of 1389 interest only to client and origin server, the client might want to 1390 mark some critical options proxy-elective, i.e. elective for a proxy 1391 but still critical for the origin server. 1393 One way to do this would be an Envelope option, the Proxy-Elective 1394 Option. A client might bundle a number of critical options into a 1395 critical Proxy-Elective Option. A proxy that processes the message 1396 is obliged to process the envelope (or reject the message), where 1397 processing means passing on the nested options towards the origin 1398 server (preferably again within a Proxy-Elective option). It can 1399 pass on the nested options, even ones unknown to the proxy, knowing 1400 that the client is happy with proxies not processing all of them. 1402 (The assumption here is that the Proxy-Elective option becomes part 1403 of the base standard, so all but the most basic proxies would know 1404 how to handle it.) 1406 B.3. Stateful URI compression 1408 Is the approximately 25 % average saving achievable with Huffman- 1409 based URI compression schemes worth the complexity? Probably not, 1410 because much higher average savings can be achieved by introducing 1411 state. 1413 Henning Schulzrinne has proposed for a server to be able to supply a 1414 shortened URI once a resource has been requested using the full- 1415 length URI. Let's call such a shortened referent a _Temporary 1416 Resource Identifier_, _TeRI_ for short. This could be expressed by a 1417 response option as shown in Figure 12. 1419 0 1420 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 1421 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1422 | duration | TeRI... 1423 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1425 Figure 12: Option for offering a TeRI in a response 1427 The TeRI offer option indicates that the server promises to offer 1428 this resources under the TeRI given for at least the time given as 1429 the duration. Another TeRI offer can be made later to extend the 1430 duration. 1432 Once a TeRI for a URI is known (and still within its lifetime), the 1433 client can supply a TeRI instead of a URI in its requests. The same 1434 option format as an offer could be used to allow the client to 1435 indicate how long it believes the TeRI will still be valid (so that 1436 the server can decide when to update the lifetime duration). TeRIs 1437 in requests could be distinguished from URIs e.g. by using a 1438 different option number. 1440 Proposal: Add a TeRI option that can be used in CoAP requests and 1441 responses. 1443 Add a way to indicate a TeRI and its duration in a link-value. 1445 Do not add any form of stateless URI encoding. 1447 Benefits: Much higher reduction of message size than any stateless 1448 URI encoding could achieve. 1450 As the use of TeRIs is entirely optional, minimal complexity nodes 1451 can get by without implementing them. 1453 Drawbacks: Adds considerable state and complexity to the protocol. 1455 It turns out that real CoAP URIs are short enough that TeRIs are 1456 not needed. 1458 (Discuss the security implications of TeRIs.) 1460 B.4. Beyond 270 bytes in a single option 1462 The authors would argue that 270 as the maximum length of an option 1463 is already beyond the "painless" threshold. 1465 If that is not the consensus of the WG, the scheme can easily be 1466 extended as in Figure 13: 1468 for 15..269: 1469 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1470 | Option Delta | 1 1 1 1 | Length - 15 | 1471 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1472 | Option Value ... 1473 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1475 for 270..65805: 1476 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1477 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 1478 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1479 | Length - 270 (in network byte order) | 1480 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1481 | Option Value ... 1482 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1484 Figure 13: Ridiculously Long Option Header 1486 The infinite number of obvious variations on this scheme are left as 1487 an exercise to the reader. 1489 Again, as a precaution to future extensions, the current encoding for 1490 length 270 (eight ones in the extension byte) could be marked as 1491 reserved today. 1493 B.5. Beyond 15 options 1495 (This section keeps discussion that is no longer needed as we have 1496 agreed to do what is documented in Appendix B.6). 1498 The limit of 15 options is motivated by the fixed four-bit field "OC" 1499 that is used for indicating the number of options in the fixed-length 1500 CoAP header (Figure 14). 1502 0 1 2 3 1503 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1504 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1505 |Ver| T | OC | Code | Message ID | 1506 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1507 | Options (if any) ... 1508 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1509 | Payload (if any) ... 1510 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1512 Figure 14: Four-byte fixed header in a CoAP Message 1514 Note that there is another fixed four-bit field in CoAP: the option 1515 length (Figure 15 - note that this figure is not to the same scale as 1516 the previous figure): 1518 0 1 2 3 4 5 6 7 1519 +---+---+---+---+---+---+---+---+ 1520 | Option Delta | Length | for 0..14 1521 +---+---+---+---+---+---+---+---+ 1522 | Option Value ... 1523 +---+---+---+---+---+---+---+---+ 1525 Figure 15: Short Option Header 1527 Since 15 is inacceptable for a maximum option length, the all-ones 1528 value (15) was taken out of the set of allowable values for the short 1529 header, and a long header was introduced that allows the insertion of 1530 an extension byte (Figure 16): 1532 for 15..270: 1533 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1534 | Option Delta | 1 1 1 1 | Length - 15 | 1535 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1536 | Option Value ... 1537 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1539 Figure 16: Long Option Header 1541 We might want to use the same technique for the CoAP header as well. 1542 There are two obvious places where the extension byte could be 1543 placed: 1545 1. right after the byte carrying the OC field, so the structure is 1546 the same as for the option header; 1548 2. right after the fixed-size CoAP header. 1550 Both solutions lose the fixed-size-ness of the CoAP header. 1552 Solution 1 has the disadvantage that the CoAP header is also changing 1553 in structure: The extension byte is wedged between the first and the 1554 second byte of the CoAP header. This is unfortunate, as the number 1555 of options only comes into play when the option processing begins, so 1556 it is more natural to use solution 2 (Figure 17): 1558 0 1 2 3 1559 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1560 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1561 |Ver| T | 15 | Code | Message ID | 1562 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1563 | OC - 15 | Options ... 1564 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1565 | Payload (if any) ... 1566 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1568 Figure 17: Extended header for CoAP Messages with 15+ options 1570 This would allow for up to 270 options in a CoAP message, which is 1571 very likely way beyond the "painless" threshold. 1573 B.5.1. Implementation considerations 1575 For a message decoder, this extension creates relatively little pain, 1576 as the number of options only becomes interesting when the encoding 1577 turns to the options part of the message, which is then simply lead 1578 in by the extension byte if the four-bit field is 15. 1580 For a message encoder, this extension is not so rosy. If the encoder 1581 is constructing the message serially, it may not know in advance 1582 whether the number of options will exceed 14. None of the following 1583 implementation strategies is particularly savory, but all of them do 1584 work: 1586 1. Encode the options serially under the assumption that the number 1587 of options will be 14 or less. When the 15th option needs to be 1588 encoded, abort the option encoding, and restart it from scratch 1589 one byte further to the left. 1591 2. Similar to 1, except that the bytes already encoded are all moved 1592 one byte to right, the extension byte is inserted, and the option 1593 encoding process is continued. 1595 3. The encoder always leaves space for the extension byte (at least 1596 if it can't prove the number will be less thatn 14). If the 1597 extension byte is not needed, an Option 0 with length 0 is 1598 encoded instead (i.e., one byte is wasted - this option is 1599 elective and will be ignored by the receiver). 1601 As a minimum, to enable strategy 3, the option 0 should be reserved 1602 at least for the case of length=0. 1604 B.5.2. What should we do now? 1606 As a minimum proposal for the next version of CoAP, the value 15 for 1607 OC should be marked as reserved today. 1609 B.5.3. Alternatives 1611 One alternative that has been discussed previously is to have an 1612 "Options" Option, which allows the carriage of multiple options in 1613 the belly of a single one. This could also be used to carry more 1614 than 15 options. However: 1616 o The conditional introduction of an Options option has 1617 implementation considerations that are likely to be more severe 1618 than the ones listed above; 1620 o since 270 bytes may not be enough for the encoding of _all_ 1621 options, the "Options" option would need to be repeatable. This 1622 creates many different ways to encode the same message, leading to 1623 combinatorial explosion in test cases for ensuring 1624 interoperability. 1626 B.5.4. Alternative: Going to a delimiter model 1628 Another alternative is to spend the additional byte not as an 1629 extended count, but as an option terminator. 1631 B.6. Implementing the option delimiter for 15 or more options 1633 Implementation note: As can be seen from the proof of concept code 1634 in Figure 18, the actual implementation cost for a decoder is 1635 around 4 lines of code (or about 8-10 machine code instructions). 1637 while numopt > 0 1638 nextbyte = ... get next byte 1640 if numopt == 15 # new 1641 break if nextbyte == 0xF0 # new 1642 else # new 1643 numopt -= 1 1644 end # new 1646 ... decode the delta and length from nextbyte and handle them 1647 end 1649 Figure 18: Implementing the Option Terminator 1651 Similarly, creating the option terminator needs about four more lines 1652 (not marked "old" in the C code in Figure 19). 1654 b0 = 0x40 + (tt << 4); /* old */ 1655 buffer[0] = b0 + 15; /* guess first byte */ 1657 .... encode options .... /* old */ 1659 if (option_count >= 15 || first_fragment_already_shipped) 1660 buffer[pos++] = 0xF0; /* use delimiter */ 1661 else /* save a byte: */ 1662 buffer[0] = b0 + option_count; /* old: backpatch */ 1664 Figure 19: Creating the Option Terminator 1666 Appendix C. Experimental Options 1668 This annex documents proposals that need significant additional 1669 discussion before they can become part of (or go back to) the main 1670 CoAP specification. They are not dead, but might die if there turns 1671 out to be no good way to solve the problem. 1673 C.1. Options indicating absolute time 1675 HTTP has a number of headers that may indicate absolute time: 1677 o "Date", defined in Section 14.18 in [RFC2616] (Section 9.3 in 1678 [I-D.ietf-httpbis-p1-messaging]), giving the absolute time a 1679 response was generated; 1681 o "Last-Modified", defined in Section 14.29 in [RFC2616], (Section 1682 6.6 in [I-D.ietf-httpbis-p4-conditional], giving the absolute time 1683 of when the origin server believes the resource representation was 1684 last modified; 1686 o "If-Modified-Since", defined in Section 14.25 in [RFC2616], 1687 "If-Unmodified-Since", defined in Section 14.28 in [RFC2616], and 1688 "If-Range", defined in Section 14.27 in [RFC2616] can be used to 1689 supply absolute time to gate a conditional request; 1691 o "Expires", defined in Section 14.21 in [RFC2616] (Section 3.3 in 1692 [I-D.ietf-httpbis-p6-cache]), giving the absolute time after which 1693 a response is considered stale. 1695 o The more obscure headers "Retry-After", defined in Section 14.37 1696 in [RFC2616], and "Warning", defined in section 14.46 in 1697 [RFC2616], also may employ absolute time. 1699 [I-D.ietf-core-coap] defines a single "Date" option, which however 1700 "indicates the creation time and date of a given resource 1701 representation", i.e., is closer to a "Last-Modified" HTTP header. 1702 HTTP's caching rules [I-D.ietf-httpbis-p6-cache] make use of both 1703 "Date" and "Last-Modified", combined with "Expires". The specific 1704 semantics required for CoAP needs further consideration. 1706 In addition to the definition of the semantics, an encoding for 1707 absolute times needs to be specified. 1709 In UNIX-related systems, it is customary to indicate absolute time as 1710 an integer number of seconds, after midnight UTC, January 1, 1970. 1711 Unless negative numbers are employed, this time format cannot 1712 represent time values prior to January 1, 1970, which probably is not 1713 required for the uses ob absolute time in CoAP. 1715 If a 32-bit integer is used and allowance is made for a sign-bit in a 1716 local implementation, the latest UTC time value that can be 1717 represented by the resulting 31 bit integer value is 03:14:07 on 1718 January 19, 2038. If the 32-bit integer is used as an unsigned 1719 value, the last date is 2106-02-07, 06:28:15. 1721 The reach can be extended by: - moving the epoch forward, e.g. by 40 1722 years (= 1262304000 seconds) to 2010-01-01. This makes it impossible 1723 to represent Last-Modified times in that past (such as could be 1724 gatewayed in from HTTP). - extending the number of bits, e.g. by one 1725 more byte, either always or as one of two formats, keeping the 32-bit 1726 variant as well. 1728 Also, the resolution can be extended by expressing time in 1729 milliseconds etc., requiring even more bits (e.g., a 48-bit unsigned 1730 integer of milliseconds would last well after year 9999.) 1732 For experiments, an experimental "Date" option is defined with the 1733 semantics of HTTP's "Last-Modified". It can carry an unsigned 1734 integer of 32, 40, or 48 bits; 32- and 40-bit integers indicate the 1735 absolute time in seconds since 1970-01-01 00:00 UTC, while 48-bit 1736 integers indicate the absolute time in milliseconds since 1970-01-01 1737 00:00 UTC. 1739 However, that option is not really that useful until there is a 1740 "If-Modified-Since" option as well. 1742 (Also: Discuss nodes without clocks.) 1744 C.2. Representing Durations 1746 Various message types used in CoAP need the representation of 1747 *durations*, i.e. of the length of a timespan. In SI units, these 1748 are measured in seconds. CoAP durations represent integer numbers of 1749 seconds, but instead of representing these numbers as integers, a 1750 more compact single-byte pseudo-floating-point (pseudo-FP) 1751 representation is used (Figure 20). 1753 0 1 2 3 4 5 6 7 1754 +---+---+---+---+---+---+---+---+ 1755 | 0... value | 1756 +---+---+---+---+---+---+---+---+ 1758 +---+---+---+---+---+---+---+---+ 1759 | 1... mantissa | exponent | 1760 +---+---+---+---+---+---+---+---+ 1761 Figure 20: Duration in (8,4) pseudo-FP representation 1763 If the high bit is clear, the entire n-bit value (including the high 1764 bit) is the decoded value. If the high bit is set, the mantissa 1765 (including the high bit, with the exponent field cleared out but 1766 still present) is shifted left by the exponent to yield the decoded 1767 value. 1769 The (n,e)-pseudo-FP format can be decoded with a single line of code 1770 (plus a couple of constant definitions), as demonstrated in 1771 Figure 21. 1773 #define N 8 1774 #define E 4 1775 #define HIBIT (1 << (N - 1)) 1776 #define EMASK ((1 << E) - 1) 1777 #define MMASK ((1 << N) - 1 - EMASK) 1779 #define DECODE_8_4(r) (r < HIBIT ? r : (r & MMASK) << (r & EMASK)) 1781 Figure 21: Decoding an (8,4) pseudo-FP value 1783 Note that a pseudo-FP encoder needs to consider rounding; different 1784 applications of durations may favor rounding up or rounding down the 1785 value encoded in the message. 1787 The highest pseudo-FP value, represented by an all-ones byte (0xFF), 1788 is reserved to indicate an indefinite duration. The next lower value 1789 (0xEF) is thus the highest representable value and is decoded as 1790 7340032 seconds, a little more than 12 weeks. 1792 C.3. Rationale 1794 Where CPU power and memory is abundant, a duration can almost always 1795 be adequately represented by a non-negative floating-point number 1796 representing that number of seconds. Historically, many APIs have 1797 also used an integer representation, which limits both the resolution 1798 (e.g., if the integer represents the duration in seconds) and often 1799 the range (integer machine types have range limits that may become 1800 relevant). UNIX's "time_t" (which is used for both absolute time and 1801 durations) originally was a signed 32-bit value of seconds, but was 1802 later complemented by an additional integer to add microsecond 1803 ("struct timeval") and then later nanosecond ("struct timespec") 1804 resolution. 1806 Three decisions need to be made for each application of the concept 1807 of duration: 1809 o the *resolution*. What rounding error is acceptable? 1811 o the *range*. What is the maximum duration that needs to be 1812 represented? 1814 o the *number of bits* that can be expended. 1816 Obviously, these decisions are interrelated. Typically, a large 1817 range needs a large number of bits, unless resolution is traded. For 1818 most applications, the actual requirement for resolution are limited 1819 for longer durations, but can be more acute for shorter durations. 1821 C.4. Pseudo-Floating Point 1823 Constrained systems typically avoid the use of floating-point (FP) 1824 values, as 1826 o simple CPUs often don't have support for floating-point datatypes 1828 o software floating-point libraries are expensive in code size and 1829 slow. 1831 In addition, floating-point datatypes used to be a significant 1832 element of market differentiation in CPU design; it has taken the 1833 industry a long time to agree on a standard floating point 1834 representation. 1836 These issues have led to protocols that try to constrain themselves 1837 to integer representation even where the ability of a floating point 1838 representation to trade range for resolution would be beneficial. 1840 The idea of introducing _pseudo-FP_ is to obtain the increased range 1841 provided by embedding an exponent, without necessarily getting stuck 1842 with hardware datatypes or inefficient software floating-point 1843 libraries. 1845 For the purposes of this draft, we define an (n,e)-pseudo-FP as a 1846 fixed-length value of n bits, e of which may be used for an exponent. 1847 Figure 20 illustrates an (8,4)-pseudo-FP value. 1849 If the high bit is clear, the entire n-bit value (including the high 1850 bit) is the decoded value. If the high bit is set, the mantissa 1851 (including the high bit, but with the exponent field cleared out) is 1852 shifted left by the exponent to yield the decoded value. 1854 The (n,e)-pseudo-FP format can be decoded with a single line of code 1855 (plus a couple of constant definition), as demonstrated in Figure 21. 1857 Only non-negative numbers can be represented by this format. It is 1858 designed to provide full integer resolution for values from 0 to 1859 2^(n-1)-1, i.e., 0 to 127 in the (8,4) case, and a mantissa of n-e 1860 bits from 2^(n-1) to (2^n-2^e)*2^(2^e-1), i.e., 128 to 7864320 in the 1861 (8,4) case. By choosing e carefully, resolution can be traded 1862 against range. 1864 Note that a pseudo-FP encoder needs to consider rounding; different 1865 applications of durations may favor rounding up or rounding down the 1866 value encoded in the message. This requires a little more than a 1867 single line of code (which is left as an exercise to the reader, as 1868 the most efficient expression depends on hardware details). 1870 C.5. A Duration Type for CoAP 1872 CoAP needs durations in a number of places. In [I-D.ietf-core-coap], 1873 durations occur in the option "Subscription-lifetime" as well as in 1874 the option "Max-age". (Note that the option "Date" is not a 1875 duration, but a point in time.) Other durations of this kind may be 1876 added later. 1878 Most durations relevant to CoAP are best expressed with a minimum 1879 resolution of one second. More detailed resolutions are unlikely to 1880 provide much benefit. 1882 The range of lifetimes and caching ages are probably best kept below 1883 the order of magnitude of months. An (8,4)-pseudo-FP has the maximum 1884 value of 7864320, which is about 91 days; this appears to be adequate 1885 for a subscription lifetime and probably even for a maximum cache 1886 age. Figure 22 shows the values that can be expressed. (If a larger 1887 range for the latter is indeed desired, an (8,5)-pseudo-FP could be 1888 used; this would last 15 milleniums, at the cost of having only 3 1889 bits of accuracy for values larger than 127 seconds.) 1891 Proposal: A single duration type is used throughout CoAP, based on 1892 an (8,4)-pseudo-FP giving a duration in seconds. 1894 Benefits: Implementations can use a single piece of code for 1895 managing all CoAP-related durations. 1897 In addition, length information never needs to be managed for 1898 durations that are embedded in other data structures: All 1899 durations are expressed by a single byte. 1901 It might be worthwhile to reserve one duration value, e.g. 0xFF, for 1902 an indefinite duration. 1904 Duration Seconds Encoded 1905 ----------- ---------- ------- 1906 00:00:00 0x00000000 0x00 1907 00:00:01 0x00000001 0x01 1908 00:00:02 0x00000002 0x02 1909 00:00:03 0x00000003 0x03 1910 00:00:04 0x00000004 0x04 1911 00:00:05 0x00000005 0x05 1912 00:00:06 0x00000006 0x06 1913 00:00:07 0x00000007 0x07 1914 00:00:08 0x00000008 0x08 1915 00:00:09 0x00000009 0x09 1916 00:00:10 0x0000000a 0x0a 1917 00:00:11 0x0000000b 0x0b 1918 00:00:12 0x0000000c 0x0c 1919 00:00:13 0x0000000d 0x0d 1920 00:00:14 0x0000000e 0x0e 1921 00:00:15 0x0000000f 0x0f 1922 00:00:16 0x00000010 0x10 1923 00:00:17 0x00000011 0x11 1924 00:00:18 0x00000012 0x12 1925 00:00:19 0x00000013 0x13 1926 00:00:20 0x00000014 0x14 1927 00:00:21 0x00000015 0x15 1928 00:00:22 0x00000016 0x16 1929 00:00:23 0x00000017 0x17 1930 00:00:24 0x00000018 0x18 1931 00:00:25 0x00000019 0x19 1932 00:00:26 0x0000001a 0x1a 1933 00:00:27 0x0000001b 0x1b 1934 00:00:28 0x0000001c 0x1c 1935 00:00:29 0x0000001d 0x1d 1936 00:00:30 0x0000001e 0x1e 1937 00:00:31 0x0000001f 0x1f 1938 00:00:32 0x00000020 0x20 1939 00:00:33 0x00000021 0x21 1940 00:00:34 0x00000022 0x22 1941 00:00:35 0x00000023 0x23 1942 00:00:36 0x00000024 0x24 1943 00:00:37 0x00000025 0x25 1944 00:00:38 0x00000026 0x26 1945 00:00:39 0x00000027 0x27 1946 00:00:40 0x00000028 0x28 1947 00:00:41 0x00000029 0x29 1948 00:00:42 0x0000002a 0x2a 1949 00:00:43 0x0000002b 0x2b 1950 00:00:44 0x0000002c 0x2c 1951 00:00:45 0x0000002d 0x2d 1952 00:00:46 0x0000002e 0x2e 1953 00:00:47 0x0000002f 0x2f 1954 00:00:48 0x00000030 0x30 1955 00:00:49 0x00000031 0x31 1956 00:00:50 0x00000032 0x32 1957 00:00:51 0x00000033 0x33 1958 00:00:52 0x00000034 0x34 1959 00:00:53 0x00000035 0x35 1960 00:00:54 0x00000036 0x36 1961 00:00:55 0x00000037 0x37 1962 00:00:56 0x00000038 0x38 1963 00:00:57 0x00000039 0x39 1964 00:00:58 0x0000003a 0x3a 1965 00:00:59 0x0000003b 0x3b 1966 00:01:00 0x0000003c 0x3c 1967 00:01:01 0x0000003d 0x3d 1968 00:01:02 0x0000003e 0x3e 1969 00:01:03 0x0000003f 0x3f 1970 00:01:04 0x00000040 0x40 1971 00:01:05 0x00000041 0x41 1972 00:01:06 0x00000042 0x42 1973 00:01:07 0x00000043 0x43 1974 00:01:08 0x00000044 0x44 1975 00:01:09 0x00000045 0x45 1976 00:01:10 0x00000046 0x46 1977 00:01:11 0x00000047 0x47 1978 00:01:12 0x00000048 0x48 1979 00:01:13 0x00000049 0x49 1980 00:01:14 0x0000004a 0x4a 1981 00:01:15 0x0000004b 0x4b 1982 00:01:16 0x0000004c 0x4c 1983 00:01:17 0x0000004d 0x4d 1984 00:01:18 0x0000004e 0x4e 1985 00:01:19 0x0000004f 0x4f 1986 00:01:20 0x00000050 0x50 1987 00:01:21 0x00000051 0x51 1988 00:01:22 0x00000052 0x52 1989 00:01:23 0x00000053 0x53 1990 00:01:24 0x00000054 0x54 1991 00:01:25 0x00000055 0x55 1992 00:01:26 0x00000056 0x56 1993 00:01:27 0x00000057 0x57 1994 00:01:28 0x00000058 0x58 1995 00:01:29 0x00000059 0x59 1996 00:01:30 0x0000005a 0x5a 1997 00:01:31 0x0000005b 0x5b 1998 00:01:32 0x0000005c 0x5c 1999 00:01:33 0x0000005d 0x5d 2000 00:01:34 0x0000005e 0x5e 2001 00:01:35 0x0000005f 0x5f 2002 00:01:36 0x00000060 0x60 2003 00:01:37 0x00000061 0x61 2004 00:01:38 0x00000062 0x62 2005 00:01:39 0x00000063 0x63 2006 00:01:40 0x00000064 0x64 2007 00:01:41 0x00000065 0x65 2008 00:01:42 0x00000066 0x66 2009 00:01:43 0x00000067 0x67 2010 00:01:44 0x00000068 0x68 2011 00:01:45 0x00000069 0x69 2012 00:01:46 0x0000006a 0x6a 2013 00:01:47 0x0000006b 0x6b 2014 00:01:48 0x0000006c 0x6c 2015 00:01:49 0x0000006d 0x6d 2016 00:01:50 0x0000006e 0x6e 2017 00:01:51 0x0000006f 0x6f 2018 00:01:52 0x00000070 0x70 2019 00:01:53 0x00000071 0x71 2020 00:01:54 0x00000072 0x72 2021 00:01:55 0x00000073 0x73 2022 00:01:56 0x00000074 0x74 2023 00:01:57 0x00000075 0x75 2024 00:01:58 0x00000076 0x76 2025 00:01:59 0x00000077 0x77 2026 00:02:00 0x00000078 0x78 2027 00:02:01 0x00000079 0x79 2028 00:02:02 0x0000007a 0x7a 2029 00:02:03 0x0000007b 0x7b 2030 00:02:04 0x0000007c 0x7c 2031 00:02:05 0x0000007d 0x7d 2032 00:02:06 0x0000007e 0x7e 2033 00:02:07 0x0000007f 0x7f 2034 00:02:08 0x00000080 0x80 2035 00:02:24 0x00000090 0x90 2036 00:02:40 0x000000a0 0xa0 2037 00:02:56 0x000000b0 0xb0 2038 00:03:12 0x000000c0 0xc0 2039 00:03:28 0x000000d0 0xd0 2040 00:03:44 0x000000e0 0xe0 2041 00:04:00 0x000000f0 0xf0 2042 00:04:16 0x00000100 0x81 2043 00:04:48 0x00000120 0x91 2044 00:05:20 0x00000140 0xa1 2045 00:05:52 0x00000160 0xb1 2046 00:06:24 0x00000180 0xc1 2047 00:06:56 0x000001a0 0xd1 2048 00:07:28 0x000001c0 0xe1 2049 00:08:00 0x000001e0 0xf1 2050 00:08:32 0x00000200 0x82 2051 00:09:36 0x00000240 0x92 2052 00:10:40 0x00000280 0xa2 2053 00:11:44 0x000002c0 0xb2 2054 00:12:48 0x00000300 0xc2 2055 00:13:52 0x00000340 0xd2 2056 00:14:56 0x00000380 0xe2 2057 00:16:00 0x000003c0 0xf2 2058 00:17:04 0x00000400 0x83 2059 00:19:12 0x00000480 0x93 2060 00:21:20 0x00000500 0xa3 2061 00:23:28 0x00000580 0xb3 2062 00:25:36 0x00000600 0xc3 2063 00:27:44 0x00000680 0xd3 2064 00:29:52 0x00000700 0xe3 2065 00:32:00 0x00000780 0xf3 2066 00:34:08 0x00000800 0x84 2067 00:38:24 0x00000900 0x94 2068 00:42:40 0x00000a00 0xa4 2069 00:46:56 0x00000b00 0xb4 2070 00:51:12 0x00000c00 0xc4 2071 00:55:28 0x00000d00 0xd4 2072 00:59:44 0x00000e00 0xe4 2073 01:04:00 0x00000f00 0xf4 2074 01:08:16 0x00001000 0x85 2075 01:16:48 0x00001200 0x95 2076 01:25:20 0x00001400 0xa5 2077 01:33:52 0x00001600 0xb5 2078 01:42:24 0x00001800 0xc5 2079 01:50:56 0x00001a00 0xd5 2080 01:59:28 0x00001c00 0xe5 2081 02:08:00 0x00001e00 0xf5 2082 02:16:32 0x00002000 0x86 2083 02:33:36 0x00002400 0x96 2084 02:50:40 0x00002800 0xa6 2085 03:07:44 0x00002c00 0xb6 2086 03:24:48 0x00003000 0xc6 2087 03:41:52 0x00003400 0xd6 2088 03:58:56 0x00003800 0xe6 2089 04:16:00 0x00003c00 0xf6 2090 04:33:04 0x00004000 0x87 2091 05:07:12 0x00004800 0x97 2092 05:41:20 0x00005000 0xa7 2093 06:15:28 0x00005800 0xb7 2094 06:49:36 0x00006000 0xc7 2095 07:23:44 0x00006800 0xd7 2096 07:57:52 0x00007000 0xe7 2097 08:32:00 0x00007800 0xf7 2098 09:06:08 0x00008000 0x88 2099 10:14:24 0x00009000 0x98 2100 11:22:40 0x0000a000 0xa8 2101 12:30:56 0x0000b000 0xb8 2102 13:39:12 0x0000c000 0xc8 2103 14:47:28 0x0000d000 0xd8 2104 15:55:44 0x0000e000 0xe8 2105 17:04:00 0x0000f000 0xf8 2106 18:12:16 0x00010000 0x89 2107 20:28:48 0x00012000 0x99 2108 22:45:20 0x00014000 0xa9 2109 1d 01:01:52 0x00016000 0xb9 2110 1d 03:18:24 0x00018000 0xc9 2111 1d 05:34:56 0x0001a000 0xd9 2112 1d 07:51:28 0x0001c000 0xe9 2113 1d 10:08:00 0x0001e000 0xf9 2114 1d 12:24:32 0x00020000 0x8a 2115 1d 16:57:36 0x00024000 0x9a 2116 1d 21:30:40 0x00028000 0xaa 2117 2d 02:03:44 0x0002c000 0xba 2118 2d 06:36:48 0x00030000 0xca 2119 2d 11:09:52 0x00034000 0xda 2120 2d 15:42:56 0x00038000 0xea 2121 2d 20:16:00 0x0003c000 0xfa 2122 3d 00:49:04 0x00040000 0x8b 2123 3d 09:55:12 0x00048000 0x9b 2124 3d 19:01:20 0x00050000 0xab 2125 4d 04:07:28 0x00058000 0xbb 2126 4d 13:13:36 0x00060000 0xcb 2127 4d 22:19:44 0x00068000 0xdb 2128 5d 07:25:52 0x00070000 0xeb 2129 5d 16:32:00 0x00078000 0xfb 2130 6d 01:38:08 0x00080000 0x8c 2131 6d 19:50:24 0x00090000 0x9c 2132 7d 14:02:40 0x000a0000 0xac 2133 8d 08:14:56 0x000b0000 0xbc 2134 9d 02:27:12 0x000c0000 0xcc 2135 9d 20:39:28 0x000d0000 0xdc 2136 10d 14:51:44 0x000e0000 0xec 2137 11d 09:04:00 0x000f0000 0xfc 2138 12d 03:16:16 0x00100000 0x8d 2139 13d 15:40:48 0x00120000 0x9d 2140 15d 04:05:20 0x00140000 0xad 2141 16d 16:29:52 0x00160000 0xbd 2142 18d 04:54:24 0x00180000 0xcd 2143 19d 17:18:56 0x001a0000 0xdd 2144 21d 05:43:28 0x001c0000 0xed 2145 22d 18:08:00 0x001e0000 0xfd 2146 24d 06:32:32 0x00200000 0x8e 2147 27d 07:21:36 0x00240000 0x9e 2148 30d 08:10:40 0x00280000 0xae 2149 33d 08:59:44 0x002c0000 0xbe 2150 36d 09:48:48 0x00300000 0xce 2151 39d 10:37:52 0x00340000 0xde 2152 42d 11:26:56 0x00380000 0xee 2153 45d 12:16:00 0x003c0000 0xfe 2154 48d 13:05:04 0x00400000 0x8f 2155 54d 14:43:12 0x00480000 0x9f 2156 60d 16:21:20 0x00500000 0xaf 2157 66d 17:59:28 0x00580000 0xbf 2158 72d 19:37:36 0x00600000 0xcf 2159 78d 21:15:44 0x00680000 0xdf 2160 84d 22:53:52 0x00700000 0xef 2161 91d 00:32:00 0x00780000 0xff (reserved) 2163 Figure 22 2165 Authors' Addresses 2167 Carsten Bormann 2168 Universitaet Bremen TZI 2169 Postfach 330440 2170 Bremen D-28359 2171 Germany 2173 Phone: +49-421-218-63921 2174 Email: cabo@tzi.org 2176 Klaus Hartke 2177 Universitaet Bremen TZI 2178 Postfach 330440 2179 Bremen D-28359 2180 Germany 2182 Phone: +49-421-218-63905 2183 Email: hartke@tzi.org