idnits 2.17.1 draft-bormann-coap-misc-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 31, 2011) is 4561 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-07 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-17 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group C. Bormann 3 Internet-Draft K. Hartke 4 Intended status: Informational Universitaet Bremen TZI 5 Expires: May 3, 2012 October 31, 2011 7 Miscellaneous additions to CoAP 8 draft-bormann-coap-misc-09 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 May 3, 2012. 35 Copyright Notice 37 Copyright (c) 2011 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Getting rid of artificial limitations . . . . . . . . . . . . 4 54 2.1. Beyond 15 options . . . . . . . . . . . . . . . . . . . . 4 55 2.1.1. Implementation considerations . . . . . . . . . . . . 6 56 2.1.2. What should we do now? . . . . . . . . . . . . . . . . 7 57 2.1.3. Alternatives . . . . . . . . . . . . . . . . . . . . . 7 58 2.2. Beyond 270 bytes in a single option . . . . . . . . . . . 7 59 3. URI Authorities with Binary Adresses . . . . . . . . . . . . . 9 60 4. User-defined Option . . . . . . . . . . . . . . . . . . . . . 11 61 5. Payload-Length Option . . . . . . . . . . . . . . . . . . . . 12 62 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 64 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 65 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 66 9.1. Normative References . . . . . . . . . . . . . . . . . . . 16 67 9.2. Informative References . . . . . . . . . . . . . . . . . . 16 68 Appendix A. The Cemetery (Things we won't do) . . . . . . . . . . 17 69 A.1. Stateful URI compression . . . . . . . . . . . . . . . . . 17 70 Appendix B. Experimental Options . . . . . . . . . . . . . . . . 19 71 B.1. Options indicating absolute time . . . . . . . . . . . . . 19 72 B.2. Representing Durations . . . . . . . . . . . . . . . . . . 20 73 B.3. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 21 74 B.4. Pseudo-Floating Point . . . . . . . . . . . . . . . . . . 22 75 B.5. A Duration Type for CoAP . . . . . . . . . . . . . . . . . 23 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 78 1. Introduction 80 The CoRE WG is tasked with standardizing an Application Protocol for 81 Constrained Networks/Nodes, CoAP [I-D.ietf-core-coap]. This protocol 82 is intended to provide RESTful [REST] services not unlike HTTP 83 [RFC2616], while reducing the complexity of implementation as well as 84 the size of packets exchanged in order to make these services useful 85 in a highly constrained network of themselves highly constrained 86 nodes. 88 This objective requires restraint in a number of sometimes 89 conflicting ways: 91 o reducing implementation complexity in order to minimize code size, 93 o reducing message sizes in order to minimize the number of 94 fragments needed for each message (in turn to maximize the 95 probability of delivery of the message), the amount of 96 transmission power needed and the loading of the limited-bandwidth 97 channel, 99 o reducing requirements on the environment such as stable storage, 100 good sources of randomness or user interaction capabilities. 102 This draft attempts to address a number of problems not yet 103 adequately solved in [I-D.ietf-core-coap]. The solutions proposed to 104 these problems are somewhat interrelated and are therefore presented 105 in one draft. 107 The appendix contains the "CoAP cemetery" (possibly later to move 108 into its own draft), documenting roads that the WG decided not to 109 take, in order to spare readers from reinventing them in vain. 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in [RFC2119]. 115 The term "byte" is used in its now customary sense as a synonym for 116 "octet". 118 2. Getting rid of artificial limitations 120 _Artificial limitations_ are limitations of a protocol or system that 121 are not rooted in limitations of actual capabilities, but in 122 arbitrary design decisions. Proper system design tries to avoid 123 artificial limitations, as these tend to cause complexity in systems 124 that need to work with these limitations. 126 E.g., the original UNIX filesystem had an artificial limitation of 127 the length of a path name component to 14 bytes. This led to all 128 kinds of workarounds in programs that manipulate file names: E.g., 129 systematically replacing a ".el" extension in a filename with a 130 ".elc" for the compiled file might exceed the limit, so all ".el" 131 files were suddenly limited to 13-byte filenames. 133 Note that, today, there still is a limitation in most file system 134 implementations, typically at 255. This just happens to be high 135 enough to rarely be of real-world concern; we will refer to this case 136 as a "painless" artificial limitation. 138 CoAP-08 has two highly recognizable artificial limitations in its 139 protocol encoding 141 o The number of options in a single message is limited to 15 max. 143 o The length of an option is limited to 270 max. 145 It is arguable that the latter limitation causes few problems, just 146 as the 255-byte path name component limitation in filenames today 147 causes few problems. Just in case, Section 2.2 provides a design to 148 extend this. 150 2.1. Beyond 15 options 152 The limit of 15 options is motivated by the fixed four-bit field "OC" 153 that is used for indicating the number of options in the fixed-length 154 CoAP header (Figure 1). 156 0 1 2 3 157 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 158 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 159 |Ver| T | OC | Code | Message ID | 160 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 161 | Options (if any) ... 162 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 163 | Payload (if any) ... 164 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 165 Figure 1: Four-byte fixed header in a CoAP Message 167 Note that there is another fixed four-bit field in CoAP: the option 168 length (Figure 2 - note that this figure is not to the same scale as 169 the previous figure): 171 0 1 2 3 4 5 6 7 172 +---+---+---+---+---+---+---+---+ 173 | Option Delta | Length | for 0..14 174 +---+---+---+---+---+---+---+---+ 175 | Option Value ... 176 +---+---+---+---+---+---+---+---+ 178 Figure 2: Short Option Header 180 Since 15 is inacceptable for a maximum option length, the all-ones 181 value (15) was taken out of the set of allowable values for the short 182 header, and a long header was introduced that allows the insertion of 183 an extension byte (Figure 3): 185 for 15..270: 186 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 187 | Option Delta | 1 1 1 1 | Length - 15 | 188 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 189 | Option Value ... 190 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 192 Figure 3: Long Option Header 194 We might want to use the same technique for the CoAP header as well. 195 There are two obvious places where the extension byte could be 196 placed: 198 1. right after the byte carrying the OC field, so the structure is 199 the same as for the option header; 201 2. right after the fixed-size CoAP header. 203 Both solutions lose the fixed-size-ness of the CoAP header. 205 Solution 1 has the disadvantage that the CoAP header is also changing 206 in structure: The extension byte is wedged between the first and the 207 second byte of the CoAP header. This is unfortunate, as the number 208 of options only comes into play when the option processing begins, so 209 it is more natural to use solution 2 (Figure 4): 211 0 1 2 3 212 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 213 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 214 |Ver| T | 15 | Code | Message ID | 215 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 216 | OC - 15 | Options ... 217 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 218 | Payload (if any) ... 219 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 221 Figure 4: Extended header for CoAP Messages with 15+ options 223 This would allow for up to 270 options in a CoAP message, which is 224 very likely way beyond the "painless" threshold. 226 2.1.1. Implementation considerations 228 For a message decoder, this extension creates relatively little pain, 229 as the number of options only becomes interesting when the encoding 230 turns to the options part of the message, which is then simply lead 231 in by the extension byte if the four-bit field is 15. 233 For a message encoder, this extension is not so rosy. If the encoder 234 is constructing the message serially, it may not know in advance 235 whether the number of options will exceed 14. None of the following 236 implementation strategies is particularly savory, but all of them do 237 work: 239 1. Encode the options serially under the assumption that the number 240 of options will be 14 or less. When the 15th option needs to be 241 encoded, abort the option encoding, and restart it from scratch 242 one byte further to the left. 244 2. Similar to 1, except that the bytes already encoded are all moved 245 one byte to right, the extension byte is inserted, and the option 246 encoding process is continued. 248 3. The encoder always leaves space for the extension byte (at least 249 if it can't prove the number will be less thatn 14). If the 250 extension byte is not needed, an Option 0 with length 0 is 251 encoded instead (i.e., one byte is wasted - this option is 252 elective and will be ignored by the receiver). 254 As a minimum, to enable strategy 3, the option 0 should be reserved 255 at least for the case of length=0. 257 2.1.2. What should we do now? 259 As a minimum proposal for the next version of CoAP, the value 15 for 260 OC should be marked as reserved today. 262 2.1.3. Alternatives 264 One alternative that has been discussed previously is to have an 265 "Options" Option, which allows the carriage of multiple options in 266 the belly of a single one. This could also be used to carry more 267 than 15 options. However: 269 o The conditional introduction of an Options option has 270 implementation considerations that are likely to be more severe 271 than the ones listed above; 273 o since 270 bytes may not be enough for the encoding of _all_ 274 options, the "Options" option would need to be repeatable. This 275 creates many different ways to encode the same message, leading to 276 combinatorial explosion in test cases for ensuring 277 interoperability. 279 2.2. Beyond 270 bytes in a single option 281 The authors would argue that 270 as the maximum length of an option 282 is already beyond the "painless" threshold. 284 If that is not the consensus of the WG, the scheme can easily be 285 extended as in Figure 5: 287 for 15..269: 288 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 289 | Option Delta | 1 1 1 1 | Length - 15 | 290 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 291 | Option Value ... 292 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 294 for 270..65805: 295 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 296 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 297 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 298 | Length - 270 (in network byte order) | 299 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 300 | Option Value ... 301 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 303 Figure 5: Ridiculously Long Option Header 305 The infinite number of obvious variations on this scheme are left as 306 an exercise to the reader. 308 Again, as a precaution to future extensions, the current encoding for 309 length 270 (eight ones in the extension byte) could be marked as 310 reserved today. 312 3. URI Authorities with Binary Adresses 314 One problem with the way URI authorities are represented in the URI 315 syntax is that the authority part can be very bulky if it encodes an 316 IPv6 address in ASCII. 318 Proposal: Provide an option "Uri-Authority-Binary" that can be an 319 even number of bytes between 2 and 18 except 12 or 14. 321 o If the number of bytes is 2, the destination IP address of the 322 packet transporting the CoAP message is implied. 324 o If the number of bytes is 4 or 6, the first four bytes of the 325 option value are an IPv4 address in binary. 327 o If the number of bytes is 8 or 10, the first eight bytes are the 328 lower 64 bits of an IPv6 address; the upper eight bytes are 329 implied from the destination address of the packet transporting 330 the CoAP message. 332 o If the number of bytes is 16 or 18, the first 16 bytes are an IPv6 333 address. 335 o If two more bytes remain, this is a port number (as always in 336 network byte order). 338 The resulting authority is (conceptually translated into ASCII and) 339 used in place of an Uri-Authority option, or inserted into a Proxy- 340 Uri. Examples: 342 +-------------+------------------+---------+------------------------+ 343 | Proxy-Uri | Uri-Authority-Bi | Uri-Pat | URI | 344 | | nary | h | | 345 +-------------+------------------+---------+------------------------+ 346 | (none) | (none) | (none) | "/" | 347 | | | | | 348 | (none) | (none) | 'temp' | "/temp" | 349 | | | | | 350 | (none) | 2 bytes: 61616 | 'temp' | "coap://[DA]:61616/tem | 351 | | | | p" | 352 | | | | | 353 | (none) | 16 bytes: | temp | "coap://[2000::1]/temp | 354 | | 2000::1 | | " | 355 | | | | | 356 | 'http://' | 10 bytes: | (none) | "http://[DA::123:45]:6 | 357 | | ::123:45 + 616 | | 16" | 358 | | | | | 359 | 'http:///te | 18 bytes: | (none) | "http://[2000::1]:616/ | 360 | mp' | 2000::1 + 616 | | temp" | 361 +-------------+------------------+---------+------------------------+ 363 4. User-defined Option 365 To enable experimentation and community-specific options, option 366 number 14 (the first NOP option) can also be used as a user-defined 367 option. For this application, the option value has one or more 368 bytes, the semantics of which are defined by prior agreement between 369 the communicating partners. 371 It is RECOMMENDED to start the option value with a unique identifier, 372 e.g., the SDNV [RFC5050] of the enterprise number of the organisation 373 defining the option, possibly followed by additional discriminating 374 bits or bytes. 376 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 377 |1 0 0 0 0 0 0 1|0 1 1 1 0 0 1 1| private opt-id| value... | 378 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 379 \___SDNV of enterprise number___/ 381 Figure 6: Example option value for user-defined option 383 User-defined Options are elective. 385 The User-defined Option is repeatable. 387 Potential options: 389 +-----+----------+------+-------------+---------+---------+ 390 | No. | C/E | Name | Format | Length | Default | 391 +-----+----------+------+-------------+---------+---------+ 392 | 14 | Elective | User | (see below) | 1-270 B | (empty) | 393 +-----+----------+------+-------------+---------+---------+ 395 5. Payload-Length Option 397 Not all transport mappings may provide an unambiguous length of the 398 CoAP message. For UDP, it may also be desirable to pack more than 399 one CoAP message into one UDP payload (aggregation); in that case, 400 for all but the last message there needs to be a way to delimit the 401 payload of that message. 403 This can be solved using a new option, the Payload-Length option. If 404 this option is present, the value of this option is an unsigned 405 integer giving the length of the payload of the message (note that 406 this integer can be zero for a zero-length payload, which can in turn 407 be represented by a zero-length option value). (In the UDP 408 aggregation case, what would have been in the payload of this message 409 after "payload-length" bytes is then actually one or more additional 410 messages.) 412 6. IANA Considerations 414 This draft adds option numbers to Table 2 of [I-D.ietf-core-coap], 415 resulting in: 417 TBD. 419 7. Security Considerations 421 TBD. 423 8. Acknowledgements 425 This work was partially funded by the Klaus Tschira Foundation. 427 Of course, much of the content of this draft is the result of 428 discussions with the [I-D.ietf-core-coap] authors. 430 9. References 432 9.1. Normative References 434 [I-D.ietf-core-coap] 435 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 436 "Constrained Application Protocol (CoAP)", 437 draft-ietf-core-coap-07 (work in progress), July 2011. 439 [I-D.ietf-httpbis-p1-messaging] 440 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 441 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 442 J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and 443 Message Parsing", draft-ietf-httpbis-p1-messaging-17 (work 444 in progress), October 2011. 446 [I-D.ietf-httpbis-p4-conditional] 447 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 448 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 449 J. Reschke, "HTTP/1.1, part 4: Conditional Requests", 450 draft-ietf-httpbis-p4-conditional-17 (work in progress), 451 October 2011. 453 [I-D.ietf-httpbis-p6-cache] 454 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 455 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., 456 Nottingham, M., and J. Reschke, "HTTP/1.1, part 6: 457 Caching", draft-ietf-httpbis-p6-cache-17 (work in 458 progress), October 2011. 460 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 461 Requirement Levels", BCP 14, RFC 2119, March 1997. 463 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 464 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 465 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 467 9.2. Informative References 469 [REST] Fielding, R., "Architectural Styles and the Design of 470 Network-based Software Architectures", 2000. 472 [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol 473 Specification", RFC 5050, November 2007. 475 Appendix A. The Cemetery (Things we won't do) 477 This annex documents roads that the WG decided not to take, in order 478 to spare readers from reinventing them in vain. 480 A.1. Stateful URI compression 482 Is the approximately 25 % average saving achievable with Huffman- 483 based URI compression schemes worth the complexity? Probably not, 484 because much higher average savings can be achieved by introducing 485 state. 487 Henning Schulzrinne has proposed for a server to be able to supply a 488 shortened URI once a resource has been requested using the full- 489 length URI. Let's call such a shortened referent a _Temporary 490 Resource Identifier_, _TeRI_ for short. This could be expressed by a 491 response option as shown in Figure 7. 493 0 494 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 495 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 496 | duration | TeRI... 497 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 499 Figure 7: Option for offering a TeRI in a response 501 The TeRI offer option indicates that the server promises to offer 502 this resources under the TeRI given for at least the time given as 503 the duration. Another TeRI offer can be made later to extend the 504 duration. 506 Once a TeRI for a URI is known (and still within its lifetime), the 507 client can supply a TeRI instead of a URI in its requests. The same 508 option format as an offer could be used to allow the client to 509 indicate how long it believes the TeRI will still be valid (so that 510 the server can decide when to update the lifetime duration). TeRIs 511 in requests could be distinguished from URIs e.g. by using a 512 different option number. 514 Proposal: Add a TeRI option that can be used in CoAP requests and 515 responses. 517 Add a way to indicate a TeRI and its duration in a link-value. 519 Do not add any form of stateless URI encoding. 521 Benefits: Much higher reduction of message size than any stateless 522 URI encoding could achieve. 524 As the use of TeRIs is entirely optional, minimal complexity nodes 525 can get by without implementing them. 527 Drawbacks: Adds considerable state and complexity to the protocol. 529 It turns out that real CoAP URIs are short enough that TeRIs are 530 not needed. 532 (Discuss the security implications of TeRIs.) 534 Appendix B. Experimental Options 536 This annex documents proposals that need significant additional 537 discussion before they can become part of (or go back to) the main 538 CoAP specification. They are not dead, but might die if there turns 539 out to be no good way to solve the problem. 541 B.1. Options indicating absolute time 543 HTTP has a number of headers that may indicate absolute time: 545 o "Date", defined in Section 14.18 in [RFC2616] (Section 9.3 in 546 [I-D.ietf-httpbis-p1-messaging]), giving the absolute time a 547 response was generated; 549 o "Last-Modified", defined in Section 14.29 in [RFC2616], (Section 550 6.6 in [I-D.ietf-httpbis-p4-conditional], giving the absolute time 551 of when the origin server believes the resource representation was 552 last modified; 554 o "If-Modified-Since", defined in Section 14.25 in [RFC2616], 555 "If-Unmodified-Since", defined in Section 14.28 in [RFC2616], and 556 "If-Range", defined in Section 14.27 in [RFC2616] can be used to 557 supply absolute time to gate a conditional request; 559 o "Expires", defined in Section 14.21 in [RFC2616] (Section 3.3 in 560 [I-D.ietf-httpbis-p6-cache]), giving the absolute time after which 561 a response is considered stale. 563 o The more obscure headers "Retry-After", defined in Section 14.37 564 in [RFC2616], and "Warning", defined in section 14.46 in 565 [RFC2616], also may employ absolute time. 567 [I-D.ietf-core-coap] defines a single "Date" option, which however 568 "indicates the creation time and date of a given resource 569 representation", i.e., is closer to a "Last-Modified" HTTP header. 570 HTTP's caching rules [I-D.ietf-httpbis-p6-cache] make use of both 571 "Date" and "Last-Modified", combined with "Expires". The specific 572 semantics required for CoAP needs further consideration. 574 In addition to the definition of the semantics, an encoding for 575 absolute times needs to be specified. 577 In UNIX-related systems, it is customary to indicate absolute time as 578 an integer number of seconds, after midnight UTC, January 1, 1970. 579 Unless negative numbers are employed, this time format cannot 580 represent time values prior to January 1, 1970, which probably is not 581 required for the uses ob absolute time in CoAP. 583 If a 32-bit integer is used and allowance is made for a sign-bit in a 584 local implementation, the latest UTC time value that can be 585 represented by the resulting 31 bit integer value is 03:14:07 on 586 January 19, 2038. If the 32-bit integer is used as an unsigned 587 value, the last date is 2106-02-07, 06:28:15. 589 The reach can be extended by: - moving the epoch forward, e.g. by 40 590 years (= 1262304000 seconds) to 2010-01-01. This makes it impossible 591 to represent Last-Modified times in that past (such as could be 592 gatewayed in from HTTP). - extending the number of bits, e.g. by one 593 more byte, either always or as one of two formats, keeping the 32-bit 594 variant as well. 596 Also, the resolution can be extended by expressing time in 597 milliseconds etc., requiring even more bits (e.g., a 48-bit unsigned 598 integer of milliseconds would last well after year 9999.) 600 For experiments, an experimental "Date" option is defined with the 601 semantics of HTTP's "Last-Modified". It can carry an unsigned 602 integer of 32, 40, or 48 bits; 32- and 40-bit integers indicate the 603 absolute time in seconds since 1970-01-01 00:00 UTC, while 48-bit 604 integers indicate the absolute time in milliseconds since 1970-01-01 605 00:00 UTC. 607 However, that option is not really that useful until there is a 608 "If-Modified-Since" option as well. 610 (Also: Discuss nodes without clocks.) 612 B.2. Representing Durations 614 Various message types used in CoAP need the representation of 615 *durations*, i.e. of the length of a timespan. In SI units, these 616 are measured in seconds. CoAP durations represent integer numbers of 617 seconds, but instead of representing these numbers as integers, a 618 more compact single-byte pseudo-floating-point (pseudo-FP) 619 representation is used (Figure 8). 621 0 1 2 3 4 5 6 7 622 +---+---+---+---+---+---+---+---+ 623 | 0... value | 624 +---+---+---+---+---+---+---+---+ 626 +---+---+---+---+---+---+---+---+ 627 | 1... mantissa | exponent | 628 +---+---+---+---+---+---+---+---+ 629 Figure 8: Duration in (8,4) pseudo-FP representation 631 If the high bit is clear, the entire n-bit value (including the high 632 bit) is the decoded value. If the high bit is set, the mantissa 633 (including the high bit, with the exponent field cleared out but 634 still present) is shifted left by the exponent to yield the decoded 635 value. 637 The (n,e)-pseudo-FP format can be decoded with a single line of code 638 (plus a couple of constant definitions), as demonstrated in Figure 9. 640 #define N 8 641 #define E 4 642 #define HIBIT (1 << (N - 1)) 643 #define EMASK ((1 << E) - 1) 644 #define MMASK ((1 << N) - 1 - EMASK) 646 #define DECODE_8_4(r) (r < HIBIT ? r : (r & MMASK) << (r & EMASK)) 648 Figure 9: Decoding an (8,4) pseudo-FP value 650 Note that a pseudo-FP encoder needs to consider rounding; different 651 applications of durations may favor rounding up or rounding down the 652 value encoded in the message. 654 The highest pseudo-FP value, represented by an all-ones byte (0xFF), 655 is reserved to indicate an indefinite duration. The next lower value 656 (0xEF) is thus the highest representable value and is decoded as 657 7340032 seconds, a little more than 12 weeks. 659 B.3. Rationale 661 Where CPU power and memory is abundant, a duration can almost always 662 be adequately represented by a non-negative floating-point number 663 representing that number of seconds. Historically, many APIs have 664 also used an integer representation, which limits both the resolution 665 (e.g., if the integer represents the duration in seconds) and often 666 the range (integer machine types have range limits that may become 667 relevant). UNIX's "time_t" (which is used for both absolute time and 668 durations) originally was a signed 32-bit value of seconds, but was 669 later complemented by an additional integer to add microsecond 670 ("struct timeval") and then later nanosecond ("struct timespec") 671 resolution. 673 Three decisions need to be made for each application of the concept 674 of duration: 676 o the *resolution*. What rounding error is acceptable? 678 o the *range*. What is the maximum duration that needs to be 679 represented? 681 o the *number of bits* that can be expended. 683 Obviously, these decisions are interrelated. Typically, a large 684 range needs a large number of bits, unless resolution is traded. For 685 most applications, the actual requirement for resolution are limited 686 for longer durations, but can be more acute for shorter durations. 688 B.4. Pseudo-Floating Point 690 Constrained systems typically avoid the use of floating-point (FP) 691 values, as 693 o simple CPUs often don't have support for floating-point datatypes 695 o software floating-point libraries are expensive in code size and 696 slow. 698 In addition, floating-point datatypes used to be a significant 699 element of market differentiation in CPU design; it has taken the 700 industry a long time to agree on a standard floating point 701 representation. 703 These issues have led to protocols that try to constrain themselves 704 to integer representation even where the ability of a floating point 705 representation to trade range for resolution would be beneficial. 707 The idea of introducing _pseudo-FP_ is to obtain the increased range 708 provided by embedding an exponent, without necessarily getting stuck 709 with hardware datatypes or inefficient software floating-point 710 libraries. 712 For the purposes of this draft, we define an (n,e)-pseudo-FP as a 713 fixed-length value of n bits, e of which may be used for an exponent. 714 Figure 8 illustrates an (8,4)-pseudo-FP value. 716 If the high bit is clear, the entire n-bit value (including the high 717 bit) is the decoded value. If the high bit is set, the mantissa 718 (including the high bit, but with the exponent field cleared out) is 719 shifted left by the exponent to yield the decoded value. 721 The (n,e)-pseudo-FP format can be decoded with a single line of code 722 (plus a couple of constant definition), as demonstrated in Figure 9. 724 Only non-negative numbers can be represented by this format. It is 725 designed to provide full integer resolution for values from 0 to 726 2^(n-1)-1, i.e., 0 to 127 in the (8,4) case, and a mantissa of n-e 727 bits from 2^(n-1) to (2^n-2^e)*2^(2^e-1), i.e., 128 to 7864320 in the 728 (8,4) case. By choosing e carefully, resolution can be traded 729 against range. 731 Note that a pseudo-FP encoder needs to consider rounding; different 732 applications of durations may favor rounding up or rounding down the 733 value encoded in the message. This requires a little more than a 734 single line of code (which is left as an exercise to the reader, as 735 the most efficient expression depends on hardware details). 737 B.5. A Duration Type for CoAP 739 CoAP needs durations in a number of places. In [I-D.ietf-core-coap], 740 durations occur in the option "Subscription-lifetime" as well as in 741 the option "Max-age". (Note that the option "Date" is not a 742 duration, but a point in time.) Other durations of this kind may be 743 added later. 745 Most durations relevant to CoAP are best expressed with a minimum 746 resolution of one second. More detailed resolutions are unlikely to 747 provide much benefit. 749 The range of lifetimes and caching ages are probably best kept below 750 the order of magnitude of months. An (8,4)-pseudo-FP has the maximum 751 value of 7864320, which is about 91 days; this appears to be adequate 752 for a subscription lifetime and probably even for a maximum cache 753 age. Figure 10 shows the values that can be expressed. (If a larger 754 range for the latter is indeed desired, an (8,5)-pseudo-FP could be 755 used; this would last 15 milleniums, at the cost of having only 3 756 bits of accuracy for values larger than 127 seconds.) 758 Proposal: A single duration type is used throughout CoAP, based on 759 an (8,4)-pseudo-FP giving a duration in seconds. 761 Benefits: Implementations can use a single piece of code for 762 managing all CoAP-related durations. 764 In addition, length information never needs to be managed for 765 durations that are embedded in other data structures: All 766 durations are expressed by a single byte. 768 It might be worthwhile to reserve one duration value, e.g. 0xFF, for 769 an indefinite duration. 771 Duration Seconds Encoded 772 ----------- ---------- ------- 773 00:00:00 0x00000000 0x00 774 00:00:01 0x00000001 0x01 775 00:00:02 0x00000002 0x02 776 00:00:03 0x00000003 0x03 777 00:00:04 0x00000004 0x04 778 00:00:05 0x00000005 0x05 779 00:00:06 0x00000006 0x06 780 00:00:07 0x00000007 0x07 781 00:00:08 0x00000008 0x08 782 00:00:09 0x00000009 0x09 783 00:00:10 0x0000000a 0x0a 784 00:00:11 0x0000000b 0x0b 785 00:00:12 0x0000000c 0x0c 786 00:00:13 0x0000000d 0x0d 787 00:00:14 0x0000000e 0x0e 788 00:00:15 0x0000000f 0x0f 789 00:00:16 0x00000010 0x10 790 00:00:17 0x00000011 0x11 791 00:00:18 0x00000012 0x12 792 00:00:19 0x00000013 0x13 793 00:00:20 0x00000014 0x14 794 00:00:21 0x00000015 0x15 795 00:00:22 0x00000016 0x16 796 00:00:23 0x00000017 0x17 797 00:00:24 0x00000018 0x18 798 00:00:25 0x00000019 0x19 799 00:00:26 0x0000001a 0x1a 800 00:00:27 0x0000001b 0x1b 801 00:00:28 0x0000001c 0x1c 802 00:00:29 0x0000001d 0x1d 803 00:00:30 0x0000001e 0x1e 804 00:00:31 0x0000001f 0x1f 805 00:00:32 0x00000020 0x20 806 00:00:33 0x00000021 0x21 807 00:00:34 0x00000022 0x22 808 00:00:35 0x00000023 0x23 809 00:00:36 0x00000024 0x24 810 00:00:37 0x00000025 0x25 811 00:00:38 0x00000026 0x26 812 00:00:39 0x00000027 0x27 813 00:00:40 0x00000028 0x28 814 00:00:41 0x00000029 0x29 815 00:00:42 0x0000002a 0x2a 816 00:00:43 0x0000002b 0x2b 817 00:00:44 0x0000002c 0x2c 818 00:00:45 0x0000002d 0x2d 819 00:00:46 0x0000002e 0x2e 820 00:00:47 0x0000002f 0x2f 821 00:00:48 0x00000030 0x30 822 00:00:49 0x00000031 0x31 823 00:00:50 0x00000032 0x32 824 00:00:51 0x00000033 0x33 825 00:00:52 0x00000034 0x34 826 00:00:53 0x00000035 0x35 827 00:00:54 0x00000036 0x36 828 00:00:55 0x00000037 0x37 829 00:00:56 0x00000038 0x38 830 00:00:57 0x00000039 0x39 831 00:00:58 0x0000003a 0x3a 832 00:00:59 0x0000003b 0x3b 833 00:01:00 0x0000003c 0x3c 834 00:01:01 0x0000003d 0x3d 835 00:01:02 0x0000003e 0x3e 836 00:01:03 0x0000003f 0x3f 837 00:01:04 0x00000040 0x40 838 00:01:05 0x00000041 0x41 839 00:01:06 0x00000042 0x42 840 00:01:07 0x00000043 0x43 841 00:01:08 0x00000044 0x44 842 00:01:09 0x00000045 0x45 843 00:01:10 0x00000046 0x46 844 00:01:11 0x00000047 0x47 845 00:01:12 0x00000048 0x48 846 00:01:13 0x00000049 0x49 847 00:01:14 0x0000004a 0x4a 848 00:01:15 0x0000004b 0x4b 849 00:01:16 0x0000004c 0x4c 850 00:01:17 0x0000004d 0x4d 851 00:01:18 0x0000004e 0x4e 852 00:01:19 0x0000004f 0x4f 853 00:01:20 0x00000050 0x50 854 00:01:21 0x00000051 0x51 855 00:01:22 0x00000052 0x52 856 00:01:23 0x00000053 0x53 857 00:01:24 0x00000054 0x54 858 00:01:25 0x00000055 0x55 859 00:01:26 0x00000056 0x56 860 00:01:27 0x00000057 0x57 861 00:01:28 0x00000058 0x58 862 00:01:29 0x00000059 0x59 863 00:01:30 0x0000005a 0x5a 864 00:01:31 0x0000005b 0x5b 865 00:01:32 0x0000005c 0x5c 866 00:01:33 0x0000005d 0x5d 867 00:01:34 0x0000005e 0x5e 868 00:01:35 0x0000005f 0x5f 869 00:01:36 0x00000060 0x60 870 00:01:37 0x00000061 0x61 871 00:01:38 0x00000062 0x62 872 00:01:39 0x00000063 0x63 873 00:01:40 0x00000064 0x64 874 00:01:41 0x00000065 0x65 875 00:01:42 0x00000066 0x66 876 00:01:43 0x00000067 0x67 877 00:01:44 0x00000068 0x68 878 00:01:45 0x00000069 0x69 879 00:01:46 0x0000006a 0x6a 880 00:01:47 0x0000006b 0x6b 881 00:01:48 0x0000006c 0x6c 882 00:01:49 0x0000006d 0x6d 883 00:01:50 0x0000006e 0x6e 884 00:01:51 0x0000006f 0x6f 885 00:01:52 0x00000070 0x70 886 00:01:53 0x00000071 0x71 887 00:01:54 0x00000072 0x72 888 00:01:55 0x00000073 0x73 889 00:01:56 0x00000074 0x74 890 00:01:57 0x00000075 0x75 891 00:01:58 0x00000076 0x76 892 00:01:59 0x00000077 0x77 893 00:02:00 0x00000078 0x78 894 00:02:01 0x00000079 0x79 895 00:02:02 0x0000007a 0x7a 896 00:02:03 0x0000007b 0x7b 897 00:02:04 0x0000007c 0x7c 898 00:02:05 0x0000007d 0x7d 899 00:02:06 0x0000007e 0x7e 900 00:02:07 0x0000007f 0x7f 901 00:02:08 0x00000080 0x80 902 00:02:24 0x00000090 0x90 903 00:02:40 0x000000a0 0xa0 904 00:02:56 0x000000b0 0xb0 905 00:03:12 0x000000c0 0xc0 906 00:03:28 0x000000d0 0xd0 907 00:03:44 0x000000e0 0xe0 908 00:04:00 0x000000f0 0xf0 909 00:04:16 0x00000100 0x81 910 00:04:48 0x00000120 0x91 911 00:05:20 0x00000140 0xa1 912 00:05:52 0x00000160 0xb1 913 00:06:24 0x00000180 0xc1 914 00:06:56 0x000001a0 0xd1 915 00:07:28 0x000001c0 0xe1 916 00:08:00 0x000001e0 0xf1 917 00:08:32 0x00000200 0x82 918 00:09:36 0x00000240 0x92 919 00:10:40 0x00000280 0xa2 920 00:11:44 0x000002c0 0xb2 921 00:12:48 0x00000300 0xc2 922 00:13:52 0x00000340 0xd2 923 00:14:56 0x00000380 0xe2 924 00:16:00 0x000003c0 0xf2 925 00:17:04 0x00000400 0x83 926 00:19:12 0x00000480 0x93 927 00:21:20 0x00000500 0xa3 928 00:23:28 0x00000580 0xb3 929 00:25:36 0x00000600 0xc3 930 00:27:44 0x00000680 0xd3 931 00:29:52 0x00000700 0xe3 932 00:32:00 0x00000780 0xf3 933 00:34:08 0x00000800 0x84 934 00:38:24 0x00000900 0x94 935 00:42:40 0x00000a00 0xa4 936 00:46:56 0x00000b00 0xb4 937 00:51:12 0x00000c00 0xc4 938 00:55:28 0x00000d00 0xd4 939 00:59:44 0x00000e00 0xe4 940 01:04:00 0x00000f00 0xf4 941 01:08:16 0x00001000 0x85 942 01:16:48 0x00001200 0x95 943 01:25:20 0x00001400 0xa5 944 01:33:52 0x00001600 0xb5 945 01:42:24 0x00001800 0xc5 946 01:50:56 0x00001a00 0xd5 947 01:59:28 0x00001c00 0xe5 948 02:08:00 0x00001e00 0xf5 949 02:16:32 0x00002000 0x86 950 02:33:36 0x00002400 0x96 951 02:50:40 0x00002800 0xa6 952 03:07:44 0x00002c00 0xb6 953 03:24:48 0x00003000 0xc6 954 03:41:52 0x00003400 0xd6 955 03:58:56 0x00003800 0xe6 956 04:16:00 0x00003c00 0xf6 957 04:33:04 0x00004000 0x87 958 05:07:12 0x00004800 0x97 959 05:41:20 0x00005000 0xa7 960 06:15:28 0x00005800 0xb7 961 06:49:36 0x00006000 0xc7 962 07:23:44 0x00006800 0xd7 963 07:57:52 0x00007000 0xe7 964 08:32:00 0x00007800 0xf7 965 09:06:08 0x00008000 0x88 966 10:14:24 0x00009000 0x98 967 11:22:40 0x0000a000 0xa8 968 12:30:56 0x0000b000 0xb8 969 13:39:12 0x0000c000 0xc8 970 14:47:28 0x0000d000 0xd8 971 15:55:44 0x0000e000 0xe8 972 17:04:00 0x0000f000 0xf8 973 18:12:16 0x00010000 0x89 974 20:28:48 0x00012000 0x99 975 22:45:20 0x00014000 0xa9 976 1d 01:01:52 0x00016000 0xb9 977 1d 03:18:24 0x00018000 0xc9 978 1d 05:34:56 0x0001a000 0xd9 979 1d 07:51:28 0x0001c000 0xe9 980 1d 10:08:00 0x0001e000 0xf9 981 1d 12:24:32 0x00020000 0x8a 982 1d 16:57:36 0x00024000 0x9a 983 1d 21:30:40 0x00028000 0xaa 984 2d 02:03:44 0x0002c000 0xba 985 2d 06:36:48 0x00030000 0xca 986 2d 11:09:52 0x00034000 0xda 987 2d 15:42:56 0x00038000 0xea 988 2d 20:16:00 0x0003c000 0xfa 989 3d 00:49:04 0x00040000 0x8b 990 3d 09:55:12 0x00048000 0x9b 991 3d 19:01:20 0x00050000 0xab 992 4d 04:07:28 0x00058000 0xbb 993 4d 13:13:36 0x00060000 0xcb 994 4d 22:19:44 0x00068000 0xdb 995 5d 07:25:52 0x00070000 0xeb 996 5d 16:32:00 0x00078000 0xfb 997 6d 01:38:08 0x00080000 0x8c 998 6d 19:50:24 0x00090000 0x9c 999 7d 14:02:40 0x000a0000 0xac 1000 8d 08:14:56 0x000b0000 0xbc 1001 9d 02:27:12 0x000c0000 0xcc 1002 9d 20:39:28 0x000d0000 0xdc 1003 10d 14:51:44 0x000e0000 0xec 1004 11d 09:04:00 0x000f0000 0xfc 1005 12d 03:16:16 0x00100000 0x8d 1006 13d 15:40:48 0x00120000 0x9d 1007 15d 04:05:20 0x00140000 0xad 1008 16d 16:29:52 0x00160000 0xbd 1009 18d 04:54:24 0x00180000 0xcd 1010 19d 17:18:56 0x001a0000 0xdd 1011 21d 05:43:28 0x001c0000 0xed 1012 22d 18:08:00 0x001e0000 0xfd 1013 24d 06:32:32 0x00200000 0x8e 1014 27d 07:21:36 0x00240000 0x9e 1015 30d 08:10:40 0x00280000 0xae 1016 33d 08:59:44 0x002c0000 0xbe 1017 36d 09:48:48 0x00300000 0xce 1018 39d 10:37:52 0x00340000 0xde 1019 42d 11:26:56 0x00380000 0xee 1020 45d 12:16:00 0x003c0000 0xfe 1021 48d 13:05:04 0x00400000 0x8f 1022 54d 14:43:12 0x00480000 0x9f 1023 60d 16:21:20 0x00500000 0xaf 1024 66d 17:59:28 0x00580000 0xbf 1025 72d 19:37:36 0x00600000 0xcf 1026 78d 21:15:44 0x00680000 0xdf 1027 84d 22:53:52 0x00700000 0xef 1028 91d 00:32:00 0x00780000 0xff (reserved) 1030 Figure 10 1032 Authors' Addresses 1034 Carsten Bormann 1035 Universitaet Bremen TZI 1036 Postfach 330440 1037 Bremen D-28359 1038 Germany 1040 Phone: +49-421-218-63921 1041 Fax: +49-421-218-7000 1042 Email: cabo@tzi.org 1044 Klaus Hartke 1045 Universitaet Bremen TZI 1046 Postfach 330440 1047 Bremen D-28359 1048 Germany 1050 Phone: +49-421-218-63905 1051 Fax: +49-421-218-7000 1052 Email: hartke@tzi.org