idnits 2.17.1 draft-bormann-coap-misc-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 5, 2011) is 4733 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 ---------------------------------------------------------------------------- == Unused Reference: 'I-D.ietf-core-observe' is defined on line 343, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 368, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 375, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-06 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-14 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-14 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-14 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 10 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: November 6, 2011 May 5, 2011 7 Miscellaneous additions to CoAP 8 draft-bormann-coap-misc-08 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 November 6, 2011. 35 Copyright Notice 37 Copyright (c) 2011 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 4 54 2.1. Accept Option . . . . . . . . . . . . . . . . . . . . . . 4 55 2.2. 4.06 Not Acceptable . . . . . . . . . . . . . . . . . . . 5 56 3. Conditional Request: If-Match . . . . . . . . . . . . . . . . 6 57 3.1. If-Match Option . . . . . . . . . . . . . . . . . . . . . 6 58 3.2. 4.12 Precondition Failed . . . . . . . . . . . . . . . . . 6 59 4. URI Authorities with Binary Adresses . . . . . . . . . . . . . 7 60 5. User-defined Option . . . . . . . . . . . . . . . . . . . . . 9 61 6. Payload-Length Option . . . . . . . . . . . . . . . . . . . . 10 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 63 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 64 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 65 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 66 10.1. Normative References . . . . . . . . . . . . . . . . . . . 14 67 10.2. Informative References . . . . . . . . . . . . . . . . . . 15 68 Appendix A. The Cemetery (Things we won't do) . . . . . . . . . . 16 69 A.1. Stateful URI compression . . . . . . . . . . . . . . . . . 16 70 Appendix B. Experimental Options . . . . . . . . . . . . . . . . 18 71 B.1. Options indicating absolute time . . . . . . . . . . . . . 18 72 B.2. Representing Durations . . . . . . . . . . . . . . . . . . 19 73 B.3. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 20 74 B.4. Pseudo-Floating Point . . . . . . . . . . . . . . . . . . 21 75 B.5. A Duration Type for CoAP . . . . . . . . . . . . . . . . . 22 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 78 1. Introduction 80 The CoRE WG is tasked with standardizing an Application Protocol for 81 Constrained Networks/Nodes, CoAP [I-D.ietf-core-coap]. This protocol 82 is intended to provide RESTful [REST] services not unlike HTTP 83 [RFC2616], while reducing the complexity of implementation as well as 84 the size of packets exchanged in order to make these services useful 85 in a highly constrained network of themselves highly constrained 86 nodes. 88 This objective requires restraint in a number of sometimes 89 conflicting ways: 91 o reducing implementation complexity in order to minimize code size, 93 o reducing message sizes in order to minimize the number of 94 fragments needed for each message (in turn to maximize the 95 probability of delivery of the message), the amount of 96 transmission power needed and the loading of the limited-bandwidth 97 channel, 99 o reducing requirements on the environment such as stable storage, 100 good sources of randomness or user interaction capabilities. 102 This draft attempts to address a number of problems not yet 103 adequately solved in [I-D.ietf-core-coap]. The solutions proposed to 104 these problems are somewhat interrelated and are therefore presented 105 in one draft. 107 The appendix contains the "CoAP cemetery" (possibly later to move 108 into its own draft), documenting roads that the WG decided not to 109 take, in order to spare readers from reinventing them in vain. 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in {RFC2119}}. 115 The term "byte" is used in its now customary sense as a synonym for 116 "octet". 118 2. Content Negotiation 120 A resource may be available in a number of representations. Without 121 some information from the client, a server has no easy way to decide 122 which of these would be best served. HTTP [RFC2616] has an Accept: 123 request header that a client can use to indicate the media types 124 supported, allowing the server to decide. This header is somewhat 125 unpopular as, for a web browser, there are too many media types to 126 choose from, so -- even with wildcards -- there is no meaningful 127 information to put there. (This has changed a bit for AJAX calls, 128 which may indeed have a specific media type preference.) It is 129 unlikely that machine-to-machine communication would have the same 130 problem. 132 A similar function to the HTTP Accept: header could be added to CoAP 133 as an option in a much simpler way. The CoAP Accept option would 134 when included one or more times in a request, carry one or more media 135 types, each of which is an acceptable media type for the client, in 136 the order of preference. If no Accept option is given, the client 137 does not express a preference. 139 Depending on whether the Accept Option is defined as a critical or an 140 elective option, the meaning of the option is slightly different: 142 Critical: The client is not interested in a representation of the 143 resource if the server is unable or unwilling to return it in one 144 of the specified media types. (For this purpose, a new response 145 code, 4.06 Not Acceptable, is needed.) 147 Elective: The client prefers the representation returned by the 148 server to be in one of the media types, but is willing to accept 149 the response also if the server returns a representation in a 150 different media type. 152 2.1. Accept Option 154 +-----+----------+---------------+--------+--------+---------+ 155 | No. | C/E | Name | Format | Length | Default | 156 +-----+----------+---------------+--------+--------+---------+ 157 | TBD | Critical | Accept.Only | uint | 0-2 B | (none) | 158 | | | | | | | 159 | TBD | Elective | Accept.Prefer | uint | 0-2 B | (none) | 160 +-----+----------+---------------+--------+--------+---------+ 162 TODO: Decide which of these options we need, or whether both should 163 be available. 165 2.2. 4.06 Not Acceptable 167 Like HTTP 406 "Not Acceptable", but with a human-readable diagnostic 168 message instead of a representation containing a list of available 169 representation characteristics and location(s). 171 3. Conditional Request: If-Match 173 The If-Match Option MAY be used to make a request conditional on the 174 current existence or value of an ETag for one or more representations 175 of the target resource. If-Match is generally useful for resource 176 update requests, such as PUT requests, as a means for protecting 177 against accidental overwrites when multiple clients are acting in 178 parallel on the same resource (i.e., the "lost update" problem). 180 The value of an If-Match option is either an ETag or the empty 181 string. An empty string places the precondition on the existence of 182 any current representation for the target resource. 184 The If-Match Option can occur multiple times. If any of the ETags 185 given as an option value match the ETag of the selected 186 representation for the target resource, or if an If-Match Option with 187 an empty string as option value is given and any current 188 representation exists for the target resource, then the server MAY 189 perform the request method as if the If-Match Option was not present. 191 If none of the ETags match and, if an empty string is given, no 192 current representation exists at all, the server MUST NOT perform the 193 requested method. Instead, the server MUST respond with the 4.12 194 (Precondition Failed) response code. 196 If the request would, without the If-Match Options, result in 197 anything other than a 2.xx or 4.12 response code, then any If-Match 198 Options MUST be ignored. 200 3.1. If-Match Option 202 +-----+----------+----------+--------+--------+---------+ 203 | No. | C/E | Name | Format | Length | Default | 204 +-----+----------+----------+--------+--------+---------+ 205 | TBD | Critical | If-Match | opaque | 0-8 B | (none) | 206 +-----+----------+----------+--------+--------+---------+ 208 If-Match Options are critical. 210 The If-Match Option is repeatable. 212 3.2. 4.12 Precondition Failed 214 Like HTTP 412 (Precondition Failed). 216 4. URI Authorities with Binary Adresses 218 One problem with the way URI authorities are represented in the URI 219 syntax is that the authority part can be very bulky if it encodes an 220 IPv6 address in ASCII. 222 Proposal: Provide an option "Uri-Authority-Binary" that can be an 223 even number of bytes between 2 and 18 except 12 or 14. 225 o If the number of bytes is 2, the destination IP address of the 226 packet transporting the CoAP message is implied. 228 o If the number of bytes is 4 or 6, the first four bytes of the 229 option value are an IPv4 address in binary. 231 o If the number of bytes is 8 or 10, the first eight bytes are the 232 lower 64 bits of an IPv6 address; the upper eight bytes are 233 implied from the destination address of the packet transporting 234 the CoAP message. 236 o If the number of bytes is 16 or 18, the first 16 bytes are an IPv6 237 address. 239 o If two more bytes remain, this is a port number (as always in 240 network byte order). 242 The resulting authority is (conceptually translated into ASCII and) 243 used in place of an Uri-Authority option, or inserted into a Proxy- 244 Uri. Examples: 246 +-------------+------------------+---------+------------------------+ 247 | Proxy-Uri | Uri-Authority-Bi | Uri-Pat | URI | 248 | | nary | h | | 249 +-------------+------------------+---------+------------------------+ 250 | (none) | (none) | (none) | "/" | 251 | | | | | 252 | (none) | (none) | 'temp' | "/temp" | 253 | | | | | 254 | (none) | 2 bytes: 61616 | 'temp' | "coap://[DA]:61616/tem | 255 | | | | p" | 256 | | | | | 257 | (none) | 16 bytes: | temp | "coap://[2000::1]/temp | 258 | | 2000::1 | | " | 259 | | | | | 260 | 'http://' | 10 bytes: | (none) | "http://[DA::123:45]:6 | 261 | | ::123:45 + 616 | | 16" | 262 | | | | | 263 | 'http:///te | 18 bytes: | (none) | "http://[2000::1]:616/ | 264 | mp' | 2000::1 + 616 | | temp" | 265 +-------------+------------------+---------+------------------------+ 267 5. User-defined Option 269 To enable experimentation and community-specific options, option 270 number 14 (the first NOP option) can also be used as a user-defined 271 option. For this application, the option value has one or more 272 bytes, the semantics of which are defined by prior agreement between 273 the communicating partners. 275 It is RECOMMENDED to start the option value with a unique identifier, 276 e.g., the SDNV [RFC5050] of the enterprise number of the organisation 277 defining the option, possibly followed by additional discriminating 278 bits or bytes. 280 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 281 |1 0 0 0 0 0 0 1|0 1 1 1 0 0 1 1| private opt-id| value... | 282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 283 \___SDNV of enterprise number___/ 285 Figure 1: Example option value for user-defined option 287 User-defined Options are elective. 289 The User-defined Option is repeatable. 291 Potential options: 293 +-----+----------+------+-------------+---------+---------+ 294 | No. | C/E | Name | Format | Length | Default | 295 +-----+----------+------+-------------+---------+---------+ 296 | 14 | Elective | User | (see below) | 1-270 B | (empty) | 297 +-----+----------+------+-------------+---------+---------+ 299 6. Payload-Length Option 301 Not all transport mappings may provide an unambiguous length of the 302 CoAP message. For UDP, it may also be desirable to pack more than 303 one CoAP message into one UDP payload (aggregation); in that case, 304 for all but the last message there needs to be a way to delimit the 305 payload of that message. 307 This can be solved using a new option, the Payload-Length option. If 308 this option is present, the value of this option is an unsigned 309 integer giving the length of the payload of the message (note that 310 this integer can be zero for a zero-length payload, which can in turn 311 be represented by a zero-length option value). (In the UDP 312 aggregation case, what would have been in the payload of this message 313 after "payload-length" bytes is then actually one or more additional 314 messages.) 316 7. IANA Considerations 318 This draft adds option numbers to Table 2 of [I-D.ietf-core-coap], 319 resulting in: 321 TBD. 323 8. Security Considerations 325 TBD. 327 9. Acknowledgements 329 This work was partially funded by the Klaus Tschira Foundation. 331 Of course, much of the content of this draft is the result of 332 discussions with the [I-D.ietf-core-coap] authors. 334 10. References 336 10.1. Normative References 338 [I-D.ietf-core-coap] 339 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 340 "Constrained Application Protocol (CoAP)", 341 draft-ietf-core-coap-06 (work in progress), May 2011. 343 [I-D.ietf-core-observe] 344 Hartke, K. and Z. Shelby, "Observing Resources in CoAP", 345 draft-ietf-core-observe-02 (work in progress), March 2011. 347 [I-D.ietf-httpbis-p1-messaging] 348 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 349 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 350 "HTTP/1.1, part 1: URIs, Connections, and Message 351 Parsing", draft-ietf-httpbis-p1-messaging-14 (work in 352 progress), April 2011. 354 [I-D.ietf-httpbis-p4-conditional] 355 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 356 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 357 "HTTP/1.1, part 4: Conditional Requests", 358 draft-ietf-httpbis-p4-conditional-14 (work in progress), 359 April 2011. 361 [I-D.ietf-httpbis-p6-cache] 362 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 363 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 364 "HTTP/1.1, part 6: Caching", 365 draft-ietf-httpbis-p6-cache-14 (work in progress), 366 April 2011. 368 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 369 Requirement Levels", BCP 14, RFC 2119, March 1997. 371 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 372 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 373 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 375 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 376 Resource Identifier (URI): Generic Syntax", STD 66, 377 RFC 3986, January 2005. 379 10.2. Informative References 381 [REST] Fielding, R., "Architectural Styles and the Design of 382 Network-based Software Architectures", 2000. 384 [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol 385 Specification", RFC 5050, November 2007. 387 Appendix A. The Cemetery (Things we won't do) 389 This annex documents roads that the WG decided not to take, in order 390 to spare readers from reinventing them in vain. 392 A.1. Stateful URI compression 394 Is the approximately 25 % average saving achievable with Huffman- 395 based URI compression schemes worth the complexity? Probably not, 396 because much higher average savings can be achieved by introducing 397 state. 399 Henning Schulzrinne has proposed for a server to be able to supply a 400 shortened URI once a resource has been requested using the full- 401 length URI. Let's call such a shortened referent a _Temporary 402 Resource Identifier_, _TeRI_ for short. This could be expressed by a 403 response option as shown in Figure 2. 405 0 406 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 407 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 408 | duration | TeRI... 409 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 411 Figure 2: Option for offering a TeRI in a response 413 The TeRI offer option indicates that the server promises to offer 414 this resources under the TeRI given for at least the time given as 415 the duration. Another TeRI offer can be made later to extend the 416 duration. 418 Once a TeRI for a URI is known (and still within its lifetime), the 419 client can supply a TeRI instead of a URI in its requests. The same 420 option format as an offer could be used to allow the client to 421 indicate how long it believes the TeRI will still be valid (so that 422 the server can decide when to update the lifetime duration). TeRIs 423 in requests could be distinguished from URIs e.g. by using a 424 different option number. 426 Proposal: Add a TeRI option that can be used in CoAP requests and 427 responses. 429 Add a way to indicate a TeRI and its duration in a link-value. 431 Do not add any form of stateless URI encoding. 433 Benefits: Much higher reduction of message size than any stateless 434 URI encoding could achieve. 436 As the use of TeRIs is entirely optional, minimal complexity nodes 437 can get by without implementing them. 439 Drawbacks: Adds considerable state and complexity to the protocol. 441 It turns out that real CoAP URIs are short enough that TeRIs are 442 not needed. 444 (Discuss the security implications of TeRIs.) 446 Appendix B. Experimental Options 448 This annex documents proposals that need significant additional 449 discussion before they can become part of (or go back to) the main 450 CoAP specification. They are not dead, but might die if there turns 451 out to be no good way to solve the problem. 453 B.1. Options indicating absolute time 455 HTTP has a number of headers that may indicate absolute time: 457 o "Date", defined in Section 14.18 in [RFC2616] (Section 9.3 in 458 [I-D.ietf-httpbis-p1-messaging]), giving the absolute time a 459 response was generated; 461 o "Last-Modified", defined in Section 14.29 in [RFC2616], (Section 462 6.6 in [I-D.ietf-httpbis-p4-conditional], giving the absolute time 463 of when the origin server believes the resource representation was 464 last modified; 466 o "If-Modified-Since", defined in Section 14.25 in [RFC2616], 467 "If-Unmodified-Since", defined in Section 14.28 in [RFC2616], and 468 "If-Range", defined in Section 14.27 in [RFC2616] can be used to 469 supply absolute time to gate a conditional request; 471 o "Expires", defined in Section 14.21 in [RFC2616] (Section 3.3 in 472 [I-D.ietf-httpbis-p6-cache]), giving the absolute time after which 473 a response is considered stale. 475 o The more obscure headers "Retry-After", defined in Section 14.37 476 in [RFC2616], and "Warning", defined in section 14.46 in 477 [RFC2616], also may employ absolute time. 479 [I-D.ietf-core-coap] defines a single "Date" option, which however 480 "indicates the creation time and date of a given resource 481 representation", i.e., is closer to a "Last-Modified" HTTP header. 482 HTTP's caching rules [I-D.ietf-httpbis-p6-cache] make use of both 483 "Date" and "Last-Modified", combined with "Expires". The specific 484 semantics required for CoAP needs further consideration. 486 In addition to the definition of the semantics, an encoding for 487 absolute times needs to be specified. 489 In UNIX-related systems, it is customary to indicate absolute time as 490 an integer number of seconds, after midnight UTC, January 1, 1970. 491 Unless negative numbers are employed, this time format cannot 492 represent time values prior to January 1, 1970, which probably is not 493 required for the uses ob absolute time in CoAP. 495 If a 32-bit integer is used and allowance is made for a sign-bit in a 496 local implementation, the latest UTC time value that can be 497 represented by the resulting 31 bit integer value is 03:14:07 on 498 January 19, 2038. If the 32-bit integer is used as an unsigned 499 value, the last date is 2106-02-07, 06:28:15. 501 The reach can be extended by: - moving the epoch forward, e.g. by 40 502 years (= 1262304000 seconds) to 2010-01-01. This makes it impossible 503 to represent Last-Modified times in that past (such as could be 504 gatewayed in from HTTP). - extending the number of bits, e.g. by one 505 more byte, either always or as one of two formats, keeping the 32-bit 506 variant as well. 508 Also, the resolution can be extended by expressing time in 509 milliseconds etc., requiring even more bits (e.g., a 48-bit unsigned 510 integer of milliseconds would last well after year 9999.) 512 For experiments, an experimental "Date" option is defined with the 513 semantics of HTTP's "Last-Modified". It can carry an unsigned 514 integer of 32, 40, or 48 bits; 32- and 40-bit integers indicate the 515 absolute time in seconds since 1970-01-01 00:00 UTC, while 48-bit 516 integers indicate the absolute time in milliseconds since 1970-01-01 517 00:00 UTC. 519 However, that option is not really that useful until there is a 520 "If-Modified-Since" option as well. 522 (Also: Discuss nodes without clocks.) 524 B.2. Representing Durations 526 Various message types used in CoAP need the representation of 527 *durations*, i.e. of the length of a timespan. In SI units, these 528 are measured in seconds. CoAP durations represent integer numbers of 529 seconds, but instead of representing these numbers as integers, a 530 more compact single-byte pseudo-floating-point (pseudo-FP) 531 representation is used (Figure 3). 533 0 1 2 3 4 5 6 7 534 +---+---+---+---+---+---+---+---+ 535 | 0... value | 536 +---+---+---+---+---+---+---+---+ 538 +---+---+---+---+---+---+---+---+ 539 | 1... mantissa | exponent | 540 +---+---+---+---+---+---+---+---+ 541 Figure 3: Duration in (8,4) pseudo-FP representation 543 If the high bit is clear, the entire n-bit value (including the high 544 bit) is the decoded value. If the high bit is set, the mantissa 545 (including the high bit, with the exponent field cleared out but 546 still present) is shifted left by the exponent to yield the decoded 547 value. 549 The (n,e)-pseudo-FP format can be decoded with a single line of code 550 (plus a couple of constant definitions), as demonstrated in Figure 4. 552 #define N 8 553 #define E 4 554 #define HIBIT (1 << (N - 1)) 555 #define EMASK ((1 << E) - 1) 556 #define MMASK ((1 << N) - 1 - EMASK) 558 #define DECODE_8_4(r) (r < HIBIT ? r : (r & MMASK) << (r & EMASK)) 560 Figure 4: Decoding an (8,4) pseudo-FP value 562 Note that a pseudo-FP encoder needs to consider rounding; different 563 applications of durations may favor rounding up or rounding down the 564 value encoded in the message. 566 The highest pseudo-FP value, represented by an all-ones byte (0xFF), 567 is reserved to indicate an indefinite duration. The next lower value 568 (0xEF) is thus the highest representable value and is decoded as 569 7340032 seconds, a little more than 12 weeks. 571 B.3. Rationale 573 Where CPU power and memory is abundant, a duration can almost always 574 be adequately represented by a non-negative floating-point number 575 representing that number of seconds. Historically, many APIs have 576 also used an integer representation, which limits both the resolution 577 (e.g., if the integer represents the duration in seconds) and often 578 the range (integer machine types have range limits that may become 579 relevant). UNIX's "time_t" (which is used for both absolute time and 580 durations) originally was a signed 32-bit value of seconds, but was 581 later complemented by an additional integer to add microsecond 582 ("struct timeval") and then later nanosecond ("struct timespec") 583 resolution. 585 Three decisions need to be made for each application of the concept 586 of duration: 588 o the *resolution*. What rounding error is acceptable? 590 o the *range*. What is the maximum duration that needs to be 591 represented? 593 o the *number of bits* that can be expended. 595 Obviously, these decisions are interrelated. Typically, a large 596 range needs a large number of bits, unless resolution is traded. For 597 most applications, the actual requirement for resolution are limited 598 for longer durations, but can be more acute for shorter durations. 600 B.4. Pseudo-Floating Point 602 Constrained systems typically avoid the use of floating-point (FP) 603 values, as 605 o simple CPUs often don't have support for floating-point datatypes 607 o software floating-point libraries are expensive in code size and 608 slow. 610 In addition, floating-point datatypes used to be a significant 611 element of market differentiation in CPU design; it has taken the 612 industry a long time to agree on a standard floating point 613 representation. 615 These issues have led to protocols that try to constrain themselves 616 to integer representation even where the ability of a floating point 617 representation to trade range for resolution would be beneficial. 619 The idea of introducing _pseudo-FP_ is to obtain the increased range 620 provided by embedding an exponent, without necessarily getting stuck 621 with hardware datatypes or inefficient software floating-point 622 libraries. 624 For the purposes of this draft, we define an (n,e)-pseudo-FP as a 625 fixed-length value of n bits, e of which may be used for an exponent. 626 Figure 3 illustrates an (8,4)-pseudo-FP value. 628 If the high bit is clear, the entire n-bit value (including the high 629 bit) is the decoded value. If the high bit is set, the mantissa 630 (including the high bit, but with the exponent field cleared out) is 631 shifted left by the exponent to yield the decoded value. 633 The (n,e)-pseudo-FP format can be decoded with a single line of code 634 (plus a couple of constant definition), as demonstrated in Figure 4. 636 Only non-negative numbers can be represented by this format. It is 637 designed to provide full integer resolution for values from 0 to 638 2^(n-1)-1, i.e., 0 to 127 in the (8,4) case, and a mantissa of n-e 639 bits from 2^(n-1) to (2^n-2^e)*2^(2^e-1), i.e., 128 to 7864320 in the 640 (8,4) case. By choosing e carefully, resolution can be traded 641 against range. 643 Note that a pseudo-FP encoder needs to consider rounding; different 644 applications of durations may favor rounding up or rounding down the 645 value encoded in the message. This requires a little more than a 646 single line of code (which is left as an exercise to the reader, as 647 the most efficient expression depends on hardware details). 649 B.5. A Duration Type for CoAP 651 CoAP needs durations in a number of places. In [I-D.ietf-core-coap], 652 durations occur in the option "Subscription-lifetime" as well as in 653 the option "Max-age". (Note that the option "Date" is not a 654 duration, but a point in time.) Other durations of this kind may be 655 added later. 657 Most durations relevant to CoAP are best expressed with a minimum 658 resolution of one second. More detailed resolutions are unlikely to 659 provide much benefit. 661 The range of lifetimes and caching ages are probably best kept below 662 the order of magnitude of months. An (8,4)-pseudo-FP has the maximum 663 value of 7864320, which is about 91 days; this appears to be adequate 664 for a subscription lifetime and probably even for a maximum cache 665 age. Figure 5 shows the values that can be expressed. (If a larger 666 range for the latter is indeed desired, an (8,5)-pseudo-FP could be 667 used; this would last 15 milleniums, at the cost of having only 3 668 bits of accuracy for values larger than 127 seconds.) 670 Proposal: A single duration type is used throughout CoAP, based on 671 an (8,4)-pseudo-FP giving a duration in seconds. 673 Benefits: Implementations can use a single piece of code for 674 managing all CoAP-related durations. 676 In addition, length information never needs to be managed for 677 durations that are embedded in other data structures: All 678 durations are expressed by a single byte. 680 It might be worthwhile to reserve one duration value, e.g. 0xFF, for 681 an indefinite duration. 683 Duration Seconds Encoded 684 ----------- ---------- ------- 685 00:00:00 0x00000000 0x00 686 00:00:01 0x00000001 0x01 687 00:00:02 0x00000002 0x02 688 00:00:03 0x00000003 0x03 689 00:00:04 0x00000004 0x04 690 00:00:05 0x00000005 0x05 691 00:00:06 0x00000006 0x06 692 00:00:07 0x00000007 0x07 693 00:00:08 0x00000008 0x08 694 00:00:09 0x00000009 0x09 695 00:00:10 0x0000000a 0x0a 696 00:00:11 0x0000000b 0x0b 697 00:00:12 0x0000000c 0x0c 698 00:00:13 0x0000000d 0x0d 699 00:00:14 0x0000000e 0x0e 700 00:00:15 0x0000000f 0x0f 701 00:00:16 0x00000010 0x10 702 00:00:17 0x00000011 0x11 703 00:00:18 0x00000012 0x12 704 00:00:19 0x00000013 0x13 705 00:00:20 0x00000014 0x14 706 00:00:21 0x00000015 0x15 707 00:00:22 0x00000016 0x16 708 00:00:23 0x00000017 0x17 709 00:00:24 0x00000018 0x18 710 00:00:25 0x00000019 0x19 711 00:00:26 0x0000001a 0x1a 712 00:00:27 0x0000001b 0x1b 713 00:00:28 0x0000001c 0x1c 714 00:00:29 0x0000001d 0x1d 715 00:00:30 0x0000001e 0x1e 716 00:00:31 0x0000001f 0x1f 717 00:00:32 0x00000020 0x20 718 00:00:33 0x00000021 0x21 719 00:00:34 0x00000022 0x22 720 00:00:35 0x00000023 0x23 721 00:00:36 0x00000024 0x24 722 00:00:37 0x00000025 0x25 723 00:00:38 0x00000026 0x26 724 00:00:39 0x00000027 0x27 725 00:00:40 0x00000028 0x28 726 00:00:41 0x00000029 0x29 727 00:00:42 0x0000002a 0x2a 728 00:00:43 0x0000002b 0x2b 729 00:00:44 0x0000002c 0x2c 730 00:00:45 0x0000002d 0x2d 731 00:00:46 0x0000002e 0x2e 732 00:00:47 0x0000002f 0x2f 733 00:00:48 0x00000030 0x30 734 00:00:49 0x00000031 0x31 735 00:00:50 0x00000032 0x32 736 00:00:51 0x00000033 0x33 737 00:00:52 0x00000034 0x34 738 00:00:53 0x00000035 0x35 739 00:00:54 0x00000036 0x36 740 00:00:55 0x00000037 0x37 741 00:00:56 0x00000038 0x38 742 00:00:57 0x00000039 0x39 743 00:00:58 0x0000003a 0x3a 744 00:00:59 0x0000003b 0x3b 745 00:01:00 0x0000003c 0x3c 746 00:01:01 0x0000003d 0x3d 747 00:01:02 0x0000003e 0x3e 748 00:01:03 0x0000003f 0x3f 749 00:01:04 0x00000040 0x40 750 00:01:05 0x00000041 0x41 751 00:01:06 0x00000042 0x42 752 00:01:07 0x00000043 0x43 753 00:01:08 0x00000044 0x44 754 00:01:09 0x00000045 0x45 755 00:01:10 0x00000046 0x46 756 00:01:11 0x00000047 0x47 757 00:01:12 0x00000048 0x48 758 00:01:13 0x00000049 0x49 759 00:01:14 0x0000004a 0x4a 760 00:01:15 0x0000004b 0x4b 761 00:01:16 0x0000004c 0x4c 762 00:01:17 0x0000004d 0x4d 763 00:01:18 0x0000004e 0x4e 764 00:01:19 0x0000004f 0x4f 765 00:01:20 0x00000050 0x50 766 00:01:21 0x00000051 0x51 767 00:01:22 0x00000052 0x52 768 00:01:23 0x00000053 0x53 769 00:01:24 0x00000054 0x54 770 00:01:25 0x00000055 0x55 771 00:01:26 0x00000056 0x56 772 00:01:27 0x00000057 0x57 773 00:01:28 0x00000058 0x58 774 00:01:29 0x00000059 0x59 775 00:01:30 0x0000005a 0x5a 776 00:01:31 0x0000005b 0x5b 777 00:01:32 0x0000005c 0x5c 778 00:01:33 0x0000005d 0x5d 779 00:01:34 0x0000005e 0x5e 780 00:01:35 0x0000005f 0x5f 781 00:01:36 0x00000060 0x60 782 00:01:37 0x00000061 0x61 783 00:01:38 0x00000062 0x62 784 00:01:39 0x00000063 0x63 785 00:01:40 0x00000064 0x64 786 00:01:41 0x00000065 0x65 787 00:01:42 0x00000066 0x66 788 00:01:43 0x00000067 0x67 789 00:01:44 0x00000068 0x68 790 00:01:45 0x00000069 0x69 791 00:01:46 0x0000006a 0x6a 792 00:01:47 0x0000006b 0x6b 793 00:01:48 0x0000006c 0x6c 794 00:01:49 0x0000006d 0x6d 795 00:01:50 0x0000006e 0x6e 796 00:01:51 0x0000006f 0x6f 797 00:01:52 0x00000070 0x70 798 00:01:53 0x00000071 0x71 799 00:01:54 0x00000072 0x72 800 00:01:55 0x00000073 0x73 801 00:01:56 0x00000074 0x74 802 00:01:57 0x00000075 0x75 803 00:01:58 0x00000076 0x76 804 00:01:59 0x00000077 0x77 805 00:02:00 0x00000078 0x78 806 00:02:01 0x00000079 0x79 807 00:02:02 0x0000007a 0x7a 808 00:02:03 0x0000007b 0x7b 809 00:02:04 0x0000007c 0x7c 810 00:02:05 0x0000007d 0x7d 811 00:02:06 0x0000007e 0x7e 812 00:02:07 0x0000007f 0x7f 813 00:02:08 0x00000080 0x80 814 00:02:24 0x00000090 0x90 815 00:02:40 0x000000a0 0xa0 816 00:02:56 0x000000b0 0xb0 817 00:03:12 0x000000c0 0xc0 818 00:03:28 0x000000d0 0xd0 819 00:03:44 0x000000e0 0xe0 820 00:04:00 0x000000f0 0xf0 821 00:04:16 0x00000100 0x81 822 00:04:48 0x00000120 0x91 823 00:05:20 0x00000140 0xa1 824 00:05:52 0x00000160 0xb1 825 00:06:24 0x00000180 0xc1 826 00:06:56 0x000001a0 0xd1 827 00:07:28 0x000001c0 0xe1 828 00:08:00 0x000001e0 0xf1 829 00:08:32 0x00000200 0x82 830 00:09:36 0x00000240 0x92 831 00:10:40 0x00000280 0xa2 832 00:11:44 0x000002c0 0xb2 833 00:12:48 0x00000300 0xc2 834 00:13:52 0x00000340 0xd2 835 00:14:56 0x00000380 0xe2 836 00:16:00 0x000003c0 0xf2 837 00:17:04 0x00000400 0x83 838 00:19:12 0x00000480 0x93 839 00:21:20 0x00000500 0xa3 840 00:23:28 0x00000580 0xb3 841 00:25:36 0x00000600 0xc3 842 00:27:44 0x00000680 0xd3 843 00:29:52 0x00000700 0xe3 844 00:32:00 0x00000780 0xf3 845 00:34:08 0x00000800 0x84 846 00:38:24 0x00000900 0x94 847 00:42:40 0x00000a00 0xa4 848 00:46:56 0x00000b00 0xb4 849 00:51:12 0x00000c00 0xc4 850 00:55:28 0x00000d00 0xd4 851 00:59:44 0x00000e00 0xe4 852 01:04:00 0x00000f00 0xf4 853 01:08:16 0x00001000 0x85 854 01:16:48 0x00001200 0x95 855 01:25:20 0x00001400 0xa5 856 01:33:52 0x00001600 0xb5 857 01:42:24 0x00001800 0xc5 858 01:50:56 0x00001a00 0xd5 859 01:59:28 0x00001c00 0xe5 860 02:08:00 0x00001e00 0xf5 861 02:16:32 0x00002000 0x86 862 02:33:36 0x00002400 0x96 863 02:50:40 0x00002800 0xa6 864 03:07:44 0x00002c00 0xb6 865 03:24:48 0x00003000 0xc6 866 03:41:52 0x00003400 0xd6 867 03:58:56 0x00003800 0xe6 868 04:16:00 0x00003c00 0xf6 869 04:33:04 0x00004000 0x87 870 05:07:12 0x00004800 0x97 871 05:41:20 0x00005000 0xa7 872 06:15:28 0x00005800 0xb7 873 06:49:36 0x00006000 0xc7 874 07:23:44 0x00006800 0xd7 875 07:57:52 0x00007000 0xe7 876 08:32:00 0x00007800 0xf7 877 09:06:08 0x00008000 0x88 878 10:14:24 0x00009000 0x98 879 11:22:40 0x0000a000 0xa8 880 12:30:56 0x0000b000 0xb8 881 13:39:12 0x0000c000 0xc8 882 14:47:28 0x0000d000 0xd8 883 15:55:44 0x0000e000 0xe8 884 17:04:00 0x0000f000 0xf8 885 18:12:16 0x00010000 0x89 886 20:28:48 0x00012000 0x99 887 22:45:20 0x00014000 0xa9 888 1d 01:01:52 0x00016000 0xb9 889 1d 03:18:24 0x00018000 0xc9 890 1d 05:34:56 0x0001a000 0xd9 891 1d 07:51:28 0x0001c000 0xe9 892 1d 10:08:00 0x0001e000 0xf9 893 1d 12:24:32 0x00020000 0x8a 894 1d 16:57:36 0x00024000 0x9a 895 1d 21:30:40 0x00028000 0xaa 896 2d 02:03:44 0x0002c000 0xba 897 2d 06:36:48 0x00030000 0xca 898 2d 11:09:52 0x00034000 0xda 899 2d 15:42:56 0x00038000 0xea 900 2d 20:16:00 0x0003c000 0xfa 901 3d 00:49:04 0x00040000 0x8b 902 3d 09:55:12 0x00048000 0x9b 903 3d 19:01:20 0x00050000 0xab 904 4d 04:07:28 0x00058000 0xbb 905 4d 13:13:36 0x00060000 0xcb 906 4d 22:19:44 0x00068000 0xdb 907 5d 07:25:52 0x00070000 0xeb 908 5d 16:32:00 0x00078000 0xfb 909 6d 01:38:08 0x00080000 0x8c 910 6d 19:50:24 0x00090000 0x9c 911 7d 14:02:40 0x000a0000 0xac 912 8d 08:14:56 0x000b0000 0xbc 913 9d 02:27:12 0x000c0000 0xcc 914 9d 20:39:28 0x000d0000 0xdc 915 10d 14:51:44 0x000e0000 0xec 916 11d 09:04:00 0x000f0000 0xfc 917 12d 03:16:16 0x00100000 0x8d 918 13d 15:40:48 0x00120000 0x9d 919 15d 04:05:20 0x00140000 0xad 920 16d 16:29:52 0x00160000 0xbd 921 18d 04:54:24 0x00180000 0xcd 922 19d 17:18:56 0x001a0000 0xdd 923 21d 05:43:28 0x001c0000 0xed 924 22d 18:08:00 0x001e0000 0xfd 925 24d 06:32:32 0x00200000 0x8e 926 27d 07:21:36 0x00240000 0x9e 927 30d 08:10:40 0x00280000 0xae 928 33d 08:59:44 0x002c0000 0xbe 929 36d 09:48:48 0x00300000 0xce 930 39d 10:37:52 0x00340000 0xde 931 42d 11:26:56 0x00380000 0xee 932 45d 12:16:00 0x003c0000 0xfe 933 48d 13:05:04 0x00400000 0x8f 934 54d 14:43:12 0x00480000 0x9f 935 60d 16:21:20 0x00500000 0xaf 936 66d 17:59:28 0x00580000 0xbf 937 72d 19:37:36 0x00600000 0xcf 938 78d 21:15:44 0x00680000 0xdf 939 84d 22:53:52 0x00700000 0xef 940 91d 00:32:00 0x00780000 0xff (reserved) 942 Figure 5 944 Authors' Addresses 946 Carsten Bormann 947 Universitaet Bremen TZI 948 Postfach 330440 949 Bremen D-28359 950 Germany 952 Phone: +49-421-218-63921 953 Fax: +49-421-218-7000 954 Email: cabo@tzi.org 956 Klaus Hartke 957 Universitaet Bremen TZI 958 Postfach 330440 959 Bremen D-28359 960 Germany 962 Phone: +49-421-218-63905 963 Fax: +49-421-218-7000 964 Email: hartke@tzi.org