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