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