idnits 2.17.1 draft-bormann-coap-misc-18.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 1175 has weird spacing: '... code mid...' -- The document date (June 25, 2012) is 4323 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFCXXXX' is mentioned on line 727, but not defined -- Looks like a reference, but probably isn't: '0' on line 1534 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-09 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-05 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-19 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Outdated reference: A later version (-03) exists of draft-allman-tcpm-rto-consider-01 -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5405 (Obsoleted by RFC 8085) Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 6 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: December 27, 2012 June 25, 2012 7 Miscellaneous additions to CoAP 8 draft-bormann-coap-misc-18 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 December 27, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 2. Getting rid of artificial limitations . . . . . . . . . . . . 5 54 2.1. Option Length encoding beyond 270 bytes . . . . . . . . . 5 55 3. Registered Option . . . . . . . . . . . . . . . . . . . . . . 8 56 4. Patience, Leisure, and Pledge . . . . . . . . . . . . . . . . 10 57 4.1. Patience . . . . . . . . . . . . . . . . . . . . . . . . . 10 58 4.2. Leisure . . . . . . . . . . . . . . . . . . . . . . . . . 10 59 4.3. Pledge . . . . . . . . . . . . . . . . . . . . . . . . . . 11 60 4.4. Option Formats . . . . . . . . . . . . . . . . . . . . . . 11 61 5. CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 62 5.1. Requesting a Tunnel with CONNECT . . . . . . . . . . . . . 13 63 5.2. Using a CONNECT Tunnel . . . . . . . . . . . . . . . . . . 13 64 5.3. Closing down a CONNECT Tunnel . . . . . . . . . . . . . . 14 65 6. Protocol Constants and Time Constants . . . . . . . . . . . . 15 66 6.1. Protocol Constants . . . . . . . . . . . . . . . . . . . . 15 67 6.2. Time Constants derived from Protocol Constants . . . . . . 16 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 69 8. Security Considerations . . . . . . . . . . . . . . . . . . . 20 70 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 21 71 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 72 10.1. Normative References . . . . . . . . . . . . . . . . . . . 22 73 10.2. Informative References . . . . . . . . . . . . . . . . . . 22 74 Appendix A. The Nursery (Things that still need to ripen a 75 bit) . . . . . . . . . . . . . . . . . . . . . . . . 24 76 A.1. Envelope Options . . . . . . . . . . . . . . . . . . . . . 24 77 A.2. Payload-Length Option . . . . . . . . . . . . . . . . . . 25 78 A.3. URI Authorities with Binary Adresses . . . . . . . . . . . 25 79 A.4. Length-aware number encoding (o256) . . . . . . . . . . . 26 80 A.5. SMS encoding . . . . . . . . . . . . . . . . . . . . . . . 28 81 A.5.1. ASCII-optimized SMS encoding . . . . . . . . . . . . . 29 82 Appendix B. The Cemetery (Things we won't do) . . . . . . . . . . 32 83 B.1. Example envelope option: solving #230 . . . . . . . . . . 32 84 B.2. Example envelope option: proxy-elective options . . . . . 33 85 B.3. Stateful URI compression . . . . . . . . . . . . . . . . . 33 86 B.4. Beyond 270 bytes in a single option . . . . . . . . . . . 34 87 B.5. Beyond 15 options . . . . . . . . . . . . . . . . . . . . 35 88 B.5.1. Implementation considerations . . . . . . . . . . . . 37 89 B.5.2. What should we do now? . . . . . . . . . . . . . . . . 38 90 B.5.3. Alternatives . . . . . . . . . . . . . . . . . . . . . 38 91 B.5.4. Alternative: Going to a delimiter model . . . . . . . 38 92 B.6. Implementing the option delimiter for 15 or more 93 options . . . . . . . . . . . . . . . . . . . . . . . . . 38 94 Appendix C. Experimental Options . . . . . . . . . . . . . . . . 40 95 C.1. Options indicating absolute time . . . . . . . . . . . . . 40 96 C.2. Representing Durations . . . . . . . . . . . . . . . . . . 41 97 C.3. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 42 98 C.4. Pseudo-Floating Point . . . . . . . . . . . . . . . . . . 43 99 C.5. A Duration Type for CoAP . . . . . . . . . . . . . . . . . 44 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 102 1. Introduction 104 The CoRE WG is tasked with standardizing an Application Protocol for 105 Constrained Networks/Nodes, CoAP [I-D.ietf-core-coap]. This protocol 106 is intended to provide RESTful [REST] services not unlike HTTP 107 [RFC2616], while reducing the complexity of implementation as well as 108 the size of packets exchanged in order to make these services useful 109 in a highly constrained network of themselves highly constrained 110 nodes. 112 This objective requires restraint in a number of sometimes 113 conflicting ways: 115 o reducing implementation complexity in order to minimize code size, 117 o reducing message sizes in order to minimize the number of 118 fragments needed for each message (in turn to maximize the 119 probability of delivery of the message), the amount of 120 transmission power needed and the loading of the limited-bandwidth 121 channel, 123 o reducing requirements on the environment such as stable storage, 124 good sources of randomness or user interaction capabilities. 126 This draft attempts to address a number of problems not yet 127 adequately solved in [I-D.ietf-core-coap]. The solutions proposed to 128 these problems are somewhat interrelated and are therefore presented 129 in one draft. 131 The appendix contains the "CoAP cemetery" (possibly later to move 132 into its own draft), documenting roads that the WG decided not to 133 take, in order to spare readers from reinventing them in vain. 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 137 document are to be interpreted as described in [RFC2119]. 139 The term "byte" is used in its now customary sense as a synonym for 140 "octet". 142 2. Getting rid of artificial limitations 144 _Artificial limitations_ are limitations of a protocol or system that 145 are not rooted in limitations of actual capabilities, but in 146 arbitrary design decisions. Proper system design tries to avoid 147 artificial limitations, as these tend to cause complexity in systems 148 that need to work with these limitations. 150 E.g., the original UNIX filesystem had an artificial limitation of 151 the length of a path name component to 14 bytes. This led to a 152 cascade of workarounds in programs that manipulate file names: E.g., 153 systematically replacing a ".el" extension in a filename with a 154 ".elc" for the compiled file might exceed the limit, so all ".el" 155 files were suddenly limited to 13-byte filenames. 157 Note that, today, there still is a limitation in most file system 158 implementations, typically at 255. This just happens to be high 159 enough to rarely be of real-world concern; we will refer to this case 160 as a "painless" artificial limitation. 162 CoAP-08 had two highly recognizable artificial limitations in its 163 protocol encoding 165 o The number of options in a single message is limited to 15 max. 167 o The length of an option is limited to 270 max. 169 It has been argued that the latter limitation causes few problems, 170 just as the 255-byte path name component limitation in filenames 171 today causes few problems. Appendix B.4 provided a design to extend 172 this; as a precaution to future extensions of this kind, the current 173 encoding for length 270 (eight ones in the extension byte) could be 174 marked as reserved today. Since, Matthias Kovatsch has proposed a 175 simpler scheme that seems to gain favor in the WG, see Section 2.1. 177 The former limitation has been solved in CoAP-09. A historical 178 discussion of other approaches for going beyond 15 options is in 179 Appendix B.5. Appendix B.6 discusses implementation. 181 2.1. Option Length encoding beyond 270 bytes 183 For option lengths beyond 270 bytes, we reserve the value 255 of an 184 extension byte to mean "add 255, read another extension byte" 185 Figure 1. While this causes the length of the option header to grow 186 linearly with the size of the option value, only 0.4 % of that size 187 is used. With a focus on short options, this encoding is justified. 189 for 15..269: 190 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 191 | Option Delta | 1 1 1 1 | Length - 15 | 192 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 193 | Option Value ... 194 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 196 for 270..524: 197 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 198 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 199 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 200 | Length - 270 | Option Value ... 201 +---+---+---+---+---+---+---+---+ 202 | 203 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 205 for 525..779: 206 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 207 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 208 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 209 | 1 1 1 1 1 1 1 1 | Length - 525 | 210 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 211 | Option Value ... 212 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 214 for 780..1034: 215 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 216 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 217 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 218 | 1 1 1 1 1 1 1 1 | 1 1 1 1 1 1 1 1 | 219 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 220 | Length - 780 | Option Value ... 221 +---+---+---+---+---+---+---+---+ 222 | 223 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 225 Figure 1: Options beyond 270 bytes 227 Options that are longer than 1034 bytes MUST NOT be sent; an option 228 that has 255 (all one bits) in the field called "Length - 780" MUST 229 be rejected upon reception as an invalid option. 231 In the process, the maximum length of all options that are currently 232 set at 270 should now be set to a carefully chosen value. With the 233 purely encoding-based limit gone, Uri-Proxy should now be restored to 234 be a non-repeatable option. 236 A first proposal for a new set of per-option length restrictions 237 follows: 239 +--------+---------------------+-----+------+--------+--------+ 240 | number | name | min | max | type | repeat | 241 +--------+---------------------+-----+------+--------+--------+ 242 | 1 | content_type | 0 | 2 | uint | - | 243 | | | | | | | 244 | 2 | max_age | 0 | 4 | uint | - | 245 | | | | | | | 246 | 3 | proxy_uri | 1 | 1023 | string | - | 247 | | | | | | | 248 | 4 | etag | 1 | 8 | opaque | yes | 249 | | | | | | | 250 | 5 | uri_host | 1 | 255 | string | - | 251 | | | | | | | 252 | 6 | location_path | 0 | 255 | string | yes | 253 | | | | | | | 254 | 7 | uri_port | 0 | 2 | uint | - | 255 | | | | | | | 256 | 8 | location_query | 0 | 255 | string | yes | 257 | | | | | | | 258 | 9 | uri_path | 0 | 255 | string | yes | 259 | | | | | | | 260 | 10 | observe | 0 | 2 | uint | - | 261 | | | | | | | 262 | 11 | token | 1 | 8 | opaque | - | 263 | | | | | | | 264 | 12 | accept | 0 | 2 | uint | yes | 265 | | | | | | | 266 | 13 | if_match | 0 | 8 | opaque | yes | 267 | | | | | | | 268 | 14 | registered_elective | 1 | 1023 | opaque | yes | 269 | | | | | | | 270 | 15 | uri_query | 1 | 255 | string | yes | 271 | | | | | | | 272 | 17 | block2 | 0 | 3 | uint | - | 273 | | | | | | | 274 | 18 | size | 0 | 4 | uint | - | 275 | | | | | | | 276 | 19 | block1 | 0 | 3 | uint | - | 277 | | | | | | | 278 | 21 | if_none_match | 0 | 0 | empty | - | 279 | | | | | | | 280 | 25 | registered_critical | 1 | 1023 | opaque | yes | 281 +--------+---------------------+-----+------+--------+--------+ 283 (Option 14 with a length of 0 is a fencepost only.) 285 3. Registered Option 287 CoAP's option encoding is highly efficient, but works best with small 288 option numbers that do not require much fenceposting. The CoAP 289 Option Number Registry therefore has a relatively heavyweight 290 registration requirement: "IETF Review" as described in [RFC5226]. 292 However, there is also considerable benefit in a much looser registry 293 of suboption numbers, with an expert review [RFC5226] (or even first- 294 come-first-served) registration policy. If expert review is selected 295 for this registry, it would be with a relatively loose policy 296 delegated to the expert. This draft proposes leaving the registered 297 suboption numbers 0-127 to expert review with a policy that mainly 298 focuses on the availability of a specification, and 128-16383 for 299 first-come-first-served where essentially only a name is defined. 301 The "registered" options are used in conjunction with this suboption 302 number registry. They use two normal CoAP option numbers, one for 303 options with elective semantics (Registered-Elective) and one for 304 options with critical semantics (Registered-Critical). The suboption 305 numbers are not separate, i.e. one registered suboption number might 306 have some elective semantics and some other critical semantics (e.g., 307 for the request and the response leg of an exchange). The option 308 value starts with an SDNV [RFC6256] of the registered suboption 309 number. (Note that there is no need for an implementation to 310 understand SDNVs, it can treat the prefixes as opaque. One could 311 consider the SDNVs as a suboption prefix allocation guideline for 312 IANA as opposed to a number encoding.) 314 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 315 |1 0 0 0 0 0 0 1|0 1 1 1 0 0 1 1| value... | 316 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 317 \___SDNV of registered number___/ 319 Figure 2: Example option value for registered option 321 Note that a Registered Option cannot be empty, because there would be 322 no space for the SDNV. Also, the empty option 14 is reserved for 323 fenceposting ([I-D.ietf-core-coap], section 3.2). (Obviously, once a 324 Registered-Elective Option is in use, there is never a need for a 325 fence-post for option number 14.) 327 The Registered-Elective and Registered-Critical Options are 328 repeatable. 330 +-----+----------+---------------------+---------+--------+---------+ 331 | No. | C/E | Name | Format | Length | Default | 332 +-----+----------+---------------------+---------+--------+---------+ 333 | 14 | Elective | Registered-Elective | (see | 1-1023 | (none) | 334 | | | | above) | B | | 335 | | | | | | | 336 | 25 | Critical | Registered-Critical | (see | 1-1023 | (none) | 337 | | | | above) | B | | 338 +-----+----------+---------------------+---------+--------+---------+ 340 This solves CoRE issue #214 [CoRE214]. (How many options we need 341 will depend on the resolution of #241 [CoRE241].) 343 4. Patience, Leisure, and Pledge 345 A number of options might be useful for controlling the timing of 346 interactions. 348 (This section also addresses core-coap ticket #177.) 350 4.1. Patience 352 A client may have a limited time period in which it can actually make 353 use of the response for a request. Using the Patience option, it can 354 provide an (elective) indication how much time it is willing to wait 355 for the response from the server, giving the server license to ignore 356 or reject the request if it cannot fulfill it in this period. 358 If the server knows early that it cannot fulfill the request in the 359 time requested, it MAY indicate this with a 5.04 "Timeout" response. 360 For non-safe methods (such as PUT, POST, DELETE), the server SHOULD 361 indicate whether it has fulfilled the request by either responding 362 with 5.04 "Timeout" (and not further processing the request) or by 363 processing the request normally. 365 Note that the value of the Patience option should be chosen such that 366 the client will be able to make use of the result even in the 367 presence of the expected network delays for the request and the 368 response. Similarly, when a proxy receives a request with a Patience 369 option and cannot fulfill that request from its cache, it may want to 370 adjust the value of the option before forwarding it to an upstream 371 server. 373 (TBD: The various cases that arise when combining Patience with 374 Observe.) 376 The Patience option is elective. Hence, a client MUST be prepared to 377 receive a normal response even after the chosen Patience period (plus 378 an allowance for network delays) has elapsed. 380 4.2. Leisure 382 Servers generally will compute an internal value that we will call 383 Leisure, which indicates the period of time that will be used for 384 responding to a request. A Patience option, if present, can be used 385 as an upper bound for the Leisure. Leisure may be non-zero for 386 congestion control reasons, in particular for responses to multicast 387 requests. For these, the server should have a group size estimate G, 388 a target rate R (which both should be chosen conservatively) and an 389 estimated response size S; a rough lower bound for Leisure can then 390 be computed as follows: 392 lb_Leisure = S * G / R 394 Figure 3: Computing a lower bound for the Leisure 396 E.g., for a multicast request with link-local scope on an 2.4 GHz 397 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 398 conservatively) set to 100, S to 100 bytes, and the target rate to 8 399 kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10 400 seconds. 402 To avoid response implosion, responses to multicast requests SHOULD 403 be dithered within a Leisure period chosen by the server to fall 404 between these two bounds. 406 Currently, we don't foresee a need to signal a value for Leisure from 407 client to server (beyond the signalling provided by Patience) or from 408 server to client, but an appropriate Option might be added later. 410 4.3. Pledge 412 In a basic observation relationship [I-D.ietf-core-observe], the 413 server makes a pledge to keep the client in the observation 414 relationship for a resource at least until the max-age for the 415 resource is reached. 417 To save the client some effort in re-establishing observation 418 relationships each time max-age is reached, the server MAY want to 419 extend its pledge beyond the end of max-age by signalling in a 420 response/notification an additional time period using the Pledge 421 Option, in parallel to the Observe Option. 423 The Pledge Option MUST NOT be used unless the server can make a 424 reasonable promise not to lose the observation relationship in this 425 time frame. 427 Currently, we don't foresee a need to signal a value for Pledge from 428 client to server, but an appropriate behavior might be added later 429 for this option when sent in a request. 431 4.4. Option Formats 433 +-----+----------+----------+-----------------+--------+---------+ 434 | No. | C/E | Name | Format | Length | Default | 435 +-----+----------+----------+-----------------+--------+---------+ 436 | 22 | Elective | Patience | Duration in mis | 1 B | (none) | 437 | | | | | | | 438 | 24 | Elective | Pledge | Duration in s | 1 B | 0 | 439 +-----+----------+----------+-----------------+--------+---------+ 441 All timing options use the Duration data type (see Appendix C.2), 442 however Patience (and Leisure, if that ever becomes an option) uses a 443 timebase of mibiseconds (mis = 1/1024 s) instead of seconds. (This 444 reduces the range of the Duration from ~ 91 days to 128 minutes.) 446 Implementation note: As there are no strong accuracy requirements on 447 the clocks employed, making use of any existing time base of 448 milliseconds is a valid implementation approach (2.4 % off). 450 None of the options may be repeated. 452 5. CONNECT 454 [RFC2817] defines the HTTP CONNECT method to establish a TCP tunnel 455 through a proxy so that end-to-end TLS connections can be made 456 through the proxy. Recently, a requirement for similar functionality 457 has been discussed for CoAP. This section defines a straw-man 458 CONNECT method and related methods and response codes for CoAP. 460 (IANA considerations for this section TBD.) 462 5.1. Requesting a Tunnel with CONNECT 464 CONNECT is allocated as a new method code in the "CoAP Method Codes" 465 registry. When a client makes a CONNECT request to an intermediary, 466 the intermediary evaluates the Uri-Host, Uri-Port, and/or the 467 authority part of the Proxy-Uri Options in a way that is defined by 468 the security policy of the intermediary. If the security policy 469 allows the allocation of a tunnel based on these parameters, the 470 method returns an empty payload and a response code of 2.30 Tunnel 471 Established. Other possible response codes include 4.03 Forbidden. 473 It may be the case that the intermediary itself can only reach the 474 requested origin server through another intermediary. In this case, 475 the first intermediary SHOULD make a CONNECT request of that next 476 intermediary, requesting a tunnel to the authority. A proxy MUST NOT 477 respond with any 2.xx status code unless it has either a direct or 478 tunnel connection established to the authority. 480 An origin server which receives a CONNECT request for itself MAY 481 respond with a 2.xx status code to indicate that a tunnel is 482 established to itself. 484 Code 2.30 "Tunnel Established" is allocated as a new response code in 485 the "CoAP Response Codes" registry. 487 5.2. Using a CONNECT Tunnel 489 Any successful (2.xx) response to a CONNECT request indicates that 490 the intermediary has established a tunnel to the requested host and 491 port. The tunnel is bound to the requesting end-point and the Token 492 supplied in the request (as always, the default Token is admissible). 493 The tunnel can be used by the client by making a DATAGRAM request. 495 DATAGRAM is allocated as a new method code in the "CoAP Method Codes" 496 registry. When a client makes a DATAGRAM request to an intermediary, 497 the intermediary looks up the tunnel bound to the client end-point 498 and Token supplied in the DATAGRAM request (no other Options are 499 permitted). If a tunnel is found and the intermediary's security 500 policy permits, the intermediary forwards the payload of the DATAGRAM 501 request as the UDP payload towards the host and port established for 502 the tunnel. No response is defined for this request (note that the 503 request can be given as a CON or NON request; for CON, there will be 504 an ACK on the message layer if the tunnel exists). 506 The security policy on the intermediary may restrict the allowable 507 payloads based on its security policy, possibly considering host and 508 port. An inadmissible payload SHOULD cause a 4.03 Forbidden response 509 with a diagnostic message as payload. 511 The UDP payload of any datagram received from the tunnel and admitted 512 by the security policy is forwarded to the client as the payload of a 513 2.31 "Datagram Received" response. The response does not carry any 514 Option except for Token, which identifies the tunnel towards the 515 client. 517 Code 2.31 "Datagram Received" is allocated as a new response code in 518 the "CoAP Response Codes" registry. 520 An origin server that has established a tunnel to itself processes 521 the CoAP payloads of related DATAGRAM requests as it would process an 522 incoming UDP payload, and forwards what would be outgoing UDP 523 payloads in 2.31 "Datagram Received" responses. 525 5.3. Closing down a CONNECT Tunnel 527 A 2.31 "Datagram Received" response may be replied to with a RST, 528 which closes down the tunnel. Similarly, the Token used in the 529 tunnel may be reused by the client for a different purpose, which 530 also closes down the tunnel. 532 6. Protocol Constants and Time Constants 534 CoAP defines a number of time-related protocol constants. There are 535 also a number of assumptions about the timing behavior of the 536 network. This section attempts to provide input to a possible 537 update, addressing #201 [CoRE201]. 539 6.1. Protocol Constants 541 Section 9 of [I-D.ietf-core-coap] defines three protocol constants: 543 +------------------------+---------------+ 544 | name | default value | 545 +------------------------+---------------+ 546 | RESPONSE_TIMEOUT | 2 seconds | 547 | | | 548 | RESPONSE_RANDOM_FACTOR | 1.5 | 549 | | | 550 | MAX_RETRANSMIT | 4 | 551 +------------------------+---------------+ 553 Section 9 gives license to a configuration to modify these protocol 554 constants, without specifying a configuration method. It also does 555 not give any further guidance. Both Cullen Jennings (msg03072by) and 556 Michael Scharf (msg03280e) have argued we do need some additional 557 guidance here. 559 In particular, Michael Scharf notes that 561 o a decrease of RESPONSE_TIMEOUT below 1 second would violate the 562 guidelines of RFC 5405, and it would not be safe for use in the 563 Internet; 565 o significantly decreasing the RESPONSE_TIMEOUT would require an 566 adaptive RTT measurement to be robust, see RFC 5405 or 567 draft-allman-tcpm-rto-consider. [...] the draft should strongly 568 discourage any decrease of RESPONSE_TIMEOUT until such more 569 advanced mechanisms exist, and it should explain why. 571 We should therefore add the following text at the end of Section 9: 573 The protocol constants have been chosen to achieve a behavior in 574 the presence of congestion that is safe in the Internet. If a 575 configuration desires to use different values, the onus is on the 576 configuration to ensure these congestion control properties are 577 not violated. In particular, a decrease of RESPONSE_TIMEOUT below 578 1 second would violate the guidelines of [RFC5405]. 579 ([I-D.allman-tcpm-rto-consider] provides some additional 580 background.) CoAP was designed to enable implementations that do 581 not maintain round-trip-time (RTT) measurements. However, where 582 it is desired to decrease the RESPONSE_TIMEOUT significantly, this 583 can only be done safely when maintaining such measurements. 584 Configurations MUST NOT decrease RESPONSE_TIMEOUT without using 585 mechanisms that ensure congestion control safety, either defined 586 in the configuration or in future standards documents. 588 RESPONSE_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it 589 SHOULD have a value that is sufficiently different from 1.0 to 590 provide some protection from synchronization effects. 592 MAX_RETRANSMIT can be freely adjusted, but a too small value will 593 reduce the probability that a confirmed message is actually 594 received, while a larger value will require further adjustments in 595 the time constants (see discussion below). 597 If the choice of protocol constants leads to an increase of 598 derived time constants (see below), the configuration mechanism 599 MUST ensure the adjusted value is available to the corresponding 600 end-points, too. 602 6.2. Time Constants derived from Protocol Constants 604 (This section might become a new section 9.2 in [I-D.ietf-core-coap]. 605 The various places where these calculations are included in the text, 606 e.g., section 4.1, can then just use these numbers.) 608 The combination of RESPONSE_TIMEOUT, RESPONSE_RANDOM_FACTOR and 609 MAX_RETRANSMIT influences the timing of retransmissions, which in 610 turn influences how long certain information items need to be kept by 611 an implementation. To be able to unambiguously reference these 612 derived time constants, we give them names as follows: 614 o MAX_TRANSMIT_SPAN is the maximum time from the first transmission 615 of a confirmed message to its last retransmission. For the 616 default protocol constants, the value is (2+4+8+16)*1.5 = 45 617 seconds, or more generally: 619 RESPONSE_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * 620 RESPONSE_RANDOM_FACTOR 622 o MAX_TRANSMIT_WAIT is the maximum time from the first transmission 623 of a confirmed message to the time when the sender gives up on 624 receiving a response. For the default protocol constants, the 625 value is (2+4+8+16+32)*1.5 = 93 seconds, or more generally: 627 RESPONSE_TIMEOUT * (2 ** (MAX_RETRANSMIT + 1) - 1) * 628 RESPONSE_RANDOM_FACTOR 630 In addition, some assumptions need to be made on the characteristics 631 of the network and the nodes. 633 o MAX_LATENCY is the maximum time a datagram is expected to take 634 from the start of its transmission to the completion of its 635 reception. This constant is related to the MSL (Maximum Segment 636 Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 637 minutes" ([RFC0793] glossary, page 81). Note that this is not 638 necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not 639 intended to describe a situation when the protocol works well, but 640 the worst case situation against which the protocol has to guard. 641 We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart 642 from being reasonably realistic for the bulk of configurations as 643 well as close to the historic choice for TCP, this value also 644 allows message ID lifetime timers to be represented in 8 bits 645 (when measured in seconds). In these calculations, there is no 646 assumption that the direction of the transmission is irrelevant 647 (i.e. that the network is symmetric), just that the same value can 648 reasonably be used as a maximum value for both directions. If 649 that is not the case, the following calculations become only 650 slightly more complex. 652 o PROCESSING_DELAY is the time a node takes to turn around a 653 confirmed message into an acknowledgement. We assume the node 654 will attempt to send an ACK before having the sender time out, so 655 as a conservative assumption we set it equal to RESPONSE_TIMEOUT. 657 o MAX_RTT is the maximum round-trip time, or: 659 2 * MAX_LATENCY + PROCESSING_DELAY 661 From these constants, we can derive the following values relevant to 662 the protocol operation: 664 o EXCHANGE_LIFETIME is the time from starting to send a confirmed 665 message to the time when a response is no longer expected, i.e. 666 message layer information about the message exchange can be 667 purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a 668 MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the 669 way back. Note that there is no need to consider 670 MAX_TRANSMIT_WAIT if the configuration is chosen such that the 671 last waiting period (RESPONSE_TIMEOUT * (2 ** MAX_RETRANSMIT) or 672 the difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is 673 less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY 674 is a worst case value unlikely to be met in the real world. In 675 this case, EXCHANGE_LIFETIME simplifies to: 677 (RESPONSE_TIMEOUT * (2 ** MAX_RETRANSMIT) * 678 RESPONSE_RANDOM_FACTOR) + (2 * MAX_LATENCY) 680 or 248 seconds with the default protocol constants. 682 o NON_LIFETIME is the time from sending a non-confirmed message to 683 the time its message-ID can be safely reused. If multiple 684 transmission of a NON message is not used, its value is 685 MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a 686 NON message multiple times, in particular for multicast 687 applications. While the period of re-use is not bounded by the 688 specification, an expectation of reliable detection of duplication 689 at the receiver is in the timescales of MAX_TRANSMIT_SPAN. 690 Therefore, for this purpose, it is safer to use the value: 692 MAX_TRANSMIT_SPAN + MAX_LATENCY 694 or 145 seconds with the default protocol constants; however, an 695 implementation that just wants to use a single timeout value for 696 retiring message-IDs can safely use the larger value for 697 EXCHANGE_LIFETIME. 699 o (others? We need to go through [I-D.ietf-core-coap] and find 700 places where we can substitute in these constants.) 702 7. IANA Considerations 704 This draft adds option numbers to Table 2 of [I-D.ietf-core-coap]: 706 +--------+---------------------+-----------+ 707 | Number | Name | Reference | 708 +--------+---------------------+-----------+ 709 | 14 | Registered-Elective | [RFCXXXX] | 710 | | | | 711 | 22 | Patience | [RFCXXXX] | 712 | | | | 713 | 24 | Pledge | [RFCXXXX] | 714 | | | | 715 | 25 | Registered-Critical | [RFCXXXX] | 716 +--------+---------------------+-----------+ 718 Table 1: New CoAP Option Numbers 720 This draft adds a suboption registry, initially empty. 722 +------------+-----------------------------+-----------+ 723 | Number | Name | Reference | 724 +------------+-----------------------------+-----------+ 725 | 0..127 | (allocate on export review) | [RFCXXXX] | 726 | | | | 727 | 128..16383 | (allocate fcfs) | [RFCXXXX] | 728 +------------+-----------------------------+-----------+ 730 Table 2: CoAP Suboption Numbers 732 8. Security Considerations 734 TBD. 736 9. Acknowledgements 738 This work was partially funded by the Klaus Tschira Foundation and by 739 Intel Corporation. 741 Of course, much of the content of this draft is the result of 742 discussions with the [I-D.ietf-core-coap] authors. 744 Patience and Leisure were influenced by a mailing list discussion 745 with Esko Dijk, Kepeng Li, and Salvatore Loreto - thanks! 747 10. References 749 10.1. Normative References 751 [I-D.ietf-core-coap] 752 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 753 "Constrained Application Protocol (CoAP)", 754 draft-ietf-core-coap-09 (work in progress), March 2012. 756 [I-D.ietf-core-observe] 757 Hartke, K., "Observing Resources in CoAP", 758 draft-ietf-core-observe-05 (work in progress), March 2012. 760 [I-D.ietf-httpbis-p1-messaging] 761 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 762 1: URIs, Connections, and Message Parsing", 763 draft-ietf-httpbis-p1-messaging-19 (work in progress), 764 March 2012. 766 [I-D.ietf-httpbis-p4-conditional] 767 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 768 4: Conditional Requests", 769 draft-ietf-httpbis-p4-conditional-19 (work in progress), 770 March 2012. 772 [I-D.ietf-httpbis-p6-cache] 773 Fielding, R., Lafon, Y., Nottingham, M., and J. Reschke, 774 "HTTP/1.1, part 6: Caching", 775 draft-ietf-httpbis-p6-cache-19 (work in progress), 776 March 2012. 778 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 779 Requirement Levels", BCP 14, RFC 2119, March 1997. 781 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 782 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 783 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 785 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 786 Encodings", RFC 4648, October 2006. 788 [RFC6256] Eddy, W. and E. Davies, "Using Self-Delimiting Numeric 789 Values in Protocols", RFC 6256, May 2011. 791 10.2. Informative References 793 [CoRE201] "Multiple Location options need to be processed as a 794 unit", CoRE ticket #201, 2012, 795 . 797 [CoRE214] "Adopt vendor-defined option into core-coap", CoRE 798 ticket #214, 2012, 799 . 801 [CoRE230] "Multiple Location options need to be processed as a 802 unit", CoRE ticket #230, 2012, 803 . 805 [CoRE241] "Proxy Safe & Cache Key indication for options", CoRE 806 ticket #241, 2012, 807 . 809 [I-D.allman-tcpm-rto-consider] 810 Allman, M., "Retransmission Timeout Considerations", 811 draft-allman-tcpm-rto-consider-01 (work in progress), 812 May 2012. 814 [REST] Fielding, R., "Architectural Styles and the Design of 815 Network-based Software Architectures", 2000. 817 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 818 RFC 793, September 1981. 820 [RFC1924] Elz, R., "A Compact Representation of IPv6 Addresses", 821 RFC 1924, April 1996. 823 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 824 HTTP/1.1", RFC 2817, May 2000. 826 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 827 Interchange", RFC 5198, March 2008. 829 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 830 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 831 May 2008. 833 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 834 for Application Designers", BCP 145, RFC 5405, 835 November 2008. 837 Appendix A. The Nursery (Things that still need to ripen a bit) 839 A.1. Envelope Options 841 As of [I-D.ietf-core-coap], options can take one of four types, two 842 of which are mostly identical: 844 o uint: A non-negative integer which is represented in network byte 845 order using a variable number of bytes (see [I-D.ietf-core-coap] 846 Appendix A); 848 o string: a sequence of bytes that is nominally a Net-Unicode string 849 [RFC5198]; 851 o opaque: a sequence of bytes. 853 o empty (not explicitly identified as a fourth type in 854 [I-D.ietf-core-coap]). 856 It turns out some options would benefit from some internal structure. 857 Also, it may be a good idea to be able to bundle multiple options 858 into one, in order to ensure consistency for a set of elective 859 options that need to be processed all or nothing (i.e., the option 860 becomes critical as soon as another option out of the set is 861 processed, too). 863 In this section, we introduce a fifth CoAP option type: Envelope 864 options. 866 An envelope option is a sequence of bytes that looks and is 867 interpreted exactly like a CoAP sequence of options. Instead of an 868 option count or an end-of-option marker, the sequence of options is 869 terminated by the end of the envelope option. 871 The nested options (options inside the envelope option) may come from 872 the same number space as the top-level CoAP options, or the envelope 873 option may define its own number space - this choice needs to be 874 defined for each envelope option. 876 If the top-level number space is used, the envelope option typically 877 will restrict the set of options that actually can be used in the 878 envelope. In particular, it is unlikely that an envelope option will 879 allow itself inside the envelope (this would be a recursive option). 881 Envelope options are a general, but simple mechanism. Some of its 882 potential uses are illustrated by two examples in the cemetery: 883 Appendix B.1 and Appendix B.2. (Each of these examples has its own 884 merits and demerits, which led us to decide not to pursue either of 885 them right now, but this should be discussed separately from the 886 concept of Envelope options employed in the examples.) 888 A.2. Payload-Length Option 890 Not all transport mappings may provide an unambiguous length of the 891 CoAP message. For UDP, it may also be desirable to pack more than 892 one CoAP message into one UDP payload (aggregation); in that case, 893 for all but the last message there needs to be a way to delimit the 894 payload of that message. 896 This can be solved using a new option, the Payload-Length option. If 897 this option is present, the value of this option is an unsigned 898 integer giving the length of the payload of the message (note that 899 this integer can be zero for a zero-length payload, which can in turn 900 be represented by a zero-length option value). (In the UDP 901 aggregation case, what would have been in the payload of this message 902 after "payload-length" bytes is then actually one or more additional 903 messages.) 905 A.3. URI Authorities with Binary Adresses 907 One problem with the way URI authorities are represented in the URI 908 syntax is that the authority part can be very bulky if it encodes an 909 IPv6 address in ASCII. 911 Proposal: Provide an option "Uri-Authority-Binary" that can be an 912 even number of bytes between 2 and 18 except 12 or 14. 914 o If the number of bytes is 2, the destination IP address of the 915 packet transporting the CoAP message is implied. 917 o If the number of bytes is 4 or 6, the first four bytes of the 918 option value are an IPv4 address in binary. 920 o If the number of bytes is 8 or 10, the first eight bytes are the 921 lower 64 bits of an IPv6 address; the upper eight bytes are 922 implied from the destination address of the packet transporting 923 the CoAP message. 925 o If the number of bytes is 16 or 18, the first 16 bytes are an IPv6 926 address. 928 o If two more bytes remain, this is a port number (as always in 929 network byte order). 931 The resulting authority is (conceptually translated into ASCII and) 932 used in place of an Uri-Authority option, or inserted into a Proxy- 933 Uri. Examples: 935 +-------------+------------------+---------+------------------------+ 936 | Proxy-Uri | Uri-Authority-Bi | Uri-Pat | URI | 937 | | nary | h | | 938 +-------------+------------------+---------+------------------------+ 939 | (none) | (none) | (none) | "/" | 940 | | | | | 941 | (none) | (none) | 'temp' | "/temp" | 942 | | | | | 943 | (none) | 2 bytes: 61616 | 'temp' | "coap://[DA]:61616/tem | 944 | | | | p" | 945 | | | | | 946 | (none) | 16 bytes: | temp | "coap://[2000::1]/temp | 947 | | 2000::1 | | " | 948 | | | | | 949 | 'http://' | 10 bytes: | (none) | "http://[DA::123:45]:6 | 950 | | ::123:45 + 616 | | 16" | 951 | | | | | 952 | 'http:///te | 18 bytes: | (none) | "http://[2000::1]:616/ | 953 | mp' | 2000::1 + 616 | | temp" | 954 +-------------+------------------+---------+------------------------+ 956 A.4. Length-aware number encoding (o256) 958 The number encoding defined in Appendix A of [I-D.ietf-core-coap] has 959 one significant flaw: Every number has an infinite number of 960 representations, which can be derived by adding leading zero bytes. 961 This runs against the principle of minimizing unnecessary choice. 962 The resulting uncertainty in encoding ultimately leads to unnecessary 963 interoperability failures. (It also wastes a small fraction of the 964 encoding space, i.e., it wastes bytes.) 966 We could solve the first, but not the second, by outlawing leading 967 zeroes, but then we have to cope with error cases caused by illegal 968 values, another source of interoperability problems. 970 The number encoding "o256" defined in this section avoids this flaw. 971 The suggestion is not to replace CoAP's "uint" encoding wholesale 972 (CoAP is already too widely implemented for such a change), but to 973 consider this format for new options. 975 The basic requirements for such an encoding are: 977 o numbers are encoded as a sequence of zero or more bytes 979 o each number has exactly one encoding 980 o for a < b, encoding-size(a) <= encoding-size(b) -- i.e., with 981 larger numbers, the encoding only gets larger, never smaller 982 again. 984 o within each encoding size (0 bytes, 1 byte, etc.), lexicographical 985 ordering of the bytes is the same as numeric ordering 987 Obviously, there is only one encoding that satisfies all these 988 requirements. As illustrated by Figure 4, this is unambiguously 989 derived by 991 1. enumerating all possible byte sequences, ordered by length and 992 within the same length in lexicographic ordering, and, 994 2. assigning sequential cardinals. 996 0x'' -> 0 997 0x'00' -> 1 998 0x'01' -> 2 999 0x'02' -> 3 1000 ... 1001 0x'fe' -> 255 1002 0x'ff' -> 256 1003 0x'0000' -> 257 1004 0x'0001' -> 258 1005 ... 1006 0x'fefd' -> 65534 1007 0x'fefe' -> 65535 1008 0x'feff' -> 65536 1009 ... 1010 0x'ffff' -> 65792 1011 0x'000000' -> 65793 1012 0x'000001' -> 65794 1014 Figure 4: Enumerating byte sequences by length and then lexicographic 1015 order 1017 This results in an exceedingly simple algorithm: each byte is 1018 interpreted in the base-256 place-value system, but stands for a 1019 number between 1 and 256 instead of 0 to 255. We therefore call this 1020 encoding "o256" (one-to-256). 0 is always encoded in zero bytes; 1 to 1021 256 is one byte, 257 (0x101) to 65792 (0x10100) is two bytes, 65793 1022 (0x10101) to 16843008 (0x1010100) is three bytes, etc. 1024 To further illustrate the algorithmic simplicity, pseudocode for 1025 encoding and decoding is given in Figure 5 and Figure 6, respectively 1026 (in the encoder, "prepend" stands for adding a byte at the _leading_ 1027 edge, the requirement for which is a result of the network byte 1028 order). Note that this differs only in a single subtraction/addition 1029 (resp.) of one from the canonical algorithm for Appendix A uints. 1031 while num > 0 1032 num -= 1 1033 prepend(num & 0xFF) 1034 num >>= 8 1035 end 1037 Figure 5: o256 encoder (pseudocode) 1039 num = 0 1040 each_byte do |b| 1041 num <<= 8 1042 num += b + 1 1043 end 1045 Figure 6: o256 decoder (pseudocode) 1047 On a more philosophical note, it can be observed that o256 solves the 1048 inverse problem of Self-Delimiting Numeric Values (SDNV) [RFC6256]: 1049 SDNV encodes variable-length numbers together with their length 1050 (allowing decoding without knowing their length in advance, deriving 1051 delimiting information from the number encoding). o256 encodes 1052 variable-length numbers when there is a way to separately convey the 1053 length (as in CoAP options), encoding (and later deriving) a small 1054 part of the numeric value into/from that size information. 1056 A.5. SMS encoding 1058 For use in SMS applications, CoAP messages can be transferred using 1059 SMS binary mode. However, there is operational experience showing 1060 that some environments cannot successfully send a binary mode SMS. 1062 For transferring SMS in character mode (7-bit characters), base64- 1063 encoding [RFC4648] is an obvious choice. 3 bytes of message (24 bits) 1064 turn into 4 characters, which cosume 28 bits. The overall overhead 1065 is approximately 17 %; the maximum message size is 120 bytes (160 SMS 1066 characters). 1068 If a more compact encoding is desired, base85 encoding can be 1069 employed (however, probably not the version defined in [RFC1924] -- 1070 instead, the version used in tools such as btoa and PDF should be 1071 chosen). However, this requires division operations. Also, the 1072 base85 character set includes several characters that cannot be 1073 transferred in a single 7-bit unit in SMS and/or are known to cause 1074 operational problems. A modified base85 character set can be defined 1075 to solve the latter problem. 4 bytes of message (32 bits) turn into 5 1076 characters, which consume 35 bits. The overall overhead is 1077 approximately 9.3 %; the resulting maximum message size is 128 bytes 1078 (160 SMS characters). 1080 Base64 and base85 do not make use of the fact that much CoAP data 1081 will be ASCII-based. Therefore, we define the following experimental 1082 SMS encoding. 1084 A.5.1. ASCII-optimized SMS encoding 1086 Not all 128 theoretically possible SMS characters are operationally 1087 free of problems. We therefore define: 1089 Shunned code characters: @ sign, as it maps to 0x00 1091 LF and CR signs (0x0A, 0x0D) 1093 uppercase C cedilla (0x09), as it is often mistranslated in 1094 gateways 1096 ESC (0x1B), as it is used in certain character combinations only 1098 Some ASCII characters cannot be transferred in the base SMS character 1099 set, as their code positions are taken by non-ASCII characters. 1100 These are simply encoded with their ASCII code positions, e.g., an 1101 underscore becomes a section mark (even though underscore has a 1102 different code position in the SMS character set). 1104 Equivalently translated input bytes: $, @, [, \, ], ^, _, `, {, |, 1105 }, ~, DEL 1107 In other words, bytes 0x20 to 0x7F are encoded into the same code 1108 positions in the 7-bit character set. 1110 Out of the remaining code characters, the following SMS characters 1111 are available for encoding: 1113 Non-equivalently translated (NET) code characters: 0x01 to 0x08, (8 1114 characters) 1116 0x0B, 0x0C, (2 characters) 1118 0x0E to 0x1A, (13 characters) 1119 0x1C to 0x1F, (4 characters) 1121 Of the 27 NET code characters, 18 are taken as prefix characters (see 1122 below), and 8 are defined as directly translated characters: 1124 Directly translated bytes: Equivalently translated input bytes are 1125 represented as themselves 1127 0x00 to 0x07 are represented as 0x01 to 0x08 1129 This leaves 0x08 to 0x1F and 0x80 to 0xFF. Of these, the bytes 0x80 1130 to 0x87 and 0xA0 to 0xFF are represented as the bytes 0x00 to 0x07 1131 (represented by characters 0x01 to 0x08) and 0x20 to 0x7F, with a 1132 prefix of 1 (see below). The characters 0x08 to 0x1F are represented 1133 as the characters 0x28 to 0x3F with a prefix of 2 (see below). The 1134 characters 0x88 to 0x9F are represented as the characters 0x48 to 1135 0x5F with a prefix of 2 (see below). (Characters 0x01 to 0x08, 0x20 1136 to 0x27, 0x40 to 0x47, and 0x60 to 0x7f with a prefix of 2 are 1137 reserved for future extensions, which could be used for some 1138 backreferencing or run-length compression.) 1140 Bytes that do not need a prefix (directly translated bytes) are sent 1141 as is. Any byte that does need a prefix (i.e., 1 or 2) is preceded 1142 by a prefix character, which provides a prefix for this and the 1143 following two bytes as follows: 1145 +------+-----+---+------+-----+ 1146 | 0x0B | 100 | | 0x15 | 200 | 1147 +------+-----+---+------+-----+ 1148 | 0x0C | 101 | | 0x16 | 201 | 1149 | | | | | | 1150 | 0x0E | 102 | | 0x17 | 202 | 1151 | | | | | | 1152 | 0x0F | 110 | | 0x18 | 210 | 1153 | | | | | | 1154 | 0x10 | 111 | | 0x19 | 211 | 1155 | | | | | | 1156 | 0x11 | 112 | | 0x1A | 212 | 1157 | | | | | | 1158 | 0x12 | 120 | | 0x1C | 220 | 1159 | | | | | | 1160 | 0x13 | 121 | | 0x1D | 221 | 1161 | | | | | | 1162 | 0x14 | 122 | | 0x1E | 222 | 1163 +------+-----+---+------+-----+ 1165 (This leaves one non-shunned character, 0x1F, for future extension.) 1166 The coding overhead of this encoding for random bytes is similar to 1167 Base85, without the need for a division/multiplication. For bytes 1168 that are mostly ASCII characters, the overhead can easily become 1169 negative. (Conversely, for bytes that are more likely to be non- 1170 ASCII than in a random sequence of bytes, the overhead becomes 1171 greater.) 1173 So, for instance, for the CoAP message in Figure 7: 1175 ver tt code mid 1176 1 ack 2.05 17033 1177 content_type 40 1178 token sometok 1179 3c 2f 3e 3b 74 69 74 6c 65 3d 22 47 65 6e 65 72 |;title="Gener| 1180 61 6c 20 49 6e 66 6f 22 3b 63 74 3d 30 2c 3c 2f |al Info";ct=0,;if="clock"| 1182 3b 72 74 3d 22 54 69 63 6b 73 22 3b 74 69 74 6c |;rt="Ticks";titl| 1183 65 3d 22 49 6e 74 65 72 6e 61 6c 20 43 6c 6f 63 |e="Internal Cloc| 1184 6b 22 3b 63 74 3d 30 2c 3c 2f 61 73 79 6e 63 3e |k";ct=0,| 1185 3b 63 74 3d 30 |;ct=0 | 1187 Figure 7: CoAP response message as captured and decoded 1189 The 116 byte unencoded message is shown as ASCII characters in 1190 Figure 8 (\xDD stands for the byte with the hex digits DD): 1192 bEB\x89\x11(\xA7sometok;title="General Info";ct=0, 1193 ;if="clock";rt="Ticks";title="Internal Clock";ct=0,;ct=0 1195 Figure 8: CoAP response message shown as unencoded characters 1197 The equivalent SMS encoding is shown as equivalent-coded SMS 1198 characters in Figure 9 (7 bits per character, \x12 is a 220 prefix 1199 and \x0B is a 100 prefix, the rest is shown in equivalent encoding), 1200 adding two characters of prefix overhead, for a total length of 118 1201 7-bit characters or 104 (103.25 plus padding) bytes: 1203 bEB\x12I1(\x0B'sometok;title="General Info";ct=0, 1204 ;if="clock";rt="Ticks";title="Internal Clock";ct=0,;ct=0 1206 Figure 9: CoAP response message shown as SMS-encoded characters 1208 Appendix B. The Cemetery (Things we won't do) 1210 This annex documents roads that the WG decided not to take, in order 1211 to spare readers from reinventing them in vain. 1213 B.1. Example envelope option: solving #230 1215 Ticket #230 [CoRE230] points out a design flaw of 1216 [I-D.ietf-core-coap]: When we split the elective Location option of 1217 draft -01 into multiple elective options, we made it possible that an 1218 implementation might process some of these and ignore others, leading 1219 to an incorrect interpretation of the Location expressed by the 1220 server. 1222 There are several more or less savory solutions to #230. 1224 Each of the elective options that together make up the Location could 1225 be defined in such a way that it makes a requirement on the 1226 processing of the related option (essentially revoking their elective 1227 status once the option under consideration is actually processed). 1228 This falls flat as soon as another option is defined that would also 1229 become part of the Location: existing implementations would not know 1230 that the new option is also part of the cluster that is re- 1231 interpreted as critical. The potential future addition of Location- 1232 Host and Location-Port makes this a valid consideration. 1234 A better solution would be to define an elective Envelope Option 1235 called Location. Within a Location Option, the following top-level 1236 options might be allowed (now or in the future): 1238 o Uri-Host 1240 o Uri-Port 1242 o Uri-Path 1244 o Uri-Query 1246 This would unify the code for interpreting the top-level request 1247 options that indicate the request URI with the code that interprets 1248 the Location URI. 1250 The four options listed are all critical, while the envelope is 1251 elective. This gives exactly the desired semantics: If the envelope 1252 is processed at all (which is elective), the nested options are 1253 critical and all need to be processed. 1255 B.2. Example envelope option: proxy-elective options 1257 Another potential application of envelope options is motivated by the 1258 observation that new critical options might not be implemented by all 1259 proxies on the CoAP path to an origin server. So that this does not 1260 become an obstacle to introducing new critical options that are of 1261 interest only to client and origin server, the client might want to 1262 mark some critical options proxy-elective, i.e. elective for a proxy 1263 but still critical for the origin server. 1265 One way to do this would be an Envelope option, the Proxy-Elective 1266 Option. A client might bundle a number of critical options into a 1267 critical Proxy-Elective Option. A proxy that processes the message 1268 is obliged to process the envelope (or reject the message), where 1269 processing means passing on the nested options towards the origin 1270 server (preferably again within a Proxy-Elective option). It can 1271 pass on the nested options, even ones unknown to the proxy, knowing 1272 that the client is happy with proxies not processing all of them. 1274 (The assumption here is that the Proxy-Elective option becomes part 1275 of the base standard, so all but the most basic proxies would know 1276 how to handle it.) 1278 B.3. Stateful URI compression 1280 Is the approximately 25 % average saving achievable with Huffman- 1281 based URI compression schemes worth the complexity? Probably not, 1282 because much higher average savings can be achieved by introducing 1283 state. 1285 Henning Schulzrinne has proposed for a server to be able to supply a 1286 shortened URI once a resource has been requested using the full- 1287 length URI. Let's call such a shortened referent a _Temporary 1288 Resource Identifier_, _TeRI_ for short. This could be expressed by a 1289 response option as shown in Figure 10. 1291 0 1292 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 1293 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1294 | duration | TeRI... 1295 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1297 Figure 10: Option for offering a TeRI in a response 1299 The TeRI offer option indicates that the server promises to offer 1300 this resources under the TeRI given for at least the time given as 1301 the duration. Another TeRI offer can be made later to extend the 1302 duration. 1304 Once a TeRI for a URI is known (and still within its lifetime), the 1305 client can supply a TeRI instead of a URI in its requests. The same 1306 option format as an offer could be used to allow the client to 1307 indicate how long it believes the TeRI will still be valid (so that 1308 the server can decide when to update the lifetime duration). TeRIs 1309 in requests could be distinguished from URIs e.g. by using a 1310 different option number. 1312 Proposal: Add a TeRI option that can be used in CoAP requests and 1313 responses. 1315 Add a way to indicate a TeRI and its duration in a link-value. 1317 Do not add any form of stateless URI encoding. 1319 Benefits: Much higher reduction of message size than any stateless 1320 URI encoding could achieve. 1322 As the use of TeRIs is entirely optional, minimal complexity nodes 1323 can get by without implementing them. 1325 Drawbacks: Adds considerable state and complexity to the protocol. 1327 It turns out that real CoAP URIs are short enough that TeRIs are 1328 not needed. 1330 (Discuss the security implications of TeRIs.) 1332 B.4. Beyond 270 bytes in a single option 1334 The authors would argue that 270 as the maximum length of an option 1335 is already beyond the "painless" threshold. 1337 If that is not the consensus of the WG, the scheme can easily be 1338 extended as in Figure 11: 1340 for 15..269: 1341 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1342 | Option Delta | 1 1 1 1 | Length - 15 | 1343 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1344 | Option Value ... 1345 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1347 for 270..65805: 1348 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1349 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 1350 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1351 | Length - 270 (in network byte order) | 1352 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1353 | Option Value ... 1354 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1356 Figure 11: Ridiculously Long Option Header 1358 The infinite number of obvious variations on this scheme are left as 1359 an exercise to the reader. 1361 Again, as a precaution to future extensions, the current encoding for 1362 length 270 (eight ones in the extension byte) could be marked as 1363 reserved today. 1365 B.5. Beyond 15 options 1367 (This section keeps discussion that is no longer needed as we have 1368 agreed to do what is documented in Appendix B.6). 1370 The limit of 15 options is motivated by the fixed four-bit field "OC" 1371 that is used for indicating the number of options in the fixed-length 1372 CoAP header (Figure 12). 1374 0 1 2 3 1375 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 1376 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1377 |Ver| T | OC | Code | Message ID | 1378 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1379 | Options (if any) ... 1380 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1381 | Payload (if any) ... 1382 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1384 Figure 12: Four-byte fixed header in a CoAP Message 1386 Note that there is another fixed four-bit field in CoAP: the option 1387 length (Figure 13 - note that this figure is not to the same scale as 1388 the previous figure): 1390 0 1 2 3 4 5 6 7 1391 +---+---+---+---+---+---+---+---+ 1392 | Option Delta | Length | for 0..14 1393 +---+---+---+---+---+---+---+---+ 1394 | Option Value ... 1395 +---+---+---+---+---+---+---+---+ 1397 Figure 13: Short Option Header 1399 Since 15 is inacceptable for a maximum option length, the all-ones 1400 value (15) was taken out of the set of allowable values for the short 1401 header, and a long header was introduced that allows the insertion of 1402 an extension byte (Figure 14): 1404 for 15..270: 1405 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1406 | Option Delta | 1 1 1 1 | Length - 15 | 1407 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1408 | Option Value ... 1409 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1411 Figure 14: Long Option Header 1413 We might want to use the same technique for the CoAP header as well. 1414 There are two obvious places where the extension byte could be 1415 placed: 1417 1. right after the byte carrying the OC field, so the structure is 1418 the same as for the option header; 1420 2. right after the fixed-size CoAP header. 1422 Both solutions lose the fixed-size-ness of the CoAP header. 1424 Solution 1 has the disadvantage that the CoAP header is also changing 1425 in structure: The extension byte is wedged between the first and the 1426 second byte of the CoAP header. This is unfortunate, as the number 1427 of options only comes into play when the option processing begins, so 1428 it is more natural to use solution 2 (Figure 15): 1430 0 1 2 3 1431 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 1432 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1433 |Ver| T | 15 | Code | Message ID | 1434 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1435 | OC - 15 | Options ... 1436 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1437 | Payload (if any) ... 1438 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1440 Figure 15: Extended header for CoAP Messages with 15+ options 1442 This would allow for up to 270 options in a CoAP message, which is 1443 very likely way beyond the "painless" threshold. 1445 B.5.1. Implementation considerations 1447 For a message decoder, this extension creates relatively little pain, 1448 as the number of options only becomes interesting when the encoding 1449 turns to the options part of the message, which is then simply lead 1450 in by the extension byte if the four-bit field is 15. 1452 For a message encoder, this extension is not so rosy. If the encoder 1453 is constructing the message serially, it may not know in advance 1454 whether the number of options will exceed 14. None of the following 1455 implementation strategies is particularly savory, but all of them do 1456 work: 1458 1. Encode the options serially under the assumption that the number 1459 of options will be 14 or less. When the 15th option needs to be 1460 encoded, abort the option encoding, and restart it from scratch 1461 one byte further to the left. 1463 2. Similar to 1, except that the bytes already encoded are all moved 1464 one byte to right, the extension byte is inserted, and the option 1465 encoding process is continued. 1467 3. The encoder always leaves space for the extension byte (at least 1468 if it can't prove the number will be less thatn 14). If the 1469 extension byte is not needed, an Option 0 with length 0 is 1470 encoded instead (i.e., one byte is wasted - this option is 1471 elective and will be ignored by the receiver). 1473 As a minimum, to enable strategy 3, the option 0 should be reserved 1474 at least for the case of length=0. 1476 B.5.2. What should we do now? 1478 As a minimum proposal for the next version of CoAP, the value 15 for 1479 OC should be marked as reserved today. 1481 B.5.3. Alternatives 1483 One alternative that has been discussed previously is to have an 1484 "Options" Option, which allows the carriage of multiple options in 1485 the belly of a single one. This could also be used to carry more 1486 than 15 options. However: 1488 o The conditional introduction of an Options option has 1489 implementation considerations that are likely to be more severe 1490 than the ones listed above; 1492 o since 270 bytes may not be enough for the encoding of _all_ 1493 options, the "Options" option would need to be repeatable. This 1494 creates many different ways to encode the same message, leading to 1495 combinatorial explosion in test cases for ensuring 1496 interoperability. 1498 B.5.4. Alternative: Going to a delimiter model 1500 Another alternative is to spend the additional byte not as an 1501 extended count, but as an option terminator. 1503 B.6. Implementing the option delimiter for 15 or more options 1505 Implementation note: As can be seen from the proof of concept code 1506 in Figure 16, the actual implementation cost for a decoder is 1507 around 4 lines of code (or about 8-10 machine code instructions). 1509 while numopt > 0 1510 nextbyte = ... get next byte 1512 if numopt == 15 # new 1513 break if nextbyte == 0xF0 # new 1514 else # new 1515 numopt -= 1 1516 end # new 1518 ... decode the delta and length from nextbyte and handle them 1519 end 1521 Figure 16: Implementing the Option Terminator 1523 Similarly, creating the option terminator needs about four more lines 1524 (not marked "old" in the C code in Figure 17). 1526 b0 = 0x40 + (tt << 4); /* old */ 1527 buffer[0] = b0 + 15; /* guess first byte */ 1529 .... encode options .... /* old */ 1531 if (option_count >= 15 || first_fragment_already_shipped) 1532 buffer[pos++] = 0xF0; /* use delimiter */ 1533 else /* save a byte: */ 1534 buffer[0] = b0 + option_count; /* old: backpatch */ 1536 Figure 17: Creating the Option Terminator 1538 Appendix C. Experimental Options 1540 This annex documents proposals that need significant additional 1541 discussion before they can become part of (or go back to) the main 1542 CoAP specification. They are not dead, but might die if there turns 1543 out to be no good way to solve the problem. 1545 C.1. Options indicating absolute time 1547 HTTP has a number of headers that may indicate absolute time: 1549 o "Date", defined in Section 14.18 in [RFC2616] (Section 9.3 in 1550 [I-D.ietf-httpbis-p1-messaging]), giving the absolute time a 1551 response was generated; 1553 o "Last-Modified", defined in Section 14.29 in [RFC2616], (Section 1554 6.6 in [I-D.ietf-httpbis-p4-conditional], giving the absolute time 1555 of when the origin server believes the resource representation was 1556 last modified; 1558 o "If-Modified-Since", defined in Section 14.25 in [RFC2616], 1559 "If-Unmodified-Since", defined in Section 14.28 in [RFC2616], and 1560 "If-Range", defined in Section 14.27 in [RFC2616] can be used to 1561 supply absolute time to gate a conditional request; 1563 o "Expires", defined in Section 14.21 in [RFC2616] (Section 3.3 in 1564 [I-D.ietf-httpbis-p6-cache]), giving the absolute time after which 1565 a response is considered stale. 1567 o The more obscure headers "Retry-After", defined in Section 14.37 1568 in [RFC2616], and "Warning", defined in section 14.46 in 1569 [RFC2616], also may employ absolute time. 1571 [I-D.ietf-core-coap] defines a single "Date" option, which however 1572 "indicates the creation time and date of a given resource 1573 representation", i.e., is closer to a "Last-Modified" HTTP header. 1574 HTTP's caching rules [I-D.ietf-httpbis-p6-cache] make use of both 1575 "Date" and "Last-Modified", combined with "Expires". The specific 1576 semantics required for CoAP needs further consideration. 1578 In addition to the definition of the semantics, an encoding for 1579 absolute times needs to be specified. 1581 In UNIX-related systems, it is customary to indicate absolute time as 1582 an integer number of seconds, after midnight UTC, January 1, 1970. 1583 Unless negative numbers are employed, this time format cannot 1584 represent time values prior to January 1, 1970, which probably is not 1585 required for the uses ob absolute time in CoAP. 1587 If a 32-bit integer is used and allowance is made for a sign-bit in a 1588 local implementation, the latest UTC time value that can be 1589 represented by the resulting 31 bit integer value is 03:14:07 on 1590 January 19, 2038. If the 32-bit integer is used as an unsigned 1591 value, the last date is 2106-02-07, 06:28:15. 1593 The reach can be extended by: - moving the epoch forward, e.g. by 40 1594 years (= 1262304000 seconds) to 2010-01-01. This makes it impossible 1595 to represent Last-Modified times in that past (such as could be 1596 gatewayed in from HTTP). - extending the number of bits, e.g. by one 1597 more byte, either always or as one of two formats, keeping the 32-bit 1598 variant as well. 1600 Also, the resolution can be extended by expressing time in 1601 milliseconds etc., requiring even more bits (e.g., a 48-bit unsigned 1602 integer of milliseconds would last well after year 9999.) 1604 For experiments, an experimental "Date" option is defined with the 1605 semantics of HTTP's "Last-Modified". It can carry an unsigned 1606 integer of 32, 40, or 48 bits; 32- and 40-bit integers indicate the 1607 absolute time in seconds since 1970-01-01 00:00 UTC, while 48-bit 1608 integers indicate the absolute time in milliseconds since 1970-01-01 1609 00:00 UTC. 1611 However, that option is not really that useful until there is a 1612 "If-Modified-Since" option as well. 1614 (Also: Discuss nodes without clocks.) 1616 C.2. Representing Durations 1618 Various message types used in CoAP need the representation of 1619 *durations*, i.e. of the length of a timespan. In SI units, these 1620 are measured in seconds. CoAP durations represent integer numbers of 1621 seconds, but instead of representing these numbers as integers, a 1622 more compact single-byte pseudo-floating-point (pseudo-FP) 1623 representation is used (Figure 18). 1625 0 1 2 3 4 5 6 7 1626 +---+---+---+---+---+---+---+---+ 1627 | 0... value | 1628 +---+---+---+---+---+---+---+---+ 1630 +---+---+---+---+---+---+---+---+ 1631 | 1... mantissa | exponent | 1632 +---+---+---+---+---+---+---+---+ 1633 Figure 18: Duration in (8,4) pseudo-FP representation 1635 If the high bit is clear, the entire n-bit value (including the high 1636 bit) is the decoded value. If the high bit is set, the mantissa 1637 (including the high bit, with the exponent field cleared out but 1638 still present) is shifted left by the exponent to yield the decoded 1639 value. 1641 The (n,e)-pseudo-FP format can be decoded with a single line of code 1642 (plus a couple of constant definitions), as demonstrated in 1643 Figure 19. 1645 #define N 8 1646 #define E 4 1647 #define HIBIT (1 << (N - 1)) 1648 #define EMASK ((1 << E) - 1) 1649 #define MMASK ((1 << N) - 1 - EMASK) 1651 #define DECODE_8_4(r) (r < HIBIT ? r : (r & MMASK) << (r & EMASK)) 1653 Figure 19: Decoding an (8,4) pseudo-FP value 1655 Note that a pseudo-FP encoder needs to consider rounding; different 1656 applications of durations may favor rounding up or rounding down the 1657 value encoded in the message. 1659 The highest pseudo-FP value, represented by an all-ones byte (0xFF), 1660 is reserved to indicate an indefinite duration. The next lower value 1661 (0xEF) is thus the highest representable value and is decoded as 1662 7340032 seconds, a little more than 12 weeks. 1664 C.3. Rationale 1666 Where CPU power and memory is abundant, a duration can almost always 1667 be adequately represented by a non-negative floating-point number 1668 representing that number of seconds. Historically, many APIs have 1669 also used an integer representation, which limits both the resolution 1670 (e.g., if the integer represents the duration in seconds) and often 1671 the range (integer machine types have range limits that may become 1672 relevant). UNIX's "time_t" (which is used for both absolute time and 1673 durations) originally was a signed 32-bit value of seconds, but was 1674 later complemented by an additional integer to add microsecond 1675 ("struct timeval") and then later nanosecond ("struct timespec") 1676 resolution. 1678 Three decisions need to be made for each application of the concept 1679 of duration: 1681 o the *resolution*. What rounding error is acceptable? 1683 o the *range*. What is the maximum duration that needs to be 1684 represented? 1686 o the *number of bits* that can be expended. 1688 Obviously, these decisions are interrelated. Typically, a large 1689 range needs a large number of bits, unless resolution is traded. For 1690 most applications, the actual requirement for resolution are limited 1691 for longer durations, but can be more acute for shorter durations. 1693 C.4. Pseudo-Floating Point 1695 Constrained systems typically avoid the use of floating-point (FP) 1696 values, as 1698 o simple CPUs often don't have support for floating-point datatypes 1700 o software floating-point libraries are expensive in code size and 1701 slow. 1703 In addition, floating-point datatypes used to be a significant 1704 element of market differentiation in CPU design; it has taken the 1705 industry a long time to agree on a standard floating point 1706 representation. 1708 These issues have led to protocols that try to constrain themselves 1709 to integer representation even where the ability of a floating point 1710 representation to trade range for resolution would be beneficial. 1712 The idea of introducing _pseudo-FP_ is to obtain the increased range 1713 provided by embedding an exponent, without necessarily getting stuck 1714 with hardware datatypes or inefficient software floating-point 1715 libraries. 1717 For the purposes of this draft, we define an (n,e)-pseudo-FP as a 1718 fixed-length value of n bits, e of which may be used for an exponent. 1719 Figure 18 illustrates an (8,4)-pseudo-FP value. 1721 If the high bit is clear, the entire n-bit value (including the high 1722 bit) is the decoded value. If the high bit is set, the mantissa 1723 (including the high bit, but with the exponent field cleared out) is 1724 shifted left by the exponent to yield the decoded value. 1726 The (n,e)-pseudo-FP format can be decoded with a single line of code 1727 (plus a couple of constant definition), as demonstrated in Figure 19. 1729 Only non-negative numbers can be represented by this format. It is 1730 designed to provide full integer resolution for values from 0 to 1731 2^(n-1)-1, i.e., 0 to 127 in the (8,4) case, and a mantissa of n-e 1732 bits from 2^(n-1) to (2^n-2^e)*2^(2^e-1), i.e., 128 to 7864320 in the 1733 (8,4) case. By choosing e carefully, resolution can be traded 1734 against range. 1736 Note that a pseudo-FP encoder needs to consider rounding; different 1737 applications of durations may favor rounding up or rounding down the 1738 value encoded in the message. This requires a little more than a 1739 single line of code (which is left as an exercise to the reader, as 1740 the most efficient expression depends on hardware details). 1742 C.5. A Duration Type for CoAP 1744 CoAP needs durations in a number of places. In [I-D.ietf-core-coap], 1745 durations occur in the option "Subscription-lifetime" as well as in 1746 the option "Max-age". (Note that the option "Date" is not a 1747 duration, but a point in time.) Other durations of this kind may be 1748 added later. 1750 Most durations relevant to CoAP are best expressed with a minimum 1751 resolution of one second. More detailed resolutions are unlikely to 1752 provide much benefit. 1754 The range of lifetimes and caching ages are probably best kept below 1755 the order of magnitude of months. An (8,4)-pseudo-FP has the maximum 1756 value of 7864320, which is about 91 days; this appears to be adequate 1757 for a subscription lifetime and probably even for a maximum cache 1758 age. Figure 20 shows the values that can be expressed. (If a larger 1759 range for the latter is indeed desired, an (8,5)-pseudo-FP could be 1760 used; this would last 15 milleniums, at the cost of having only 3 1761 bits of accuracy for values larger than 127 seconds.) 1763 Proposal: A single duration type is used throughout CoAP, based on 1764 an (8,4)-pseudo-FP giving a duration in seconds. 1766 Benefits: Implementations can use a single piece of code for 1767 managing all CoAP-related durations. 1769 In addition, length information never needs to be managed for 1770 durations that are embedded in other data structures: All 1771 durations are expressed by a single byte. 1773 It might be worthwhile to reserve one duration value, e.g. 0xFF, for 1774 an indefinite duration. 1776 Duration Seconds Encoded 1777 ----------- ---------- ------- 1778 00:00:00 0x00000000 0x00 1779 00:00:01 0x00000001 0x01 1780 00:00:02 0x00000002 0x02 1781 00:00:03 0x00000003 0x03 1782 00:00:04 0x00000004 0x04 1783 00:00:05 0x00000005 0x05 1784 00:00:06 0x00000006 0x06 1785 00:00:07 0x00000007 0x07 1786 00:00:08 0x00000008 0x08 1787 00:00:09 0x00000009 0x09 1788 00:00:10 0x0000000a 0x0a 1789 00:00:11 0x0000000b 0x0b 1790 00:00:12 0x0000000c 0x0c 1791 00:00:13 0x0000000d 0x0d 1792 00:00:14 0x0000000e 0x0e 1793 00:00:15 0x0000000f 0x0f 1794 00:00:16 0x00000010 0x10 1795 00:00:17 0x00000011 0x11 1796 00:00:18 0x00000012 0x12 1797 00:00:19 0x00000013 0x13 1798 00:00:20 0x00000014 0x14 1799 00:00:21 0x00000015 0x15 1800 00:00:22 0x00000016 0x16 1801 00:00:23 0x00000017 0x17 1802 00:00:24 0x00000018 0x18 1803 00:00:25 0x00000019 0x19 1804 00:00:26 0x0000001a 0x1a 1805 00:00:27 0x0000001b 0x1b 1806 00:00:28 0x0000001c 0x1c 1807 00:00:29 0x0000001d 0x1d 1808 00:00:30 0x0000001e 0x1e 1809 00:00:31 0x0000001f 0x1f 1810 00:00:32 0x00000020 0x20 1811 00:00:33 0x00000021 0x21 1812 00:00:34 0x00000022 0x22 1813 00:00:35 0x00000023 0x23 1814 00:00:36 0x00000024 0x24 1815 00:00:37 0x00000025 0x25 1816 00:00:38 0x00000026 0x26 1817 00:00:39 0x00000027 0x27 1818 00:00:40 0x00000028 0x28 1819 00:00:41 0x00000029 0x29 1820 00:00:42 0x0000002a 0x2a 1821 00:00:43 0x0000002b 0x2b 1822 00:00:44 0x0000002c 0x2c 1823 00:00:45 0x0000002d 0x2d 1824 00:00:46 0x0000002e 0x2e 1825 00:00:47 0x0000002f 0x2f 1826 00:00:48 0x00000030 0x30 1827 00:00:49 0x00000031 0x31 1828 00:00:50 0x00000032 0x32 1829 00:00:51 0x00000033 0x33 1830 00:00:52 0x00000034 0x34 1831 00:00:53 0x00000035 0x35 1832 00:00:54 0x00000036 0x36 1833 00:00:55 0x00000037 0x37 1834 00:00:56 0x00000038 0x38 1835 00:00:57 0x00000039 0x39 1836 00:00:58 0x0000003a 0x3a 1837 00:00:59 0x0000003b 0x3b 1838 00:01:00 0x0000003c 0x3c 1839 00:01:01 0x0000003d 0x3d 1840 00:01:02 0x0000003e 0x3e 1841 00:01:03 0x0000003f 0x3f 1842 00:01:04 0x00000040 0x40 1843 00:01:05 0x00000041 0x41 1844 00:01:06 0x00000042 0x42 1845 00:01:07 0x00000043 0x43 1846 00:01:08 0x00000044 0x44 1847 00:01:09 0x00000045 0x45 1848 00:01:10 0x00000046 0x46 1849 00:01:11 0x00000047 0x47 1850 00:01:12 0x00000048 0x48 1851 00:01:13 0x00000049 0x49 1852 00:01:14 0x0000004a 0x4a 1853 00:01:15 0x0000004b 0x4b 1854 00:01:16 0x0000004c 0x4c 1855 00:01:17 0x0000004d 0x4d 1856 00:01:18 0x0000004e 0x4e 1857 00:01:19 0x0000004f 0x4f 1858 00:01:20 0x00000050 0x50 1859 00:01:21 0x00000051 0x51 1860 00:01:22 0x00000052 0x52 1861 00:01:23 0x00000053 0x53 1862 00:01:24 0x00000054 0x54 1863 00:01:25 0x00000055 0x55 1864 00:01:26 0x00000056 0x56 1865 00:01:27 0x00000057 0x57 1866 00:01:28 0x00000058 0x58 1867 00:01:29 0x00000059 0x59 1868 00:01:30 0x0000005a 0x5a 1869 00:01:31 0x0000005b 0x5b 1870 00:01:32 0x0000005c 0x5c 1871 00:01:33 0x0000005d 0x5d 1872 00:01:34 0x0000005e 0x5e 1873 00:01:35 0x0000005f 0x5f 1874 00:01:36 0x00000060 0x60 1875 00:01:37 0x00000061 0x61 1876 00:01:38 0x00000062 0x62 1877 00:01:39 0x00000063 0x63 1878 00:01:40 0x00000064 0x64 1879 00:01:41 0x00000065 0x65 1880 00:01:42 0x00000066 0x66 1881 00:01:43 0x00000067 0x67 1882 00:01:44 0x00000068 0x68 1883 00:01:45 0x00000069 0x69 1884 00:01:46 0x0000006a 0x6a 1885 00:01:47 0x0000006b 0x6b 1886 00:01:48 0x0000006c 0x6c 1887 00:01:49 0x0000006d 0x6d 1888 00:01:50 0x0000006e 0x6e 1889 00:01:51 0x0000006f 0x6f 1890 00:01:52 0x00000070 0x70 1891 00:01:53 0x00000071 0x71 1892 00:01:54 0x00000072 0x72 1893 00:01:55 0x00000073 0x73 1894 00:01:56 0x00000074 0x74 1895 00:01:57 0x00000075 0x75 1896 00:01:58 0x00000076 0x76 1897 00:01:59 0x00000077 0x77 1898 00:02:00 0x00000078 0x78 1899 00:02:01 0x00000079 0x79 1900 00:02:02 0x0000007a 0x7a 1901 00:02:03 0x0000007b 0x7b 1902 00:02:04 0x0000007c 0x7c 1903 00:02:05 0x0000007d 0x7d 1904 00:02:06 0x0000007e 0x7e 1905 00:02:07 0x0000007f 0x7f 1906 00:02:08 0x00000080 0x80 1907 00:02:24 0x00000090 0x90 1908 00:02:40 0x000000a0 0xa0 1909 00:02:56 0x000000b0 0xb0 1910 00:03:12 0x000000c0 0xc0 1911 00:03:28 0x000000d0 0xd0 1912 00:03:44 0x000000e0 0xe0 1913 00:04:00 0x000000f0 0xf0 1914 00:04:16 0x00000100 0x81 1915 00:04:48 0x00000120 0x91 1916 00:05:20 0x00000140 0xa1 1917 00:05:52 0x00000160 0xb1 1918 00:06:24 0x00000180 0xc1 1919 00:06:56 0x000001a0 0xd1 1920 00:07:28 0x000001c0 0xe1 1921 00:08:00 0x000001e0 0xf1 1922 00:08:32 0x00000200 0x82 1923 00:09:36 0x00000240 0x92 1924 00:10:40 0x00000280 0xa2 1925 00:11:44 0x000002c0 0xb2 1926 00:12:48 0x00000300 0xc2 1927 00:13:52 0x00000340 0xd2 1928 00:14:56 0x00000380 0xe2 1929 00:16:00 0x000003c0 0xf2 1930 00:17:04 0x00000400 0x83 1931 00:19:12 0x00000480 0x93 1932 00:21:20 0x00000500 0xa3 1933 00:23:28 0x00000580 0xb3 1934 00:25:36 0x00000600 0xc3 1935 00:27:44 0x00000680 0xd3 1936 00:29:52 0x00000700 0xe3 1937 00:32:00 0x00000780 0xf3 1938 00:34:08 0x00000800 0x84 1939 00:38:24 0x00000900 0x94 1940 00:42:40 0x00000a00 0xa4 1941 00:46:56 0x00000b00 0xb4 1942 00:51:12 0x00000c00 0xc4 1943 00:55:28 0x00000d00 0xd4 1944 00:59:44 0x00000e00 0xe4 1945 01:04:00 0x00000f00 0xf4 1946 01:08:16 0x00001000 0x85 1947 01:16:48 0x00001200 0x95 1948 01:25:20 0x00001400 0xa5 1949 01:33:52 0x00001600 0xb5 1950 01:42:24 0x00001800 0xc5 1951 01:50:56 0x00001a00 0xd5 1952 01:59:28 0x00001c00 0xe5 1953 02:08:00 0x00001e00 0xf5 1954 02:16:32 0x00002000 0x86 1955 02:33:36 0x00002400 0x96 1956 02:50:40 0x00002800 0xa6 1957 03:07:44 0x00002c00 0xb6 1958 03:24:48 0x00003000 0xc6 1959 03:41:52 0x00003400 0xd6 1960 03:58:56 0x00003800 0xe6 1961 04:16:00 0x00003c00 0xf6 1962 04:33:04 0x00004000 0x87 1963 05:07:12 0x00004800 0x97 1964 05:41:20 0x00005000 0xa7 1965 06:15:28 0x00005800 0xb7 1966 06:49:36 0x00006000 0xc7 1967 07:23:44 0x00006800 0xd7 1968 07:57:52 0x00007000 0xe7 1969 08:32:00 0x00007800 0xf7 1970 09:06:08 0x00008000 0x88 1971 10:14:24 0x00009000 0x98 1972 11:22:40 0x0000a000 0xa8 1973 12:30:56 0x0000b000 0xb8 1974 13:39:12 0x0000c000 0xc8 1975 14:47:28 0x0000d000 0xd8 1976 15:55:44 0x0000e000 0xe8 1977 17:04:00 0x0000f000 0xf8 1978 18:12:16 0x00010000 0x89 1979 20:28:48 0x00012000 0x99 1980 22:45:20 0x00014000 0xa9 1981 1d 01:01:52 0x00016000 0xb9 1982 1d 03:18:24 0x00018000 0xc9 1983 1d 05:34:56 0x0001a000 0xd9 1984 1d 07:51:28 0x0001c000 0xe9 1985 1d 10:08:00 0x0001e000 0xf9 1986 1d 12:24:32 0x00020000 0x8a 1987 1d 16:57:36 0x00024000 0x9a 1988 1d 21:30:40 0x00028000 0xaa 1989 2d 02:03:44 0x0002c000 0xba 1990 2d 06:36:48 0x00030000 0xca 1991 2d 11:09:52 0x00034000 0xda 1992 2d 15:42:56 0x00038000 0xea 1993 2d 20:16:00 0x0003c000 0xfa 1994 3d 00:49:04 0x00040000 0x8b 1995 3d 09:55:12 0x00048000 0x9b 1996 3d 19:01:20 0x00050000 0xab 1997 4d 04:07:28 0x00058000 0xbb 1998 4d 13:13:36 0x00060000 0xcb 1999 4d 22:19:44 0x00068000 0xdb 2000 5d 07:25:52 0x00070000 0xeb 2001 5d 16:32:00 0x00078000 0xfb 2002 6d 01:38:08 0x00080000 0x8c 2003 6d 19:50:24 0x00090000 0x9c 2004 7d 14:02:40 0x000a0000 0xac 2005 8d 08:14:56 0x000b0000 0xbc 2006 9d 02:27:12 0x000c0000 0xcc 2007 9d 20:39:28 0x000d0000 0xdc 2008 10d 14:51:44 0x000e0000 0xec 2009 11d 09:04:00 0x000f0000 0xfc 2010 12d 03:16:16 0x00100000 0x8d 2011 13d 15:40:48 0x00120000 0x9d 2012 15d 04:05:20 0x00140000 0xad 2013 16d 16:29:52 0x00160000 0xbd 2014 18d 04:54:24 0x00180000 0xcd 2015 19d 17:18:56 0x001a0000 0xdd 2016 21d 05:43:28 0x001c0000 0xed 2017 22d 18:08:00 0x001e0000 0xfd 2018 24d 06:32:32 0x00200000 0x8e 2019 27d 07:21:36 0x00240000 0x9e 2020 30d 08:10:40 0x00280000 0xae 2021 33d 08:59:44 0x002c0000 0xbe 2022 36d 09:48:48 0x00300000 0xce 2023 39d 10:37:52 0x00340000 0xde 2024 42d 11:26:56 0x00380000 0xee 2025 45d 12:16:00 0x003c0000 0xfe 2026 48d 13:05:04 0x00400000 0x8f 2027 54d 14:43:12 0x00480000 0x9f 2028 60d 16:21:20 0x00500000 0xaf 2029 66d 17:59:28 0x00580000 0xbf 2030 72d 19:37:36 0x00600000 0xcf 2031 78d 21:15:44 0x00680000 0xdf 2032 84d 22:53:52 0x00700000 0xef 2033 91d 00:32:00 0x00780000 0xff (reserved) 2035 Figure 20 2037 Authors' Addresses 2039 Carsten Bormann 2040 Universitaet Bremen TZI 2041 Postfach 330440 2042 Bremen D-28359 2043 Germany 2045 Phone: +49-421-218-63921 2046 Email: cabo@tzi.org 2048 Klaus Hartke 2049 Universitaet Bremen TZI 2050 Postfach 330440 2051 Bremen D-28359 2052 Germany 2054 Phone: +49-421-218-63905 2055 Email: hartke@tzi.org