idnits 2.17.1 draft-bormann-coap-misc-14.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 801 has weird spacing: '... code mid...' -- The document date (March 28, 2012) is 4411 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: 'RFC2046' is mentioned on line 415, but not defined == Missing Reference: 'RFC3676' is mentioned on line 408, but not defined == Missing Reference: 'RFC5147' is mentioned on line 408, but not defined == Missing Reference: 'I-D.ietf-core-link-format' is mentioned on line 411, but not defined == Missing Reference: 'RFC3023' is mentioned on line 413, but not defined ** Obsolete undefined reference: RFC 3023 (Obsoleted by RFC 7303) == Missing Reference: 'RFC2045' is mentioned on line 415, but not defined == Missing Reference: 'EXIMIME' is mentioned on line 417, but not defined == Missing Reference: 'RFC4627' is mentioned on line 419, but not defined ** Obsolete undefined reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) == Missing Reference: 'RFCXXXX' is mentioned on line 435, but not defined -- Looks like a reference, but probably isn't: '0' on line 1094 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-09 == 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-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-19 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 3 errors (**), 0 flaws (~~), 16 warnings (==), 3 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: September 29, 2012 March 28, 2012 7 Miscellaneous additions to CoAP 8 draft-bormann-coap-misc-14 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 September 29, 2012. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Getting rid of artificial limitations . . . . . . . . . . . . 4 54 2.1. Option Length encoding beyond 270 bytes . . . . . . . . . 4 55 3. Vendor-defined Option . . . . . . . . . . . . . . . . . . . . 6 56 4. Patience, Leisure, and Pledge . . . . . . . . . . . . . . . . 7 57 4.1. Patience . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 4.2. Leisure . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 4.3. Pledge . . . . . . . . . . . . . . . . . . . . . . . . . . 8 60 4.4. Option Formats . . . . . . . . . . . . . . . . . . . . . . 8 61 5. Combining Content-Type and Content-Encoding . . . . . . . . . 10 62 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 64 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 14 65 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 66 9.1. Normative References . . . . . . . . . . . . . . . . . . . 15 67 9.2. Informative References . . . . . . . . . . . . . . . . . . 15 68 Appendix A. The Nursery (Things that still need to ripen a 69 bit) . . . . . . . . . . . . . . . . . . . . . . . . 17 70 A.1. Payload-Length Option . . . . . . . . . . . . . . . . . . 17 71 A.2. URI Authorities with Binary Adresses . . . . . . . . . . . 17 72 A.3. Length-aware number encoding (o256) . . . . . . . . . . . 18 73 A.4. SMS encoding . . . . . . . . . . . . . . . . . . . . . . . 20 74 A.4.1. ASCII-optimized SMS encoding . . . . . . . . . . . . . 21 75 Appendix B. The Cemetery (Things we won't do) . . . . . . . . . . 24 76 B.1. Stateful URI compression . . . . . . . . . . . . . . . . . 24 77 B.2. Beyond 270 bytes in a single option . . . . . . . . . . . 25 78 B.3. Beyond 15 options . . . . . . . . . . . . . . . . . . . . 26 79 B.3.1. Implementation considerations . . . . . . . . . . . . 27 80 B.3.2. What should we do now? . . . . . . . . . . . . . . . . 28 81 B.3.3. Alternatives . . . . . . . . . . . . . . . . . . . . . 28 82 B.3.4. Alternative: Going to a delimiter model . . . . . . . 28 83 B.4. Implementing the option delimiter for 15 or more 84 options . . . . . . . . . . . . . . . . . . . . . . . . . 28 85 Appendix C. Experimental Options . . . . . . . . . . . . . . . . 30 86 C.1. Options indicating absolute time . . . . . . . . . . . . . 30 87 C.2. Representing Durations . . . . . . . . . . . . . . . . . . 31 88 C.3. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 32 89 C.4. Pseudo-Floating Point . . . . . . . . . . . . . . . . . . 33 90 C.5. A Duration Type for CoAP . . . . . . . . . . . . . . . . . 34 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 41 93 1. Introduction 95 The CoRE WG is tasked with standardizing an Application Protocol for 96 Constrained Networks/Nodes, CoAP [I-D.ietf-core-coap]. This protocol 97 is intended to provide RESTful [REST] services not unlike HTTP 98 [RFC2616], while reducing the complexity of implementation as well as 99 the size of packets exchanged in order to make these services useful 100 in a highly constrained network of themselves highly constrained 101 nodes. 103 This objective requires restraint in a number of sometimes 104 conflicting ways: 106 o reducing implementation complexity in order to minimize code size, 108 o reducing message sizes in order to minimize the number of 109 fragments needed for each message (in turn to maximize the 110 probability of delivery of the message), the amount of 111 transmission power needed and the loading of the limited-bandwidth 112 channel, 114 o reducing requirements on the environment such as stable storage, 115 good sources of randomness or user interaction capabilities. 117 This draft attempts to address a number of problems not yet 118 adequately solved in [I-D.ietf-core-coap]. The solutions proposed to 119 these problems are somewhat interrelated and are therefore presented 120 in one draft. 122 The appendix contains the "CoAP cemetery" (possibly later to move 123 into its own draft), documenting roads that the WG decided not to 124 take, in order to spare readers from reinventing them in vain. 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 128 document are to be interpreted as described in [RFC2119]. 130 The term "byte" is used in its now customary sense as a synonym for 131 "octet". 133 2. Getting rid of artificial limitations 135 _Artificial limitations_ are limitations of a protocol or system that 136 are not rooted in limitations of actual capabilities, but in 137 arbitrary design decisions. Proper system design tries to avoid 138 artificial limitations, as these tend to cause complexity in systems 139 that need to work with these limitations. 141 E.g., the original UNIX filesystem had an artificial limitation of 142 the length of a path name component to 14 bytes. This led to all 143 kinds of workarounds in programs that manipulate file names: E.g., 144 systematically replacing a ".el" extension in a filename with a 145 ".elc" for the compiled file might exceed the limit, so all ".el" 146 files were suddenly limited to 13-byte filenames. 148 Note that, today, there still is a limitation in most file system 149 implementations, typically at 255. This just happens to be high 150 enough to rarely be of real-world concern; we will refer to this case 151 as a "painless" artificial limitation. 153 CoAP-08 had two highly recognizable artificial limitations in its 154 protocol encoding 156 o The number of options in a single message is limited to 15 max. 158 o The length of an option is limited to 270 max. 160 It has been argued that the latter limitation causes few problems, 161 just as the 255-byte path name component limitation in filenames 162 today causes few problems. Appendix B.2 provided a design to extend 163 this; as a precaution to future extensions of this kind, the current 164 encoding for length 270 (eight ones in the extension byte) could be 165 marked as reserved today. Since, Matthias Kovatsch has proposed a 166 simpler scheme that seems to gain favor in the WG, see Section 2.1. 168 The former limitation has been solved in CoAP-09. A historical 169 discussion of other approaches for going beyond 15 options is in 170 Appendix B.3. Appendix B.4 discusses implementation. 172 2.1. Option Length encoding beyond 270 bytes 174 For option lengths beyond 270 bytes, we reserve the value 255 of an 175 extension byte to mean "add 255, read another extension byte" 176 Figure 1. While this causes the length of the option header to grow 177 linearly with the size of the option value, only 0.4 % of that size 178 is used. With a focus on short options, this encoding is justified. 180 for 15..269: 181 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 182 | Option Delta | 1 1 1 1 | Length - 15 | 183 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 184 | Option Value ... 185 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 187 for 270..524: 188 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 189 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 190 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 191 | Length - 270 | Option Value ... 192 +---+---+---+---+---+---+---+---+ 193 | 194 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 196 for 525..779: 197 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 198 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 199 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 200 | 1 1 1 1 1 1 1 1 | Length - 525 | 201 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 202 | Option Value ... 203 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 205 for 780..1034: 206 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 207 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 208 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 209 | 1 1 1 1 1 1 1 1 | 1 1 1 1 1 1 1 1 | 210 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 211 | Length - 780 | Option Value ... 212 +---+---+---+---+---+---+---+---+ 213 | 214 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 216 and so on... 218 Figure 1: Options beyond 270 bytes 220 In the process, the maximum length of all options that are currently 221 set at 270 should now be set to infinite. With the artificial limit 222 gone, Uri-Proxy should now be restored to be a non-repeatable option. 224 3. Vendor-defined Option 226 To enable experimentation and community-specific options, option 227 number 14 (the first NOP option) can also be used as a vendor-defined 228 option. For this application, the option value has one or more 229 bytes, the semantics of which are defined by prior agreement between 230 the communicating partners. 232 It is RECOMMENDED to start the option value with a unique identifier, 233 e.g., the SDNV [RFC5050] of the enterprise number of the organisation 234 defining the option, possibly followed by additional discriminating 235 bits or bytes as defined by the organisation. 237 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 238 |1 0 0 0 0 0 0 1|0 1 1 1 0 0 1 1| private opt-id| value... | 239 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 240 \___SDNV of enterprise number___/ 242 Figure 2: Example option value for vendor-defined option 244 Note that a Vendor-defined Option cannot be empty, not only because 245 there would be no space for the SDNV, but in particular as the empty 246 option 14 is reserved for fenceposting ([I-D.ietf-core-coap], section 247 3.2). (Obviously, once a Vendor-defined Option is in use, there is 248 never a need for a fence-post for option number 14.) 250 Vendor-defined Options are elective. 252 The Vendor-defined Option is repeatable. 254 +-----+----------+--------+-------------+---------+---------+ 255 | No. | C/E | Name | Format | Length | Default | 256 +-----+----------+--------+-------------+---------+---------+ 257 | 14 | Elective | Vendor | (see below) | 1-270 B | (empty) | 258 +-----+----------+--------+-------------+---------+---------+ 260 4. Patience, Leisure, and Pledge 262 A number of options might be useful for controlling the timing of 263 interactions. 265 (This section also addresses core-coap ticket #177.) 267 4.1. Patience 269 A client may have a limited time period in which it can actually make 270 use of the response for a request. Using the Patience option, it can 271 provide an (elective) indication how much time it is willing to wait 272 for the response from the server, giving the server license to ignore 273 or reject the request if it cannot fulfill it in this period. 275 If the server knows early that it cannot fulfill the request in the 276 time requested, it MAY indicate this with a 5.04 "Timeout" response. 277 For non-safe methods (such as PUT, POST, DELETE), the server SHOULD 278 indicate whether it has fulfilled the request by either responding 279 with 5.04 "Timeout" (and not further processing the request) or by 280 processing the request normally. 282 Note that the value of the Patience option should be chosen such that 283 the client will be able to make use of the result even in the 284 presence of the expected network delays for the request and the 285 response. Similarly, when a proxy receives a request with a Patience 286 option and cannot fulfill that request from its cache, it may want to 287 adjust the value of the option before forwarding it to an upstream 288 server. 290 (TBD: The various cases that arise when combining Patience with 291 Observe.) 293 The Patience option is elective. Hence, a client MUST be prepared to 294 receive a normal response even after the chosen Patience period (plus 295 an allowance for network delays) has elapsed. 297 4.2. Leisure 299 Servers generally will compute an internal value that we will call 300 Leisure, which indicates the period of time that will be used for 301 responding to a request. A Patience option, if present, can be used 302 as an upper bound for the Leisure. Leisure may be non-zero for 303 congestion control reasons, in particular for responses to multicast 304 requests. For these, the server should have a group size estimate G, 305 a target rate R (which both should be chosen conservatively) and an 306 estimated response size S; a rough lower bound for Leisure can then 307 be computed as follows: 309 lb_Leisure = S * G / R 311 Figure 3: Computing a lower bound for the Leisure 313 E.g., for a multicast request with link-local scope on an 2.4 GHz 314 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 315 conservatively) set to 100, S to 100 bytes, and the target rate to 8 316 kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10 317 seconds. 319 To avoid response implosion, responses to multicast requests SHOULD 320 be dithered within a Leisure period chosen by the server to fall 321 between these two bounds. 323 Currently, we don't foresee a need to signal a value for Leisure from 324 client to server (beyond the signalling provided by Patience) or from 325 server to client, but an appropriate Option might be added later. 327 4.3. Pledge 329 In a basic observation relationship [I-D.ietf-core-observe], the 330 server makes a pledge to keep the client in the observation 331 relationship for a resource at least until the max-age for the 332 resource is reached. 334 To save the client some effort in re-establishing observation 335 relationships each time max-age is reached, the server MAY want to 336 extend its pledge beyond the end of max-age by signalling in a 337 response/notification an additional time period using the Pledge 338 Option, in parallel to the Observe Option. 340 The Pledge Option MUST NOT be used unless the server can make a 341 reasonable promise not to lose the observation relationship in this 342 time frame. 344 Currently, we don't foresee a need to signal a value for Pledge from 345 client to server, but an appropriate behavior might be added later 346 for this option when sent in a request. 348 4.4. Option Formats 350 +-----+----------+----------+-----------------+--------+---------+ 351 | No. | C/E | Name | Format | Length | Default | 352 +-----+----------+----------+-----------------+--------+---------+ 353 | 22 | Elective | Patience | Duration in mis | 1 B | (none) | 354 | | | | | | | 355 | 24 | Elective | Pledge | Duration in s | 1 B | 0 | 356 +-----+----------+----------+-----------------+--------+---------+ 358 All timing options use the Duration data type (see Appendix C.2), 359 however Patience (and Leisure, if that ever becomes an option) uses a 360 timebase of mibiseconds (mis = 1/1024 s) instead of seconds. (This 361 reduces the range of the Duration from ~ 91 days to 128 minutes.) 363 Implementation note: As there are no strong accuracy requirements on 364 the clocks employed, making use of any existing time base of 365 milliseconds is a valid implementation approach (2.4 % off). 367 None of the options may be repeated. 369 5. Combining Content-Type and Content-Encoding 371 (This section addresses core-coap ticket #181.) 373 There may be rare cases where the Content-Encoding concept of HTTP 374 may be applicable to CoAP as well. Instead of defining another 375 option to carry that information, the decision was to combine it with 376 the Internet Media Type into the single Option unfortunately called 377 Content-Type. 379 In Section 5.10.4, add behind: 381 5.10.4. Content-Type 383 The Content-Type Option indicates the representation format of the 384 message payload. The representation format is given as a numeric 385 media type identifier that is defined in the CoAP Media Type registry 386 (Section 11.3). No default value is assumed in the absence of the 387 option. 389 Figure 4 391 the new text: 393 Apart from indicating the equivalent of an HTTP Content-Type, a media 394 type identifier registry entry may also incorporate the equivalent of 395 one or more Content-Encodings [RFC2616]. 397 and continue: 399 This option is "critical". It MUST NOT occur more than once. 401 Figure 5 403 In Section 11.3, change table 5 to: 405 +--------------------------+----+-----+-----------------------------+ 406 | Media type | CE | Id. | Reference | 407 +--------------------------+----+-----+-----------------------------+ 408 | text/plain; | -- | 0 | [RFC2046][RFC3676][RFC5147] | 409 | charset=utf-8 | | | | 410 | | | | | 411 | application/link-format | -- | 40 | [I-D.ietf-core-link-format] | 412 | | | | | 413 | application/xml | -- | 41 | [RFC3023] | 414 | | | | | 415 | application/octet-stream | -- | 42 | [RFC2045][RFC2046] | 416 | | | | | 417 | application/exi | -- | 47 | [EXIMIME] | 418 | | | | | 419 | application/json | -- | 50 | [RFC4627] | 420 +--------------------------+----+-----+-----------------------------+ 422 Table 1: CoAP Media Types (CE = Content-Encoding) 424 6. IANA Considerations 426 This draft adds option numbers to Table 2 of [I-D.ietf-core-coap]: 428 +--------+----------+-----------+ 429 | Number | Name | Reference | 430 +--------+----------+-----------+ 431 | 14 | Vendor | [RFCXXXX] | 432 | | | | 433 | 22 | Patience | [RFCXXXX] | 434 | | | | 435 | 24 | Pledge | [RFCXXXX] | 436 +--------+----------+-----------+ 438 Table 2: New CoAP Option Numbers 440 7. Security Considerations 442 TBD. 444 8. Acknowledgements 446 This work was partially funded by the Klaus Tschira Foundation. 448 Of course, much of the content of this draft is the result of 449 discussions with the [I-D.ietf-core-coap] authors. 451 Patience and Leisure were influenced by a mailing list discussion 452 with Esko Dijk, Kepeng Li, and Salvatore Loreto - thanks! 454 9. References 456 9.1. Normative References 458 [I-D.ietf-core-coap] 459 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 460 "Constrained Application Protocol (CoAP)", 461 draft-ietf-core-coap-09 (work in progress), March 2012. 463 [I-D.ietf-core-observe] 464 Hartke, K., "Observing Resources in CoAP", 465 draft-ietf-core-observe-05 (work in progress), March 2012. 467 [I-D.ietf-httpbis-p1-messaging] 468 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 469 1: URIs, Connections, and Message Parsing", 470 draft-ietf-httpbis-p1-messaging-19 (work in progress), 471 March 2012. 473 [I-D.ietf-httpbis-p4-conditional] 474 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 475 4: Conditional Requests", 476 draft-ietf-httpbis-p4-conditional-19 (work in progress), 477 March 2012. 479 [I-D.ietf-httpbis-p6-cache] 480 Fielding, R., Lafon, Y., Nottingham, M., and J. Reschke, 481 "HTTP/1.1, part 6: Caching", 482 draft-ietf-httpbis-p6-cache-19 (work in progress), 483 March 2012. 485 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 486 Requirement Levels", BCP 14, RFC 2119, March 1997. 488 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 489 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 490 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 492 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 493 Encodings", RFC 4648, October 2006. 495 9.2. Informative References 497 [REST] Fielding, R., "Architectural Styles and the Design of 498 Network-based Software Architectures", 2000. 500 [RFC1924] Elz, R., "A Compact Representation of IPv6 Addresses", 501 RFC 1924, April 1996. 503 [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol 504 Specification", RFC 5050, November 2007. 506 [RFC6256] Eddy, W. and E. Davies, "Using Self-Delimiting Numeric 507 Values in Protocols", RFC 6256, May 2011. 509 Appendix A. The Nursery (Things that still need to ripen a bit) 511 A.1. Payload-Length Option 513 Not all transport mappings may provide an unambiguous length of the 514 CoAP message. For UDP, it may also be desirable to pack more than 515 one CoAP message into one UDP payload (aggregation); in that case, 516 for all but the last message there needs to be a way to delimit the 517 payload of that message. 519 This can be solved using a new option, the Payload-Length option. If 520 this option is present, the value of this option is an unsigned 521 integer giving the length of the payload of the message (note that 522 this integer can be zero for a zero-length payload, which can in turn 523 be represented by a zero-length option value). (In the UDP 524 aggregation case, what would have been in the payload of this message 525 after "payload-length" bytes is then actually one or more additional 526 messages.) 528 A.2. URI Authorities with Binary Adresses 530 One problem with the way URI authorities are represented in the URI 531 syntax is that the authority part can be very bulky if it encodes an 532 IPv6 address in ASCII. 534 Proposal: Provide an option "Uri-Authority-Binary" that can be an 535 even number of bytes between 2 and 18 except 12 or 14. 537 o If the number of bytes is 2, the destination IP address of the 538 packet transporting the CoAP message is implied. 540 o If the number of bytes is 4 or 6, the first four bytes of the 541 option value are an IPv4 address in binary. 543 o If the number of bytes is 8 or 10, the first eight bytes are the 544 lower 64 bits of an IPv6 address; the upper eight bytes are 545 implied from the destination address of the packet transporting 546 the CoAP message. 548 o If the number of bytes is 16 or 18, the first 16 bytes are an IPv6 549 address. 551 o If two more bytes remain, this is a port number (as always in 552 network byte order). 554 The resulting authority is (conceptually translated into ASCII and) 555 used in place of an Uri-Authority option, or inserted into a Proxy- 556 Uri. Examples: 558 +-------------+------------------+---------+------------------------+ 559 | Proxy-Uri | Uri-Authority-Bi | Uri-Pat | URI | 560 | | nary | h | | 561 +-------------+------------------+---------+------------------------+ 562 | (none) | (none) | (none) | "/" | 563 | | | | | 564 | (none) | (none) | 'temp' | "/temp" | 565 | | | | | 566 | (none) | 2 bytes: 61616 | 'temp' | "coap://[DA]:61616/tem | 567 | | | | p" | 568 | | | | | 569 | (none) | 16 bytes: | temp | "coap://[2000::1]/temp | 570 | | 2000::1 | | " | 571 | | | | | 572 | 'http://' | 10 bytes: | (none) | "http://[DA::123:45]:6 | 573 | | ::123:45 + 616 | | 16" | 574 | | | | | 575 | 'http:///te | 18 bytes: | (none) | "http://[2000::1]:616/ | 576 | mp' | 2000::1 + 616 | | temp" | 577 +-------------+------------------+---------+------------------------+ 579 A.3. Length-aware number encoding (o256) 581 The number encoding defined in Appendix A of [I-D.ietf-core-coap] has 582 one significant flaw: Every number has an infinite number of 583 representations, which can be derived by adding leading zero bytes. 584 This runs against the principle of minimizing unnecessary choice. 585 The resulting uncertainty in encoding ultimately leads to unnecessary 586 interoperability failures. (It also wastes a small fraction of the 587 encoding space, i.e., it wastes bytes.) 589 We could solve the first, but not the second, by outlawing leading 590 zeroes, but then we have to cope with error cases caused by illegal 591 values, another source of interoperability problems. 593 The number encoding "o256" defined in this section avoids this flaw. 594 The suggestion is not to replace CoAP's "uint" encoding wholesale 595 (CoAP is already too widely implemented for such a change), but to 596 consider this format for new options. 598 The basic requirements for such an encoding are: 600 o numbers are encoded as a sequence of zero or more bytes 602 o each number has exactly one encoding 604 o for a < b, encoding-size(a) <= encoding-size(b) -- i.e., with 605 larger numbers, the encoding only gets larger, never smaller 606 again. 608 o within each encoding size (0 bytes, 1 byte, etc.), lexicographical 609 ordering of the bytes is the same as numeric ordering 611 Obviously, there is only one encoding that satisfies all these 612 requirements. As illustrated by Figure 6, this is unambiguously 613 derived by 615 1. enumerating all possible byte sequences, ordered by length and 616 within the same length in lexicographic ordering, and, 618 2. assigning sequential cardinals. 620 0x'' -> 0 621 0x'00' -> 1 622 0x'01' -> 2 623 0x'02' -> 3 624 ... 625 0x'fe' -> 255 626 0x'ff' -> 256 627 0x'0000' -> 257 628 0x'0001' -> 258 629 ... 630 0x'fefd' -> 65534 631 0x'fefe' -> 65535 632 0x'feff' -> 65536 633 ... 634 0x'ffff' -> 65792 635 0x'000000' -> 65793 636 0x'000001' -> 65794 638 Figure 6: Enumerating byte sequences by length and then lexicographic 639 order 641 This results in an exceedingly simple algorithm: each byte is 642 interpreted in the base-256 place-value system, but stands for a 643 number between 1 and 256 instead of 0 to 255. We therefore call this 644 encoding "o256" (one-to-256). 0 is always encoded in zero bytes; 1 to 645 256 is one byte, 257 (0x101) to 65792 (0x10100) is two bytes, 65793 646 (0x10101) to 16843008 (0x1010100) is three bytes, etc. 648 To further illustrate the algorithmic simplicity, pseudocode for 649 encoding and decoding is given in Figure 7 and Figure 8, respectively 650 (in the encoder, "prepend" stands for adding a byte at the _leading_ 651 edge, the requirement for which is a result of the network byte 652 order). Note that this differs only in a single subtraction/addition 653 (resp.) of one from the canonical algorithm for Appendix A uints. 655 while num > 0 656 num -= 1 657 prepend(num & 0xFF) 658 num >>= 8 659 end 661 Figure 7: o256 encoder (pseudocode) 663 num = 0 664 each_byte do |b| 665 num <<= 8 666 num += b + 1 667 end 669 Figure 8: o256 decoder (pseudocode) 671 On a more philosophical note, it can be observed that o256 solves the 672 inverse problem of Self-Delimiting Numeric Values (SDNV) [RFC6256]: 673 SDNV encodes variable-length numbers together with their length 674 (allowing decoding without knowing their length in advance, deriving 675 delimiting information from the number encoding). o256 encodes 676 variable-length numbers when there is a way to separately convey the 677 length (as in CoAP options), encoding (and later deriving) a small 678 part of the numeric value into/from that size information. 680 A.4. SMS encoding 682 For use in SMS applications, CoAP messages can be transferred using 683 SMS binary mode. However, there is operational experience showing 684 that some environments cannot successfully send a binary mode SMS. 686 For transferring SMS in character mode (7-bit characters), base64- 687 encoding [RFC4648] is an obvious choice. 3 bytes of message (24 bits) 688 turn into 4 characters, which cosume 28 bits. The overall overhead 689 is approximately 17 %; the maximum message size is 120 bytes (160 SMS 690 characters). 692 If a more compact encoding is desired, base85 encoding can be 693 employed (however, probably not the version defined in [RFC1924] -- 694 instead, the version used in tools such as btoa and PDF should be 695 chosen). However, this requires division operations. Also, the 696 base85 character set includes several characters that cannot be 697 transferred in a single 7-bit unit in SMS and/or are known to cause 698 operational problems. A modified base85 character set can be defined 699 to solve the latter problem. 4 bytes of message (32 bits) turn into 5 700 characters, which consume 35 bits. The overall overhead is 701 approximately 9.3 %; the resulting maximum message size is 128 bytes 702 (160 SMS characters). 704 Base64 and base85 do not make use of the fact that much CoAP data 705 will be ASCII-based. Therefore, we define the following experimental 706 SMS encoding. 708 A.4.1. ASCII-optimized SMS encoding 710 Not all 128 theoretically possible SMS characters are operationally 711 free of problems. We therefore define: 713 Shunned code characters: @ sign, as it maps to 0x00 715 LF and CR signs (0x0A, 0x0D) 717 uppercase C cedilla (0x09), as it is often mistranslated in 718 gateways 720 ESC (0x1B), as it is used in certain character combinations only 722 Some ASCII characters cannot be transferred in the base SMS character 723 set, as their code positions are taken by non-ASCII characters. 724 These are simply encoded with their ASCII code positions, e.g., an 725 underscore becomes a section mark (even though underscore has a 726 different code position in the SMS character set). 728 Equivalently translated input bytes: $, @, [, \, ], ^, _, `, {, |, 729 }, ~, DEL 731 In other words, bytes 0x20 to 0x7F are encoded into the same code 732 positions in the 7-bit character set. 734 Out of the remaining code characters, the following SMS characters 735 are available for encoding: 737 Non-equivalently translated (NET) code characters: 0x01 to 0x08, (8 738 characters) 740 0x0B, 0x0C, (2 characters) 742 0x0E to 0x1A, (13 characters) 744 0x1C to 0x1F, (4 characters) 746 Of the 27 NET code characters, 18 are taken as prefix characters (see 747 below), and 8 are defined as directly translated characters: 749 Directly translated bytes: Equivalently translated input bytes are 750 represented as themselves 752 0x00 to 0x07 are represented as 0x01 to 0x08 754 This leaves 0x08 to 0x1F and 0x80 to 0xFF. Of these, the bytes 0x80 755 to 0x87 and 0xA0 to 0xFF are represented as the bytes 0x00 to 0x07 756 (represented by characters 0x01 to 0x08) and 0x20 to 0x7F, with a 757 prefix of 1 (see below). The characters 0x08 to 0x1F are represented 758 as the characters 0x28 to 0x3F with a prefix of 2 (see below). The 759 characters 0x88 to 0x9F are represented as the characters 0x48 to 760 0x5F with a prefix of 2 (see below). (Characters 0x01 to 0x08, 0x20 761 to 0x27, 0x40 to 0x47, and 0x60 to 0x7f with a prefix of 2 are 762 reserved for future extensions, which could be used for some 763 backreferencing or run-length compression.) 765 Bytes that do not need a prefix (directly translated bytes) are sent 766 as is. Any byte that does need a prefix (i.e., 1 or 2) is preceded 767 by a prefix character, which provides a prefix for this and the 768 following two bytes as follows: 770 +------+-----+---+------+-----+ 771 | 0x0B | 100 | | 0x15 | 200 | 772 +------+-----+---+------+-----+ 773 | 0x0C | 101 | | 0x16 | 201 | 774 | | | | | | 775 | 0x0E | 102 | | 0x17 | 202 | 776 | | | | | | 777 | 0x0F | 110 | | 0x18 | 210 | 778 | | | | | | 779 | 0x10 | 111 | | 0x19 | 211 | 780 | | | | | | 781 | 0x11 | 112 | | 0x1A | 212 | 782 | | | | | | 783 | 0x12 | 120 | | 0x1C | 220 | 784 | | | | | | 785 | 0x13 | 121 | | 0x1D | 221 | 786 | | | | | | 787 | 0x14 | 122 | | 0x1E | 222 | 788 +------+-----+---+------+-----+ 790 (This leaves one non-shunned character, 0x1F, for future extension.) 792 The coding overhead of this encoding for random bytes is similar to 793 Base85, without the need for a division/multiplication. For bytes 794 that are mostly ASCII characters, the overhead can easily become 795 negative. (Conversely, for bytes that are more likely to be non- 796 ASCII than in a random sequence of bytes, the overhead becomes 797 greater.) 799 So, for instance, for the CoAP message in Figure 9: 801 ver tt code mid 802 1 ack 2.05 17033 803 content_type 40 804 token sometok 805 3c 2f 3e 3b 74 69 74 6c 65 3d 22 47 65 6e 65 72 |;title="Gener| 806 61 6c 20 49 6e 66 6f 22 3b 63 74 3d 30 2c 3c 2f |al Info";ct=0,;if="clock"| 808 3b 72 74 3d 22 54 69 63 6b 73 22 3b 74 69 74 6c |;rt="Ticks";titl| 809 65 3d 22 49 6e 74 65 72 6e 61 6c 20 43 6c 6f 63 |e="Internal Cloc| 810 6b 22 3b 63 74 3d 30 2c 3c 2f 61 73 79 6e 63 3e |k";ct=0,| 811 3b 63 74 3d 30 |;ct=0 | 813 Figure 9: CoAP response message as captured and decoded 815 The 116 byte unencoded message is shown as ASCII characters in 816 Figure 10 (\xDD stands for the byte with the hex digits DD): 818 bEB\x89\x11(\xA7sometok;title="General Info";ct=0, 819 ;if="clock";rt="Ticks";title="Internal Clock";ct=0,;ct=0 821 Figure 10: CoAP response message shown as unencoded characters 823 The equivalent SMS encoding is shown as equivalent-coded SMS 824 characters in Figure 11 (7 bits per character, \x12 is a 220 prefix 825 and \x0B is a 100 prefix, the rest is shown in equivalent encoding), 826 adding two characters of prefix overhead, for a total length of 118 827 7-bit characters or 104 (103.25 plus padding) bytes: 829 bEB\x12I1(\x0B'sometok;title="General Info";ct=0, 830 ;if="clock";rt="Ticks";title="Internal Clock";ct=0,;ct=0 832 Figure 11: CoAP response message shown as SMS-encoded characters 834 Appendix B. The Cemetery (Things we won't do) 836 This annex documents roads that the WG decided not to take, in order 837 to spare readers from reinventing them in vain. 839 B.1. Stateful URI compression 841 Is the approximately 25 % average saving achievable with Huffman- 842 based URI compression schemes worth the complexity? Probably not, 843 because much higher average savings can be achieved by introducing 844 state. 846 Henning Schulzrinne has proposed for a server to be able to supply a 847 shortened URI once a resource has been requested using the full- 848 length URI. Let's call such a shortened referent a _Temporary 849 Resource Identifier_, _TeRI_ for short. This could be expressed by a 850 response option as shown in Figure 12. 852 0 853 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 854 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 855 | duration | TeRI... 856 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 858 Figure 12: Option for offering a TeRI in a response 860 The TeRI offer option indicates that the server promises to offer 861 this resources under the TeRI given for at least the time given as 862 the duration. Another TeRI offer can be made later to extend the 863 duration. 865 Once a TeRI for a URI is known (and still within its lifetime), the 866 client can supply a TeRI instead of a URI in its requests. The same 867 option format as an offer could be used to allow the client to 868 indicate how long it believes the TeRI will still be valid (so that 869 the server can decide when to update the lifetime duration). TeRIs 870 in requests could be distinguished from URIs e.g. by using a 871 different option number. 873 Proposal: Add a TeRI option that can be used in CoAP requests and 874 responses. 876 Add a way to indicate a TeRI and its duration in a link-value. 878 Do not add any form of stateless URI encoding. 880 Benefits: Much higher reduction of message size than any stateless 881 URI encoding could achieve. 883 As the use of TeRIs is entirely optional, minimal complexity nodes 884 can get by without implementing them. 886 Drawbacks: Adds considerable state and complexity to the protocol. 888 It turns out that real CoAP URIs are short enough that TeRIs are 889 not needed. 891 (Discuss the security implications of TeRIs.) 893 B.2. Beyond 270 bytes in a single option 895 The authors would argue that 270 as the maximum length of an option 896 is already beyond the "painless" threshold. 898 If that is not the consensus of the WG, the scheme can easily be 899 extended as in Figure 13: 901 for 15..269: 902 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 903 | Option Delta | 1 1 1 1 | Length - 15 | 904 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 905 | Option Value ... 906 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 908 for 270..65805: 909 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 910 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 911 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 912 | Length - 270 (in network byte order) | 913 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 914 | Option Value ... 915 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 917 Figure 13: Ridiculously Long Option Header 919 The infinite number of obvious variations on this scheme are left as 920 an exercise to the reader. 922 Again, as a precaution to future extensions, the current encoding for 923 length 270 (eight ones in the extension byte) could be marked as 924 reserved today. 926 B.3. Beyond 15 options 928 (This section keeps discussion that is no longer needed as we have 929 agreed to do what is documented in Appendix B.4). 931 The limit of 15 options is motivated by the fixed four-bit field "OC" 932 that is used for indicating the number of options in the fixed-length 933 CoAP header (Figure 14). 935 0 1 2 3 936 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 937 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 938 |Ver| T | OC | Code | Message ID | 939 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 940 | Options (if any) ... 941 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 942 | Payload (if any) ... 943 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 945 Figure 14: Four-byte fixed header in a CoAP Message 947 Note that there is another fixed four-bit field in CoAP: the option 948 length (Figure 15 - note that this figure is not to the same scale as 949 the previous figure): 951 0 1 2 3 4 5 6 7 952 +---+---+---+---+---+---+---+---+ 953 | Option Delta | Length | for 0..14 954 +---+---+---+---+---+---+---+---+ 955 | Option Value ... 956 +---+---+---+---+---+---+---+---+ 958 Figure 15: Short Option Header 960 Since 15 is inacceptable for a maximum option length, the all-ones 961 value (15) was taken out of the set of allowable values for the short 962 header, and a long header was introduced that allows the insertion of 963 an extension byte (Figure 16): 965 for 15..270: 966 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 967 | Option Delta | 1 1 1 1 | Length - 15 | 968 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 969 | Option Value ... 970 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 972 Figure 16: Long Option Header 974 We might want to use the same technique for the CoAP header as well. 975 There are two obvious places where the extension byte could be 976 placed: 978 1. right after the byte carrying the OC field, so the structure is 979 the same as for the option header; 981 2. right after the fixed-size CoAP header. 983 Both solutions lose the fixed-size-ness of the CoAP header. 985 Solution 1 has the disadvantage that the CoAP header is also changing 986 in structure: The extension byte is wedged between the first and the 987 second byte of the CoAP header. This is unfortunate, as the number 988 of options only comes into play when the option processing begins, so 989 it is more natural to use solution 2 (Figure 17): 991 0 1 2 3 992 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 993 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 994 |Ver| T | 15 | Code | Message ID | 995 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 996 | OC - 15 | Options ... 997 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 998 | Payload (if any) ... 999 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1001 Figure 17: Extended header for CoAP Messages with 15+ options 1003 This would allow for up to 270 options in a CoAP message, which is 1004 very likely way beyond the "painless" threshold. 1006 B.3.1. Implementation considerations 1008 For a message decoder, this extension creates relatively little pain, 1009 as the number of options only becomes interesting when the encoding 1010 turns to the options part of the message, which is then simply lead 1011 in by the extension byte if the four-bit field is 15. 1013 For a message encoder, this extension is not so rosy. If the encoder 1014 is constructing the message serially, it may not know in advance 1015 whether the number of options will exceed 14. None of the following 1016 implementation strategies is particularly savory, but all of them do 1017 work: 1019 1. Encode the options serially under the assumption that the number 1020 of options will be 14 or less. When the 15th option needs to be 1021 encoded, abort the option encoding, and restart it from scratch 1022 one byte further to the left. 1024 2. Similar to 1, except that the bytes already encoded are all moved 1025 one byte to right, the extension byte is inserted, and the option 1026 encoding process is continued. 1028 3. The encoder always leaves space for the extension byte (at least 1029 if it can't prove the number will be less thatn 14). If the 1030 extension byte is not needed, an Option 0 with length 0 is 1031 encoded instead (i.e., one byte is wasted - this option is 1032 elective and will be ignored by the receiver). 1034 As a minimum, to enable strategy 3, the option 0 should be reserved 1035 at least for the case of length=0. 1037 B.3.2. What should we do now? 1039 As a minimum proposal for the next version of CoAP, the value 15 for 1040 OC should be marked as reserved today. 1042 B.3.3. Alternatives 1044 One alternative that has been discussed previously is to have an 1045 "Options" Option, which allows the carriage of multiple options in 1046 the belly of a single one. This could also be used to carry more 1047 than 15 options. However: 1049 o The conditional introduction of an Options option has 1050 implementation considerations that are likely to be more severe 1051 than the ones listed above; 1053 o since 270 bytes may not be enough for the encoding of _all_ 1054 options, the "Options" option would need to be repeatable. This 1055 creates many different ways to encode the same message, leading to 1056 combinatorial explosion in test cases for ensuring 1057 interoperability. 1059 B.3.4. Alternative: Going to a delimiter model 1061 Another alternative is to spend the additional byte not as an 1062 extended count, but as an option terminator. 1064 B.4. Implementing the option delimiter for 15 or more options 1065 Implementation note: As can be seen from the proof of concept code 1066 in Figure 18, the actual implementation cost for a decoder is 1067 around 4 lines of code (or about 8-10 machine code instructions). 1069 while numopt > 0 1070 nextbyte = ... get next byte 1072 if numopt == 15 # new 1073 break if nextbyte == 0xF0 # new 1074 else # new 1075 numopt -= 1 1076 end # new 1078 ... decode the delta and length from nextbyte and handle them 1079 end 1081 Figure 18: Implementing the Option Terminator 1083 Similarly, creating the option terminator needs about four more lines 1084 (not marked "old" in the C code in Figure 19). 1086 b0 = 0x40 + (tt << 4); /* old */ 1087 buffer[0] = b0 + 15; /* guess first byte */ 1089 .... encode options .... /* old */ 1091 if (option_count >= 15 || first_fragment_already_shipped) 1092 buffer[pos++] = 0xF0; /* use delimiter */ 1093 else /* save a byte: */ 1094 buffer[0] = b0 + option_count; /* old: backpatch */ 1096 Figure 19: Creating the Option Terminator 1098 Appendix C. Experimental Options 1100 This annex documents proposals that need significant additional 1101 discussion before they can become part of (or go back to) the main 1102 CoAP specification. They are not dead, but might die if there turns 1103 out to be no good way to solve the problem. 1105 C.1. Options indicating absolute time 1107 HTTP has a number of headers that may indicate absolute time: 1109 o "Date", defined in Section 14.18 in [RFC2616] (Section 9.3 in 1110 [I-D.ietf-httpbis-p1-messaging]), giving the absolute time a 1111 response was generated; 1113 o "Last-Modified", defined in Section 14.29 in [RFC2616], (Section 1114 6.6 in [I-D.ietf-httpbis-p4-conditional], giving the absolute time 1115 of when the origin server believes the resource representation was 1116 last modified; 1118 o "If-Modified-Since", defined in Section 14.25 in [RFC2616], 1119 "If-Unmodified-Since", defined in Section 14.28 in [RFC2616], and 1120 "If-Range", defined in Section 14.27 in [RFC2616] can be used to 1121 supply absolute time to gate a conditional request; 1123 o "Expires", defined in Section 14.21 in [RFC2616] (Section 3.3 in 1124 [I-D.ietf-httpbis-p6-cache]), giving the absolute time after which 1125 a response is considered stale. 1127 o The more obscure headers "Retry-After", defined in Section 14.37 1128 in [RFC2616], and "Warning", defined in section 14.46 in 1129 [RFC2616], also may employ absolute time. 1131 [I-D.ietf-core-coap] defines a single "Date" option, which however 1132 "indicates the creation time and date of a given resource 1133 representation", i.e., is closer to a "Last-Modified" HTTP header. 1134 HTTP's caching rules [I-D.ietf-httpbis-p6-cache] make use of both 1135 "Date" and "Last-Modified", combined with "Expires". The specific 1136 semantics required for CoAP needs further consideration. 1138 In addition to the definition of the semantics, an encoding for 1139 absolute times needs to be specified. 1141 In UNIX-related systems, it is customary to indicate absolute time as 1142 an integer number of seconds, after midnight UTC, January 1, 1970. 1143 Unless negative numbers are employed, this time format cannot 1144 represent time values prior to January 1, 1970, which probably is not 1145 required for the uses ob absolute time in CoAP. 1147 If a 32-bit integer is used and allowance is made for a sign-bit in a 1148 local implementation, the latest UTC time value that can be 1149 represented by the resulting 31 bit integer value is 03:14:07 on 1150 January 19, 2038. If the 32-bit integer is used as an unsigned 1151 value, the last date is 2106-02-07, 06:28:15. 1153 The reach can be extended by: - moving the epoch forward, e.g. by 40 1154 years (= 1262304000 seconds) to 2010-01-01. This makes it impossible 1155 to represent Last-Modified times in that past (such as could be 1156 gatewayed in from HTTP). - extending the number of bits, e.g. by one 1157 more byte, either always or as one of two formats, keeping the 32-bit 1158 variant as well. 1160 Also, the resolution can be extended by expressing time in 1161 milliseconds etc., requiring even more bits (e.g., a 48-bit unsigned 1162 integer of milliseconds would last well after year 9999.) 1164 For experiments, an experimental "Date" option is defined with the 1165 semantics of HTTP's "Last-Modified". It can carry an unsigned 1166 integer of 32, 40, or 48 bits; 32- and 40-bit integers indicate the 1167 absolute time in seconds since 1970-01-01 00:00 UTC, while 48-bit 1168 integers indicate the absolute time in milliseconds since 1970-01-01 1169 00:00 UTC. 1171 However, that option is not really that useful until there is a 1172 "If-Modified-Since" option as well. 1174 (Also: Discuss nodes without clocks.) 1176 C.2. Representing Durations 1178 Various message types used in CoAP need the representation of 1179 *durations*, i.e. of the length of a timespan. In SI units, these 1180 are measured in seconds. CoAP durations represent integer numbers of 1181 seconds, but instead of representing these numbers as integers, a 1182 more compact single-byte pseudo-floating-point (pseudo-FP) 1183 representation is used (Figure 20). 1185 0 1 2 3 4 5 6 7 1186 +---+---+---+---+---+---+---+---+ 1187 | 0... value | 1188 +---+---+---+---+---+---+---+---+ 1190 +---+---+---+---+---+---+---+---+ 1191 | 1... mantissa | exponent | 1192 +---+---+---+---+---+---+---+---+ 1193 Figure 20: Duration in (8,4) pseudo-FP representation 1195 If the high bit is clear, the entire n-bit value (including the high 1196 bit) is the decoded value. If the high bit is set, the mantissa 1197 (including the high bit, with the exponent field cleared out but 1198 still present) is shifted left by the exponent to yield the decoded 1199 value. 1201 The (n,e)-pseudo-FP format can be decoded with a single line of code 1202 (plus a couple of constant definitions), as demonstrated in 1203 Figure 21. 1205 #define N 8 1206 #define E 4 1207 #define HIBIT (1 << (N - 1)) 1208 #define EMASK ((1 << E) - 1) 1209 #define MMASK ((1 << N) - 1 - EMASK) 1211 #define DECODE_8_4(r) (r < HIBIT ? r : (r & MMASK) << (r & EMASK)) 1213 Figure 21: Decoding an (8,4) pseudo-FP value 1215 Note that a pseudo-FP encoder needs to consider rounding; different 1216 applications of durations may favor rounding up or rounding down the 1217 value encoded in the message. 1219 The highest pseudo-FP value, represented by an all-ones byte (0xFF), 1220 is reserved to indicate an indefinite duration. The next lower value 1221 (0xEF) is thus the highest representable value and is decoded as 1222 7340032 seconds, a little more than 12 weeks. 1224 C.3. Rationale 1226 Where CPU power and memory is abundant, a duration can almost always 1227 be adequately represented by a non-negative floating-point number 1228 representing that number of seconds. Historically, many APIs have 1229 also used an integer representation, which limits both the resolution 1230 (e.g., if the integer represents the duration in seconds) and often 1231 the range (integer machine types have range limits that may become 1232 relevant). UNIX's "time_t" (which is used for both absolute time and 1233 durations) originally was a signed 32-bit value of seconds, but was 1234 later complemented by an additional integer to add microsecond 1235 ("struct timeval") and then later nanosecond ("struct timespec") 1236 resolution. 1238 Three decisions need to be made for each application of the concept 1239 of duration: 1241 o the *resolution*. What rounding error is acceptable? 1243 o the *range*. What is the maximum duration that needs to be 1244 represented? 1246 o the *number of bits* that can be expended. 1248 Obviously, these decisions are interrelated. Typically, a large 1249 range needs a large number of bits, unless resolution is traded. For 1250 most applications, the actual requirement for resolution are limited 1251 for longer durations, but can be more acute for shorter durations. 1253 C.4. Pseudo-Floating Point 1255 Constrained systems typically avoid the use of floating-point (FP) 1256 values, as 1258 o simple CPUs often don't have support for floating-point datatypes 1260 o software floating-point libraries are expensive in code size and 1261 slow. 1263 In addition, floating-point datatypes used to be a significant 1264 element of market differentiation in CPU design; it has taken the 1265 industry a long time to agree on a standard floating point 1266 representation. 1268 These issues have led to protocols that try to constrain themselves 1269 to integer representation even where the ability of a floating point 1270 representation to trade range for resolution would be beneficial. 1272 The idea of introducing _pseudo-FP_ is to obtain the increased range 1273 provided by embedding an exponent, without necessarily getting stuck 1274 with hardware datatypes or inefficient software floating-point 1275 libraries. 1277 For the purposes of this draft, we define an (n,e)-pseudo-FP as a 1278 fixed-length value of n bits, e of which may be used for an exponent. 1279 Figure 20 illustrates an (8,4)-pseudo-FP value. 1281 If the high bit is clear, the entire n-bit value (including the high 1282 bit) is the decoded value. If the high bit is set, the mantissa 1283 (including the high bit, but with the exponent field cleared out) is 1284 shifted left by the exponent to yield the decoded value. 1286 The (n,e)-pseudo-FP format can be decoded with a single line of code 1287 (plus a couple of constant definition), as demonstrated in Figure 21. 1289 Only non-negative numbers can be represented by this format. It is 1290 designed to provide full integer resolution for values from 0 to 1291 2^(n-1)-1, i.e., 0 to 127 in the (8,4) case, and a mantissa of n-e 1292 bits from 2^(n-1) to (2^n-2^e)*2^(2^e-1), i.e., 128 to 7864320 in the 1293 (8,4) case. By choosing e carefully, resolution can be traded 1294 against range. 1296 Note that a pseudo-FP encoder needs to consider rounding; different 1297 applications of durations may favor rounding up or rounding down the 1298 value encoded in the message. This requires a little more than a 1299 single line of code (which is left as an exercise to the reader, as 1300 the most efficient expression depends on hardware details). 1302 C.5. A Duration Type for CoAP 1304 CoAP needs durations in a number of places. In [I-D.ietf-core-coap], 1305 durations occur in the option "Subscription-lifetime" as well as in 1306 the option "Max-age". (Note that the option "Date" is not a 1307 duration, but a point in time.) Other durations of this kind may be 1308 added later. 1310 Most durations relevant to CoAP are best expressed with a minimum 1311 resolution of one second. More detailed resolutions are unlikely to 1312 provide much benefit. 1314 The range of lifetimes and caching ages are probably best kept below 1315 the order of magnitude of months. An (8,4)-pseudo-FP has the maximum 1316 value of 7864320, which is about 91 days; this appears to be adequate 1317 for a subscription lifetime and probably even for a maximum cache 1318 age. Figure 22 shows the values that can be expressed. (If a larger 1319 range for the latter is indeed desired, an (8,5)-pseudo-FP could be 1320 used; this would last 15 milleniums, at the cost of having only 3 1321 bits of accuracy for values larger than 127 seconds.) 1323 Proposal: A single duration type is used throughout CoAP, based on 1324 an (8,4)-pseudo-FP giving a duration in seconds. 1326 Benefits: Implementations can use a single piece of code for 1327 managing all CoAP-related durations. 1329 In addition, length information never needs to be managed for 1330 durations that are embedded in other data structures: All 1331 durations are expressed by a single byte. 1333 It might be worthwhile to reserve one duration value, e.g. 0xFF, for 1334 an indefinite duration. 1336 Duration Seconds Encoded 1337 ----------- ---------- ------- 1338 00:00:00 0x00000000 0x00 1339 00:00:01 0x00000001 0x01 1340 00:00:02 0x00000002 0x02 1341 00:00:03 0x00000003 0x03 1342 00:00:04 0x00000004 0x04 1343 00:00:05 0x00000005 0x05 1344 00:00:06 0x00000006 0x06 1345 00:00:07 0x00000007 0x07 1346 00:00:08 0x00000008 0x08 1347 00:00:09 0x00000009 0x09 1348 00:00:10 0x0000000a 0x0a 1349 00:00:11 0x0000000b 0x0b 1350 00:00:12 0x0000000c 0x0c 1351 00:00:13 0x0000000d 0x0d 1352 00:00:14 0x0000000e 0x0e 1353 00:00:15 0x0000000f 0x0f 1354 00:00:16 0x00000010 0x10 1355 00:00:17 0x00000011 0x11 1356 00:00:18 0x00000012 0x12 1357 00:00:19 0x00000013 0x13 1358 00:00:20 0x00000014 0x14 1359 00:00:21 0x00000015 0x15 1360 00:00:22 0x00000016 0x16 1361 00:00:23 0x00000017 0x17 1362 00:00:24 0x00000018 0x18 1363 00:00:25 0x00000019 0x19 1364 00:00:26 0x0000001a 0x1a 1365 00:00:27 0x0000001b 0x1b 1366 00:00:28 0x0000001c 0x1c 1367 00:00:29 0x0000001d 0x1d 1368 00:00:30 0x0000001e 0x1e 1369 00:00:31 0x0000001f 0x1f 1370 00:00:32 0x00000020 0x20 1371 00:00:33 0x00000021 0x21 1372 00:00:34 0x00000022 0x22 1373 00:00:35 0x00000023 0x23 1374 00:00:36 0x00000024 0x24 1375 00:00:37 0x00000025 0x25 1376 00:00:38 0x00000026 0x26 1377 00:00:39 0x00000027 0x27 1378 00:00:40 0x00000028 0x28 1379 00:00:41 0x00000029 0x29 1380 00:00:42 0x0000002a 0x2a 1381 00:00:43 0x0000002b 0x2b 1382 00:00:44 0x0000002c 0x2c 1383 00:00:45 0x0000002d 0x2d 1384 00:00:46 0x0000002e 0x2e 1385 00:00:47 0x0000002f 0x2f 1386 00:00:48 0x00000030 0x30 1387 00:00:49 0x00000031 0x31 1388 00:00:50 0x00000032 0x32 1389 00:00:51 0x00000033 0x33 1390 00:00:52 0x00000034 0x34 1391 00:00:53 0x00000035 0x35 1392 00:00:54 0x00000036 0x36 1393 00:00:55 0x00000037 0x37 1394 00:00:56 0x00000038 0x38 1395 00:00:57 0x00000039 0x39 1396 00:00:58 0x0000003a 0x3a 1397 00:00:59 0x0000003b 0x3b 1398 00:01:00 0x0000003c 0x3c 1399 00:01:01 0x0000003d 0x3d 1400 00:01:02 0x0000003e 0x3e 1401 00:01:03 0x0000003f 0x3f 1402 00:01:04 0x00000040 0x40 1403 00:01:05 0x00000041 0x41 1404 00:01:06 0x00000042 0x42 1405 00:01:07 0x00000043 0x43 1406 00:01:08 0x00000044 0x44 1407 00:01:09 0x00000045 0x45 1408 00:01:10 0x00000046 0x46 1409 00:01:11 0x00000047 0x47 1410 00:01:12 0x00000048 0x48 1411 00:01:13 0x00000049 0x49 1412 00:01:14 0x0000004a 0x4a 1413 00:01:15 0x0000004b 0x4b 1414 00:01:16 0x0000004c 0x4c 1415 00:01:17 0x0000004d 0x4d 1416 00:01:18 0x0000004e 0x4e 1417 00:01:19 0x0000004f 0x4f 1418 00:01:20 0x00000050 0x50 1419 00:01:21 0x00000051 0x51 1420 00:01:22 0x00000052 0x52 1421 00:01:23 0x00000053 0x53 1422 00:01:24 0x00000054 0x54 1423 00:01:25 0x00000055 0x55 1424 00:01:26 0x00000056 0x56 1425 00:01:27 0x00000057 0x57 1426 00:01:28 0x00000058 0x58 1427 00:01:29 0x00000059 0x59 1428 00:01:30 0x0000005a 0x5a 1429 00:01:31 0x0000005b 0x5b 1430 00:01:32 0x0000005c 0x5c 1431 00:01:33 0x0000005d 0x5d 1432 00:01:34 0x0000005e 0x5e 1433 00:01:35 0x0000005f 0x5f 1434 00:01:36 0x00000060 0x60 1435 00:01:37 0x00000061 0x61 1436 00:01:38 0x00000062 0x62 1437 00:01:39 0x00000063 0x63 1438 00:01:40 0x00000064 0x64 1439 00:01:41 0x00000065 0x65 1440 00:01:42 0x00000066 0x66 1441 00:01:43 0x00000067 0x67 1442 00:01:44 0x00000068 0x68 1443 00:01:45 0x00000069 0x69 1444 00:01:46 0x0000006a 0x6a 1445 00:01:47 0x0000006b 0x6b 1446 00:01:48 0x0000006c 0x6c 1447 00:01:49 0x0000006d 0x6d 1448 00:01:50 0x0000006e 0x6e 1449 00:01:51 0x0000006f 0x6f 1450 00:01:52 0x00000070 0x70 1451 00:01:53 0x00000071 0x71 1452 00:01:54 0x00000072 0x72 1453 00:01:55 0x00000073 0x73 1454 00:01:56 0x00000074 0x74 1455 00:01:57 0x00000075 0x75 1456 00:01:58 0x00000076 0x76 1457 00:01:59 0x00000077 0x77 1458 00:02:00 0x00000078 0x78 1459 00:02:01 0x00000079 0x79 1460 00:02:02 0x0000007a 0x7a 1461 00:02:03 0x0000007b 0x7b 1462 00:02:04 0x0000007c 0x7c 1463 00:02:05 0x0000007d 0x7d 1464 00:02:06 0x0000007e 0x7e 1465 00:02:07 0x0000007f 0x7f 1466 00:02:08 0x00000080 0x80 1467 00:02:24 0x00000090 0x90 1468 00:02:40 0x000000a0 0xa0 1469 00:02:56 0x000000b0 0xb0 1470 00:03:12 0x000000c0 0xc0 1471 00:03:28 0x000000d0 0xd0 1472 00:03:44 0x000000e0 0xe0 1473 00:04:00 0x000000f0 0xf0 1474 00:04:16 0x00000100 0x81 1475 00:04:48 0x00000120 0x91 1476 00:05:20 0x00000140 0xa1 1477 00:05:52 0x00000160 0xb1 1478 00:06:24 0x00000180 0xc1 1479 00:06:56 0x000001a0 0xd1 1480 00:07:28 0x000001c0 0xe1 1481 00:08:00 0x000001e0 0xf1 1482 00:08:32 0x00000200 0x82 1483 00:09:36 0x00000240 0x92 1484 00:10:40 0x00000280 0xa2 1485 00:11:44 0x000002c0 0xb2 1486 00:12:48 0x00000300 0xc2 1487 00:13:52 0x00000340 0xd2 1488 00:14:56 0x00000380 0xe2 1489 00:16:00 0x000003c0 0xf2 1490 00:17:04 0x00000400 0x83 1491 00:19:12 0x00000480 0x93 1492 00:21:20 0x00000500 0xa3 1493 00:23:28 0x00000580 0xb3 1494 00:25:36 0x00000600 0xc3 1495 00:27:44 0x00000680 0xd3 1496 00:29:52 0x00000700 0xe3 1497 00:32:00 0x00000780 0xf3 1498 00:34:08 0x00000800 0x84 1499 00:38:24 0x00000900 0x94 1500 00:42:40 0x00000a00 0xa4 1501 00:46:56 0x00000b00 0xb4 1502 00:51:12 0x00000c00 0xc4 1503 00:55:28 0x00000d00 0xd4 1504 00:59:44 0x00000e00 0xe4 1505 01:04:00 0x00000f00 0xf4 1506 01:08:16 0x00001000 0x85 1507 01:16:48 0x00001200 0x95 1508 01:25:20 0x00001400 0xa5 1509 01:33:52 0x00001600 0xb5 1510 01:42:24 0x00001800 0xc5 1511 01:50:56 0x00001a00 0xd5 1512 01:59:28 0x00001c00 0xe5 1513 02:08:00 0x00001e00 0xf5 1514 02:16:32 0x00002000 0x86 1515 02:33:36 0x00002400 0x96 1516 02:50:40 0x00002800 0xa6 1517 03:07:44 0x00002c00 0xb6 1518 03:24:48 0x00003000 0xc6 1519 03:41:52 0x00003400 0xd6 1520 03:58:56 0x00003800 0xe6 1521 04:16:00 0x00003c00 0xf6 1522 04:33:04 0x00004000 0x87 1523 05:07:12 0x00004800 0x97 1524 05:41:20 0x00005000 0xa7 1525 06:15:28 0x00005800 0xb7 1526 06:49:36 0x00006000 0xc7 1527 07:23:44 0x00006800 0xd7 1528 07:57:52 0x00007000 0xe7 1529 08:32:00 0x00007800 0xf7 1530 09:06:08 0x00008000 0x88 1531 10:14:24 0x00009000 0x98 1532 11:22:40 0x0000a000 0xa8 1533 12:30:56 0x0000b000 0xb8 1534 13:39:12 0x0000c000 0xc8 1535 14:47:28 0x0000d000 0xd8 1536 15:55:44 0x0000e000 0xe8 1537 17:04:00 0x0000f000 0xf8 1538 18:12:16 0x00010000 0x89 1539 20:28:48 0x00012000 0x99 1540 22:45:20 0x00014000 0xa9 1541 1d 01:01:52 0x00016000 0xb9 1542 1d 03:18:24 0x00018000 0xc9 1543 1d 05:34:56 0x0001a000 0xd9 1544 1d 07:51:28 0x0001c000 0xe9 1545 1d 10:08:00 0x0001e000 0xf9 1546 1d 12:24:32 0x00020000 0x8a 1547 1d 16:57:36 0x00024000 0x9a 1548 1d 21:30:40 0x00028000 0xaa 1549 2d 02:03:44 0x0002c000 0xba 1550 2d 06:36:48 0x00030000 0xca 1551 2d 11:09:52 0x00034000 0xda 1552 2d 15:42:56 0x00038000 0xea 1553 2d 20:16:00 0x0003c000 0xfa 1554 3d 00:49:04 0x00040000 0x8b 1555 3d 09:55:12 0x00048000 0x9b 1556 3d 19:01:20 0x00050000 0xab 1557 4d 04:07:28 0x00058000 0xbb 1558 4d 13:13:36 0x00060000 0xcb 1559 4d 22:19:44 0x00068000 0xdb 1560 5d 07:25:52 0x00070000 0xeb 1561 5d 16:32:00 0x00078000 0xfb 1562 6d 01:38:08 0x00080000 0x8c 1563 6d 19:50:24 0x00090000 0x9c 1564 7d 14:02:40 0x000a0000 0xac 1565 8d 08:14:56 0x000b0000 0xbc 1566 9d 02:27:12 0x000c0000 0xcc 1567 9d 20:39:28 0x000d0000 0xdc 1568 10d 14:51:44 0x000e0000 0xec 1569 11d 09:04:00 0x000f0000 0xfc 1570 12d 03:16:16 0x00100000 0x8d 1571 13d 15:40:48 0x00120000 0x9d 1572 15d 04:05:20 0x00140000 0xad 1573 16d 16:29:52 0x00160000 0xbd 1574 18d 04:54:24 0x00180000 0xcd 1575 19d 17:18:56 0x001a0000 0xdd 1576 21d 05:43:28 0x001c0000 0xed 1577 22d 18:08:00 0x001e0000 0xfd 1578 24d 06:32:32 0x00200000 0x8e 1579 27d 07:21:36 0x00240000 0x9e 1580 30d 08:10:40 0x00280000 0xae 1581 33d 08:59:44 0x002c0000 0xbe 1582 36d 09:48:48 0x00300000 0xce 1583 39d 10:37:52 0x00340000 0xde 1584 42d 11:26:56 0x00380000 0xee 1585 45d 12:16:00 0x003c0000 0xfe 1586 48d 13:05:04 0x00400000 0x8f 1587 54d 14:43:12 0x00480000 0x9f 1588 60d 16:21:20 0x00500000 0xaf 1589 66d 17:59:28 0x00580000 0xbf 1590 72d 19:37:36 0x00600000 0xcf 1591 78d 21:15:44 0x00680000 0xdf 1592 84d 22:53:52 0x00700000 0xef 1593 91d 00:32:00 0x00780000 0xff (reserved) 1595 Figure 22 1597 Authors' Addresses 1599 Carsten Bormann 1600 Universitaet Bremen TZI 1601 Postfach 330440 1602 Bremen D-28359 1603 Germany 1605 Phone: +49-421-218-63921 1606 Fax: +49-421-218-7000 1607 Email: cabo@tzi.org 1609 Klaus Hartke 1610 Universitaet Bremen TZI 1611 Postfach 330440 1612 Bremen D-28359 1613 Germany 1615 Phone: +49-421-218-63905 1616 Fax: +49-421-218-7000 1617 Email: hartke@tzi.org