idnits 2.17.1 draft-bormann-coap-misc-24.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 751 has weird spacing: '... code mid...' -- The document date (March 31, 2013) is 4038 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 1467, but not defined -- Looks like a reference, but probably isn't: '0' on line 1107 -- Looks like a reference, but probably isn't: '1' on line 3039 -- Looks like a reference, but probably isn't: '2' on line 3039 -- Looks like a reference, but probably isn't: '3' on line 3039 == Unused Reference: 'CoRE201' is defined on line 378, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-14 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-22 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-22 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) == Outdated reference: A later version (-07) exists of draft-ietf-lwig-terminology-02 Summary: 3 errors (**), 0 flaws (~~), 10 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: October 02, 2013 March 31, 2013 7 Miscellaneous additions to CoAP 8 draft-bormann-coap-misc-24 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 02, 2013. 35 Copyright Notice 37 Copyright (c) 2013 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. Observing Resources in CoAP . . . . . . . . . . . . . . . . . 4 54 3. The Base-Uri Option . . . . . . . . . . . . . . . . . . . . . 6 55 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 56 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 57 5.1. Normative References . . . . . . . . . . . . . . . . . . 7 58 5.2. Informative References . . . . . . . . . . . . . . . . . 8 59 Appendix A. The Nursery (Things that still need to ripen a bit) 9 60 A.1. Envelope Options . . . . . . . . . . . . . . . . . . . . 9 61 A.2. Payload-Length Option . . . . . . . . . . . . . . . . . . 10 62 A.3. URI Authorities with Binary Adresses . . . . . . . . . . 11 63 A.4. Length-aware number encoding (o256) . . . . . . . . . . . 12 64 A.5. SMS encoding . . . . . . . . . . . . . . . . . . . . . . 14 65 A.5.1. ASCII-optimized SMS encoding . . . . . . . . . . . . 14 66 A.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . 17 67 A.6.1. Requesting a Tunnel with CONNECT . . . . . . . . . . 17 68 A.6.2. Using a CONNECT Tunnel . . . . . . . . . . . . . . . 18 69 A.6.3. Closing down a CONNECT Tunnel . . . . . . . . . . . . 18 70 Appendix B. The Museum (Things we did, but maybe not exactly 71 this way) . . . . . . . . . . . . . . . . . . . . . 19 72 B.1. Getting rid of artificial limitations . . . . . . . . . . 19 73 B.1.1. Beyond 270 bytes in a single option . . . . . . . . . 20 74 B.1.2. Beyond 15 options . . . . . . . . . . . . . . . . . . 20 75 B.1.3. Implementing the option delimiter for 15 or more 76 options . . . . . . . . . . . . . . . . . . . . . . . 23 77 B.1.4. Option Length encoding beyond 270 bytes . . . . . . . 24 78 B.2. Registered Option . . . . . . . . . . . . . . . . . . . . 26 79 B.2.1. A Separate Suboption Number Space . . . . . . . . . . 27 80 B.2.2. Opening Up the Option Number Space . . . . . . . . . 28 81 B.3. Enabling Protocol Evolution . . . . . . . . . . . . . . . 32 82 B.3.1. Potential new option number allocation . . . . . . . 33 83 B.4. Patience, Leisure, and Pledge . . . . . . . . . . . . . . 35 84 B.4.1. Patience . . . . . . . . . . . . . . . . . . . . . . 35 85 B.4.2. Leisure . . . . . . . . . . . . . . . . . . . . . . . 36 86 B.4.3. Pledge . . . . . . . . . . . . . . . . . . . . . . . 36 87 B.4.4. Option Formats . . . . . . . . . . . . . . . . . . . 37 88 Appendix C. The Cemetery (Things we won't do) . . . . . . . . . 37 89 C.1. Example envelope option: solving #230 . . . . . . . . . . 37 90 C.2. Example envelope option: proxy-elective options . . . . . 38 91 C.3. Stateful URI compression . . . . . . . . . . . . . . . . 39 92 Appendix D. Experimental Options . . . . . . . . . . . . . . . . 40 93 D.1. Options indicating absolute time . . . . . . . . . . . . 40 94 D.2. Representing Durations . . . . . . . . . . . . . . . . . 41 95 D.3. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 43 96 D.4. Pseudo-Floating Point . . . . . . . . . . . . . . . . . . 43 97 D.5. A Duration Type for CoAP . . . . . . . . . . . . . . . . 44 98 D.6. CONTOUR (CoAP Non-trivial Option Useful Representation) . 50 99 D.6.1. Objectives . . . . . . . . . . . . . . . . . . . . . 51 100 D.6.2. Specification of the CBOR Encoding . . . . . . . . . 52 101 D.6.3. Optional Features . . . . . . . . . . . . . . . . . . 59 102 D.6.4. Discussion . . . . . . . . . . . . . . . . . . . . . 62 103 D.6.5. Diagnostic Notation . . . . . . . . . . . . . . . . . 62 104 D.6.6. Examples . . . . . . . . . . . . . . . . . . . . . . 63 105 D.6.7. Acknowledgements . . . . . . . . . . . . . . . . . . 65 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 108 1. Introduction 110 The CoRE WG is tasked with standardizing an Application Protocol for 111 Constrained Networks/Nodes, CoAP [I-D.ietf-core-coap]. This protocol 112 is intended to provide RESTful [REST] services not unlike HTTP 113 [RFC2616], while reducing the complexity of implementation as well as 114 the size of packets exchanged in order to make these services useful 115 in a highly constrained network of themselves highly constrained 116 nodes. 118 This objective requires restraint in a number of sometimes 119 conflicting ways: 121 o reducing implementation complexity in order to minimize code size, 123 o reducing message sizes in order to minimize the number of 124 fragments needed for each message (in turn to maximize the 125 probability of delivery of the message), the amount of 126 transmission power needed and the loading of the limited-bandwidth 127 channel, 129 o reducing requirements on the environment such as stable storage, 130 good sources of randomness or user interaction capabilities. 132 This draft attempts to address a number of problems not yet 133 adequately solved in [I-D.ietf-core-coap]. The solutions proposed to 134 these problems are somewhat interrelated and are therefore presented 135 in one draft. As of the current version of the draft, the main body 136 is almost empty, since few significant problems remain with CoAP or 137 its satellite specifications. 139 The appendix contains the "CoAP cemetery" (Appendix C, possibly later 140 to move into its own draft), documenting roads that the WG decided 141 not to take, in order to spare readers from reinventing them in vain. 142 There is also a "CoAP museum" (Appendix B), which documents previous 143 forms of proposals part of which did make it into the main documents 144 in one form or another. Finally, the "CoAP nursery" (Appendix A) 145 contains half- to fully-baked proposals that might become interesting 146 as the basis for future extensions. 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. 152 The term "byte" is used in its now customary sense as a synonym for 153 "octet". 155 2. Observing Resources in CoAP 157 (Co-Author for this section: Matthias Kovatsch) 159 There are two open issues related to -observe 160 [I-D.ietf-core-observe]: 162 o mixing freshness and observation lifetime, and 164 o non-cacheable resources. 166 To solve the first issue, we think that -observe should be clarified 167 as follows: 169 A server sends at least some notifications as confirmable messages. 170 Each confirmable notification is an opportunity for the server to 171 check if the client is still there. If the client acknowledges the 172 notification, it is assumed to be well and alive and still interested 173 in the resource. If it rejects the message with a reset message or 174 if it doesn't respond, it is assumed not longer to be interested and 175 is removed from the list of observers. So an observation 176 relationship can potentially go on forever, if the client 177 acknowledges each confirmable notification. If the server doesn't 178 send a notification for a while and wants to check if the client is 179 still there, it may send a confirmable notification with the current 180 resource state to check that. 182 So there is no mixing of freshness and lifetime going on. 184 The other issue is a bit less trivial to solve. The problem is that 185 normal CoAP and -observe actually have very different freshness 186 models: 188 Normally, when a client wants to know the current state of a 189 resource, it retrieves a representation, uses it and stores it in its 190 cache. Later, when it wants to know the current state again, it can 191 either use the stored representation provided that it's still fresh, 192 or retrieve a new representation, use it and store it in its cache. 194 If a server knows when the state of the resource will change the next 195 time, it can set the Max-Age of the representation to an accurate 196 time span. So the change of the resource state will coincide with 197 the expiration of the freshness of the representation stored in the 198 client's cache (ignoring network latency). 200 But if the resource changes its state unpredictably at any time, the 201 server can set the Max-Age only to an estimate. If the state then 202 actually changes before the freshness expires, the client wrongly 203 believes it has fresh information. Conversely, if the freshness 204 expires and the client wants to know the current state, the client 205 wrongly believes it has to make a new request although the 206 representation is actually still fresh (this is defused by ETag 207 validation). 209 -observe doesn't have these kinds of problems: the server does not 210 have to predict when the resource will change its state the next 211 time. It just sends a notification when it does. The new 212 representation invalidates the old representation stored in the 213 client's cache. So the client always has a fresh representation that 214 it can use when it wants to know the current resource state without 215 ever having to make a request. An explicit Max-Age is not needed for 216 determining freshness. 218 But -observe has a different set of problems: 220 The first problem is that the resource may change its state more 221 often than there is bandwidth available or the client can handle. 222 Thus, -observe cannot make any guarantee that a client will see every 223 state change. The solution is that -observe guarantees that the 224 client will eventually see the latest state change, and follows a 225 best effort approach to enable the client to see as many state 226 changes as possible. 228 The second problem is that, when a notification doesn't arrive for a 229 while, the client does not know if the resource did not change its 230 state or if the server lost its state and forgot that the client is 231 interested in the resource. We propose the following solution: With 232 each notification that the server sends, it makes a promise to send 233 another notification, and that it will send this next notification at 234 latest after a certain time span. This time span is included with 235 each notification. So when no notification arrives for a while and 236 the time span has not expired yet, the client assumes that the 237 resource did not change its state. If the time span has expired, no 238 notification has arrived and the client wants to know the current 239 state of the resource, it has to make a new request. 241 The third problem is that, when an intermediary is observing a 242 resource and wants to create a response from a representation stored 243 in its cache, it needs to specify a Max-Age. But the intermediary 244 cannot predict when it will receive the next notification, because 245 the next notification can arrive at any time. Unlike the origin 246 server, it also doesn't have the application-specific knowledge that 247 the origin server has. We propose the following solution: With each 248 notification a server sends, it includes a value that an intermediary 249 should use to calculate the Max-Age. 251 To summarize: 253 o A notification doesn't have a Max-Age; it's fresh until the next 254 notification arrives. A notification is the promise for another 255 notification that will arrive at latest after Next-Notification- 256 At-Latest. This value is included with every notification. The 257 promise includes that the server attempts to transmit a 258 notification to the client for the promised time span, even if the 259 client does not seem to respond, e.g., due to a temporary network 260 outage. 262 o A notification also contains another value, called Max-Age-Hint. 263 This value is used by a cache to calculate a Max-Age for the 264 representation if needed. In a cache, the Max-Age-Hint of a 265 representation is counted down like Max-Age. When it reaches 266 zero, however, the representation can be still used to satisfy 267 requests, but is non-cacheable (i.e., Max-Age is 0). The Max-Age- 268 Hint must be less than or equal to Next-Notification-At-Latest. 270 We see two possible ways to encode Next-Notification-At-Latest and 271 Max-Age-Hint in a message: 273 o The first way is to require the values of Next-Notification-At- 274 Latest and Max-Age-Hint to be the same, although they are 275 conceptually unrelated. Then, a single option in the message can 276 be used to hold both values. 278 o The second way is to include two options, one for Next- 279 Notification-At-Latest and one for Max-Age-Hint. Since Next- 280 Notification-At-Latest is less than or equal to Max-Age-Hint, the 281 first option should indicates Max-Age-Hint, and the second option 282 Next-Notification-At-Latest minus Max-Age-Hint with a default 283 value of 0. 285 3. The Base-Uri Option 287 A proxy that forwards a response with embedded URIs may need to 288 indicate a base URI relative to which the embedded URIs need to be 289 interpreted that is different from the original request URI. E.g., 290 when the proxy forwarded the request to a multicast address, it may 291 need to indicate which specific server sent the response. A similar 292 requirement is the need to provide a request URI relative to which 293 the Location-* options can be interpreted. 295 The Base-Uri Option can be used in a response to provide this 296 information. It is structured like the Proxy-Uri option, but it is 297 elective and safe to forward (whether it is a cache-key is 298 irrelevant, as it is a response option only). 300 +--------+----------+-----------+ 301 | Number | Name | Reference | 302 +--------+----------+-----------+ 303 | TBD | Base-Uri | [RFCXXXX] | 304 +--------+----------+-----------+ 306 4. Acknowledgements 308 This work was partially funded by the Klaus Tschira Foundation and by 309 Intel Corporation. 311 Of course, much of the content of this draft is the result of 312 discussions with the [I-D.ietf-core-coap] authors. 314 Patience and Leisure were influenced by a mailing list discussion 315 with Esko Dijk, Kepeng Li, and Salvatore Loreto - thanks! 317 5. References 319 5.1. Normative References 321 [I-D.ietf-core-coap] 322 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 323 Application Protocol (CoAP)", draft-ietf-core-coap-14 324 (work in progress), March 2013. 326 [I-D.ietf-core-observe] 327 Hartke, K., "Observing Resources in CoAP", draft-ietf- 328 core-observe-08 (work in progress), February 2013. 330 [I-D.ietf-httpbis-p1-messaging] 331 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 332 (HTTP/1.1): Message Syntax and Routing", draft-ietf- 333 httpbis-p1-messaging-22 (work in progress), February 2013. 335 [I-D.ietf-httpbis-p4-conditional] 336 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 337 (HTTP/1.1): Conditional Requests", draft-ietf- 338 httpbis-p4-conditional-22 (work in progress), February 339 2013. 341 [I-D.ietf-httpbis-p6-cache] 342 Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 343 Transfer Protocol (HTTP/1.1): Caching", draft-ietf- 344 httpbis-p6-cache-22 (work in progress), February 2013. 346 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 347 Requirement Levels", BCP 14, RFC 2119, March 1997. 349 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 350 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 351 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 353 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 354 Internet: Timestamps", RFC 3339, July 2002. 356 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 357 10646", STD 63, RFC 3629, November 2003. 359 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 360 Encodings", RFC 4648, October 2006. 362 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 363 Interchange", RFC 5198, March 2008. 365 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 366 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 367 May 2008. 369 [RFC5905] Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 370 Time Protocol Version 4: Protocol and Algorithms 371 Specification", RFC 5905, June 2010. 373 [RFC6256] Eddy, W. and E. Davies, "Using Self-Delimiting Numeric 374 Values in Protocols", RFC 6256, May 2011. 376 5.2. Informative References 378 [CoRE201] , "Clarify use of retransmission window for duplicate 379 detection", CoRE ticket #201, 2012, 380 . 382 [CoRE214] , "Adopt vendor-defined option into core-coap", CoRE 383 ticket #214, 2012, 384 . 386 [CoRE230] , "Multiple Location options need to be processed as a 387 unit", CoRE ticket #230, 2012, 388 . 390 [CoRE241] , "Proxy Safe & Cache Key indication for options", CoRE 391 ticket #241, 2012, 392 . 394 [I-D.ietf-lwig-terminology] 395 Bormann, C. and M. Ersue, "Terminology for Constrained 396 Node Networks", draft-ietf-lwig-terminology-02 (work in 397 progress), March 2013. 399 [REST] Fielding, R., "Architectural Styles and the Design of 400 Network-based Software Architectures", 2000. 402 [RFC1924] Elz, R., "A Compact Representation of IPv6 Addresses", RFC 403 1924, April 1996. 405 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/ 406 1.1", RFC 2817, May 2000. 408 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 409 "Deprecating the "X-" Prefix and Similar Constructs in 410 Application Protocols", BCP 178, RFC 6648, June 2012. 412 Appendix A. The Nursery (Things that still need to ripen a bit) 414 A.1. Envelope Options 416 As of [I-D.ietf-core-coap], options can take one of four types, two 417 of which are mostly identical: 419 o uint: A non-negative integer which is represented in network byte 420 order using a variable number of bytes (see [I-D.ietf-core-coap] 421 Appendix A); 423 o string: a sequence of bytes that is nominally a Net-Unicode string 424 [RFC5198]; 426 o opaque: a sequence of bytes. 428 o empty (not explicitly identified as a fourth type in 429 [I-D.ietf-core-coap]). 431 It turns out some options would benefit from some internal structure. 432 Also, it may be a good idea to be able to bundle multiple options 433 into one, in order to ensure consistency for a set of elective 434 options that need to be processed all or nothing (i.e., the option 435 becomes critical as soon as another option out of the set is 436 processed, too). 438 In this section, we introduce a fifth CoAP option type: Envelope 439 options. 441 An envelope option is a sequence of bytes that looks and is 442 interpreted exactly like a CoAP sequence of options. Instead of an 443 option count or an end-of-option marker, the sequence of options is 444 terminated by the end of the envelope option. 446 The nested options (options inside the envelope option) may come from 447 the same number space as the top-level CoAP options, or the envelope 448 option may define its own number space - this choice needs to be 449 defined for each envelope option. 451 If the top-level number space is used, the envelope option typically 452 will restrict the set of options that actually can be used in the 453 envelope. In particular, it is unlikely that an envelope option will 454 allow itself inside the envelope (this would be a recursive option). 456 Envelope options are a general, but simple mechanism. Some of its 457 potential uses are illustrated by two examples in the cemetery: 458 Appendix C.1 and Appendix C.2. (Each of these examples has its own 459 merits and demerits, which led us to decide not to pursue either of 460 them right now, but this should be discussed separately from the 461 concept of Envelope options employed in the examples.) 463 A.2. Payload-Length Option 465 Not all transport mappings may provide an unambiguous length of the 466 CoAP message. For UDP, it may also be desirable to pack more than 467 one CoAP message into one UDP payload (aggregation); in that case, 468 for all but the last message there needs to be a way to delimit the 469 payload of that message. 471 This can be solved using a new option, the Payload-Length option. If 472 this option is present, the value of this option is an unsigned 473 integer giving the length of the payload of the message (note that 474 this integer can be zero for a zero-length payload, which can in turn 475 be represented by a zero-length option value). (In the UDP 476 aggregation case, what would have been in the payload of this message 477 after "payload-length" bytes is then actually one or more additional 478 messages.) 480 A.3. URI Authorities with Binary Adresses 482 One problem with the way URI authorities are represented in the URI 483 syntax is that the authority part can be very bulky if it encodes an 484 IPv6 address in ASCII. 486 Proposal: Provide an option "Uri-Authority-Binary" that can be an 487 even number of bytes between 2 and 18 except 12 or 14. 489 o If the number of bytes is 2, the destination IP address of the 490 packet transporting the CoAP message is implied. 492 o If the number of bytes is 4 or 6, the first four bytes of the 493 option value are an IPv4 address in binary. 495 o If the number of bytes is 8 or 10, the first eight bytes are the 496 lower 64 bits of an IPv6 address; the upper eight bytes are 497 implied from the destination address of the packet transporting 498 the CoAP message. 500 o If the number of bytes is 16 or 18, the first 16 bytes are an IPv6 501 address. 503 o If two more bytes remain, this is a port number (as always in 504 network byte order). 506 The resulting authority is (conceptually translated into ASCII and) 507 used in place of an Uri-Authority option, or inserted into a Proxy- 508 Uri. Examples: 510 +--------------+------------------+---------+-----------------------+ 511 | Proxy-Uri | Uri-Authority- | Uri- | URI | 512 | | Binary | Path | | 513 +--------------+------------------+---------+-----------------------+ 514 | (none) | (none) | (none) | "/" | 515 | | | | | 516 | (none) | (none) | 'temp' | "/temp" | 517 | | | | | 518 | (none) | 2 bytes: 61616 | 'temp' | "coap://[DA]:61616/te | 519 | | | | mp" | 520 | | | | | 521 | (none) | 16 bytes: | temp | "coap://[2000::1]/tem | 522 | | 2000::1 | | p" | 523 | | | | | 524 | 'http://' | 10 bytes: | (none) | "http://[DA::123:45]: | 525 | | ::123:45 + 616 | | 616" | 526 | | | | | 527 | 'http:///tem | 18 bytes: | (none) | "http://[2000::1]:616 | 528 | p' | 2000::1 + 616 | | /temp" | 529 +--------------+------------------+---------+-----------------------+ 531 A.4. Length-aware number encoding (o256) 533 The number encoding defined in Appendix A of [I-D.ietf-core-coap] has 534 one significant flaw: Every number has an infinite number of 535 representations, which can be derived by adding leading zero bytes. 536 This runs against the principle of minimizing unnecessary choice. 537 The resulting uncertainty in encoding ultimately leads to unnecessary 538 interoperability failures. (It also wastes a small fraction of the 539 encoding space, i.e., it wastes bytes.) 541 We could solve the first, but not the second, by outlawing leading 542 zeroes, but then we have to cope with error cases caused by illegal 543 values, another source of interoperability problems. 545 The number encoding "o256" defined in this section avoids this flaw. 546 The suggestion is not to replace CoAP's "uint" encoding wholesale 547 (CoAP is already too widely implemented for such a change), but to 548 consider this format for new options. 550 The basic requirements for such an encoding are: 552 o numbers are encoded as a sequence of zero or more bytes 554 o each number has exactly one encoding 556 o for a < b, encoding-size(a) <= encoding-size(b) -\u002D i.e., with 557 larger numbers, the encoding only gets larger, never smaller 558 again. 560 o within each encoding size (0 bytes, 1 byte, etc.), lexicographical 561 ordering of the bytes is the same as numeric ordering 563 Obviously, there is only one encoding that satisfies all these 564 requirements. As illustrated by Figure 1, this is unambiguously 565 derived by 567 1. enumerating all possible byte sequences, ordered by length and 568 within the same length in lexicographic ordering, and, 570 2. assigning sequential cardinals. 572 0x'' -> 0 573 0x'00' -> 1 574 0x'01' -> 2 575 0x'02' -> 3 576 ... 577 0x'fe' -> 255 578 0x'ff' -> 256 579 0x'0000' -> 257 580 0x'0001' -> 258 581 ... 582 0x'fefd' -> 65534 583 0x'fefe' -> 65535 584 0x'feff' -> 65536 585 ... 586 0x'ffff' -> 65792 587 0x'000000' -> 65793 588 0x'000001' -> 65794 590 Figure 1: Enumerating byte sequences by length and then lexicographic 591 order 593 This results in an exceedingly simple algorithm: each byte is 594 interpreted in the base-256 place-value system, but stands for a 595 number between 1 and 256 instead of 0 to 255. We therefore call this 596 encoding "o256" (one-to-256). 0 is always encoded in zero bytes; 1 597 to 256 is one byte, 257 (0x101) to 65792 (0x10100) is two bytes, 598 65793 (0x10101) to 16843008 (0x1010100) is three bytes, etc. 600 To further illustrate the algorithmic simplicity, pseudocode for 601 encoding and decoding is given in Figure 2 and Figure 3, respectively 602 (in the encoder, "prepend" stands for adding a byte at the _leading_ 603 edge, the requirement for which is a result of the network byte 604 order). Note that this differs only in a single subtraction/addition 605 (resp.) of one from the canonical algorithm for Appendix A uints. 607 while num > 0 608 num -= 1 609 prepend(num & 0xFF) 610 num >>= 8 611 end 613 Figure 2: o256 encoder (pseudocode) 615 num = 0 616 each_byte do |b| 617 num <<= 8 618 num += b + 1 619 end 621 Figure 3: o256 decoder (pseudocode) 623 On a more philosophical note, it can be observed that o256 solves the 624 inverse problem of Self-Delimiting Numeric Values (SDNV) [RFC6256]: 625 SDNV encodes variable-length numbers together with their length 626 (allowing decoding without knowing their length in advance, deriving 627 delimiting information from the number encoding). o256 encodes 628 variable-length numbers when there is a way to separately convey the 629 length (as in CoAP options), encoding (and later deriving) a small 630 part of the numeric value into/from that size information. 632 A.5. SMS encoding 634 For use in SMS applications, CoAP messages can be transferred using 635 SMS binary mode. However, there is operational experience showing 636 that some environments cannot successfully send a binary mode SMS. 638 For transferring SMS in character mode (7-bit characters), 639 base64-encoding [RFC4648] is an obvious choice. 3 bytes of message 640 (24 bits) turn into 4 characters, which cosume 28 bits. The overall 641 overhead is approximately 17 %; the maximum message size is 120 bytes 642 (160 SMS characters). 644 If a more compact encoding is desired, base85 encoding can be 645 employed (however, probably not the version defined in [RFC1924] 646 -\u002D instead, the version used in tools such as btoa and PDF 647 should be chosen). However, this requires division operations. 648 Also, the base85 character set includes several characters that 649 cannot be transferred in a single 7-bit unit in SMS and/or are known 650 to cause operational problems. A modified base85 character set can 651 be defined to solve the latter problem. 4 bytes of message (32 bits) 652 turn into 5 characters, which consume 35 bits. The overall overhead 653 is approximately 9.3 %; the resulting maximum message size is 128 654 bytes (160 SMS characters). 656 Base64 and base85 do not make use of the fact that much CoAP data 657 will be ASCII-based. Therefore, we define the following experimental 658 SMS encoding. 660 A.5.1. ASCII-optimized SMS encoding 662 Not all 128 theoretically possible SMS characters are operationally 663 free of problems. We therefore define: 665 Shunned code characters: @ sign, as it maps to 0x00 667 LF and CR signs (0x0A, 0x0D) 669 uppercase C cedilla (0x09), as it is often mistranslated in 670 gateways 671 ESC (0x1B), as it is used in certain character combinations only 673 Some ASCII characters cannot be transferred in the base SMS character 674 set, as their code positions are taken by non-ASCII characters. 675 These are simply encoded with their ASCII code positions, e.g., an 676 underscore becomes a section mark (even though underscore has a 677 different code position in the SMS character set). 679 Equivalently translated input bytes: $, @, [, \, ], ^, _, `, {, |, 680 }, ~, DEL 682 In other words, bytes 0x20 to 0x7F are encoded into the same code 683 positions in the 7-bit character set. 685 Out of the remaining code characters, the following SMS characters 686 are available for encoding: 688 Non-equivalently translated (NET) code characters: 0x01 to 0x08, (8 689 characters) 691 0x0B, 0x0C, (2 characters) 693 0x0E to 0x1A, (13 characters) 695 0x1C to 0x1F, (4 characters) 697 Of the 27 NET code characters, 18 are taken as prefix characters (see 698 below), and 8 are defined as directly translated characters: 700 Directly translated bytes: Equivalently translated input bytes are 701 represented as themselves 703 0x00 to 0x07 are represented as 0x01 to 0x08 705 This leaves 0x08 to 0x1F and 0x80 to 0xFF. Of these, the bytes 0x80 706 to 0x87 and 0xA0 to 0xFF are represented as the bytes 0x00 to 0x07 707 (represented by characters 0x01 to 0x08) and 0x20 to 0x7F, with a 708 prefix of 1 (see below). The characters 0x08 to 0x1F are represented 709 as the characters 0x28 to 0x3F with a prefix of 2 (see below). The 710 characters 0x88 to 0x9F are represented as the characters 0x48 to 711 0x5F with a prefix of 2 (see below). (Characters 0x01 to 0x08, 0x20 712 to 0x27, 0x40 to 0x47, and 0x60 to 0x7f with a prefix of 2 are 713 reserved for future extensions, which could be used for some 714 backreferencing or run-length compression.) 715 Bytes that do not need a prefix (directly translated bytes) are sent 716 as is. Any byte that does need a prefix (i.e., 1 or 2) is preceded 717 by a prefix character, which provides a prefix for this and the 718 following two bytes as follows: 720 +------+-----+---+------+-----+ 721 | 0x0B | 100 | | 0x15 | 200 | 722 +------+-----+---+------+-----+ 723 | 0x0C | 101 | | 0x16 | 201 | 724 | | | | | | 725 | 0x0E | 102 | | 0x17 | 202 | 726 | | | | | | 727 | 0x0F | 110 | | 0x18 | 210 | 728 | | | | | | 729 | 0x10 | 111 | | 0x19 | 211 | 730 | | | | | | 731 | 0x11 | 112 | | 0x1A | 212 | 732 | | | | | | 733 | 0x12 | 120 | | 0x1C | 220 | 734 | | | | | | 735 | 0x13 | 121 | | 0x1D | 221 | 736 | | | | | | 737 | 0x14 | 122 | | 0x1E | 222 | 738 +------+-----+---+------+-----+ 740 (This leaves one non-shunned character, 0x1F, for future extension.) 742 The coding overhead of this encoding for random bytes is similar to 743 Base85, without the need for a division/multiplication. For bytes 744 that are mostly ASCII characters, the overhead can easily become 745 negative. (Conversely, for bytes that are more likely to be non- 746 ASCII than in a random sequence of bytes, the overhead becomes 747 greater.) 749 So, for instance, for the CoAP message in Figure 4: 751 ver tt code mid 752 1 ack 2.05 17033 753 content_type 40 754 token sometok 755 3c 2f 3e 3b 74 69 74 6c 65 3d 22 47 65 6e 65 72 |;title="Gener| 756 61 6c 20 49 6e 66 6f 22 3b 63 74 3d 30 2c 3c 2f |al Info";ct=0,;if="clock"| 758 3b 72 74 3d 22 54 69 63 6b 73 22 3b 74 69 74 6c |;rt="Ticks";titl| 759 65 3d 22 49 6e 74 65 72 6e 61 6c 20 43 6c 6f 63 |e="Internal Cloc| 760 6b 22 3b 63 74 3d 30 2c 3c 2f 61 73 79 6e 63 3e |k";ct=0,| 761 3b 63 74 3d 30 |;ct=0 | 762 Figure 4: CoAP response message as captured and decoded 764 The 116 byte unencoded message is shown as ASCII characters in Figure 765 5 (\xDD stands for the byte with the hex digits DD): 767 bEB\x89\x11(\xA7sometok;title="General Info";ct=0, 768 ;if="clock";rt="Ticks";title="Internal Clock";ct=0,;ct=0 770 Figure 5: CoAP response message shown as unencoded characters 772 The equivalent SMS encoding is shown as equivalent-coded SMS 773 characters in Figure 6 (7 bits per character, \x12 is a 220 prefix 774 and \x0B is a 100 prefix, the rest is shown in equivalent encoding), 775 adding two characters of prefix overhead, for a total length of 118 776 7-bit characters or 104 (103.25 plus padding) bytes: 778 bEB\x12I1(\x0B'sometok;title="General Info";ct=0, 779 ;if="clock";rt="Ticks";title="Internal Clock";ct=0,;ct=0 781 Figure 6: CoAP response message shown as SMS-encoded characters 783 A.6. CONNECT 785 [RFC2817] defines the HTTP CONNECT method to establish a TCP tunnel 786 through a proxy so that end-to-end TLS connections can be made 787 through the proxy. Recently, a requirement for similar functionality 788 has been discussed for CoAP. This section defines a straw-man 789 CONNECT method and related methods and response codes for CoAP. 791 (IANA considerations for this section TBD.) 793 A.6.1. Requesting a Tunnel with CONNECT 795 CONNECT is allocated as a new method code in the "CoAP Method Codes" 796 registry. When a client makes a CONNECT request to an intermediary, 797 the intermediary evaluates the Uri-Host, Uri-Port, and/or the 798 authority part of the Proxy-Uri Options in a way that is defined by 799 the security policy of the intermediary. If the security policy 800 allows the allocation of a tunnel based on these parameters, the 801 method returns an empty payload and a response code of 2.30 Tunnel 802 Established. Other possible response codes include 4.03 Forbidden. 804 It may be the case that the intermediary itself can only reach the 805 requested origin server through another intermediary. In this case, 806 the first intermediary SHOULD make a CONNECT request of that next 807 intermediary, requesting a tunnel to the authority. A proxy MUST NOT 808 respond with any 2.xx status code unless it has either a direct or 809 tunnel connection established to the authority. 811 An origin server which receives a CONNECT request for itself MAY 812 respond with a 2.xx status code to indicate that a tunnel is 813 established to itself. 815 Code 2.30 "Tunnel Established" is allocated as a new response code in 816 the "CoAP Response Codes" registry. 818 A.6.2. Using a CONNECT Tunnel 820 Any successful (2.xx) response to a CONNECT request indicates that 821 the intermediary has established a tunnel to the requested host and 822 port. The tunnel is bound to the requesting end-point and the Token 823 supplied in the request (as always, the default Token is admissible). 824 The tunnel can be used by the client by making a DATAGRAM request. 826 DATAGRAM is allocated as a new method code in the "CoAP Method Codes" 827 registry. When a client makes a DATAGRAM request to an intermediary, 828 the intermediary looks up the tunnel bound to the client end-point 829 and Token supplied in the DATAGRAM request (no other Options are 830 permitted). If a tunnel is found and the intermediary's security 831 policy permits, the intermediary forwards the payload of the DATAGRAM 832 request as the UDP payload towards the host and port established for 833 the tunnel. No response is defined for this request (note that the 834 request can be given as a CON or NON request; for CON, there will be 835 an ACK on the message layer if the tunnel exists). 837 The security policy on the intermediary may restrict the allowable 838 payloads based on its security policy, possibly considering host and 839 port. An inadmissible payload SHOULD cause a 4.03 Forbidden response 840 with a diagnostic message as payload. 842 The UDP payload of any datagram received from the tunnel and admitted 843 by the security policy is forwarded to the client as the payload of a 844 2.31 "Datagram Received" response. The response does not carry any 845 Option except for Token, which identifies the tunnel towards the 846 client. 848 Code 2.31 "Datagram Received" is allocated as a new response code in 849 the "CoAP Response Codes" registry. 851 An origin server that has established a tunnel to itself processes 852 the CoAP payloads of related DATAGRAM requests as it would process an 853 incoming UDP payload, and forwards what would be outgoing UDP 854 payloads in 2.31 "Datagram Received" responses. 856 A.6.3. Closing down a CONNECT Tunnel 857 A 2.31 "Datagram Received" response may be replied to with a RST, 858 which closes down the tunnel. Similarly, the Token used in the 859 tunnel may be reused by the client for a different purpose, which 860 also closes down the tunnel. 862 Appendix B. The Museum (Things we did, but maybe not exactly this way) 864 B.1. Getting rid of artificial limitations 866 _Artificial limitations_ are limitations of a protocol or system that 867 are not rooted in limitations of actual capabilities, but in 868 arbitrary design decisions. Proper system design tries to avoid 869 artificial limitations, as these tend to cause complexity in systems 870 that need to work with these limitations. 872 E.g., the original UNIX filesystem had an artificial limitation of 873 the length of a path name component to 14 bytes. This led to a 874 cascade of workarounds in programs that manipulate file names: E.g., 875 systematically replacing a ".el" extension in a filename with a 876 ".elc" for the compiled file might exceed the limit, so all ".el" 877 files were suddenly limited to 13-byte filenames. 879 Note that, today, there still is a limitation in most file system 880 implementations, typically at 255. This just happens to be high 881 enough to rarely be of real-world concern; we will refer to this case 882 as a "painless" artificial limitation. 884 CoAP-08 had two highly recognizable artificial limitations in its 885 protocol encoding 887 o The number of options in a single message is limited to 15 max. 889 o The length of an option is limited to 270 max. 891 It has been argued that the latter limitation causes few problems, 892 just as the 255-byte path name component limitation in filenames 893 today causes few problems. Appendix B.1.1 provided a design to 894 extend this; as a precaution to future extensions of this kind, the 895 current encoding for length 270 (eight ones in the extension byte) 896 could be marked as reserved today. Since, Matthias Kovatsch has 897 proposed a simpler scheme that seems to gain favor in the WG, see 898 Appendix B.1.4. 900 The former limitation has been solved in CoAP-09. A historical 901 discussion of other approaches for going beyond 15 options is in 902 Appendix B.1.2. Appendix B.1.3 discusses implementation. 904 B.1.1. Beyond 270 bytes in a single option 906 The authors would argue that 270 as the maximum length of an option 907 is already beyond the "painless" threshold. 909 If that is not the consensus of the WG, the scheme can easily be 910 extended as in Figure 7: 912 for 15..269: 913 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 914 | Option Delta | 1 1 1 1 | Length - 15 | 915 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 916 | Option Value ... 917 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 919 for 270..65805: 920 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 921 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 922 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 923 | Length - 270 (in network byte order) | 924 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 925 | Option Value ... 926 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 928 Figure 7: Ridiculously Long Option Header 930 The infinite number of obvious variations on this scheme are left as 931 an exercise to the reader. 933 Again, as a precaution to future extensions, the current encoding for 934 length 270 (eight ones in the extension byte) could be marked as 935 reserved today. 937 B.1.2. Beyond 15 options 939 (This section keeps discussion that is no longer needed as we have 940 agreed to do what is documented in Appendix B.1.3). 942 The limit of 15 options is motivated by the fixed four-bit field "OC" 943 that is used for indicating the number of options in the fixed-length 944 CoAP header (Figure 8). 946 0 1 2 3 947 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 948 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 949 |Ver| T | OC | Code | Message ID | 950 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 951 | Options (if any) ... 953 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 954 | Payload (if any) ... 955 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 957 Figure 8: Four-byte fixed header in a CoAP Message 959 Note that there is another fixed four-bit field in CoAP: the option 960 length (Figure 9 - note that this figure is not to the same scale as 961 the previous figure): 963 0 1 2 3 4 5 6 7 964 +---+---+---+---+---+---+---+---+ 965 | Option Delta | Length | for 0..14 966 +---+---+---+---+---+---+---+---+ 967 | Option Value ... 968 +---+---+---+---+---+---+---+---+ 970 Figure 9: Short Option Header 972 Since 15 is inacceptable for a maximum option length, the all-ones 973 value (15) was taken out of the set of allowable values for the short 974 header, and a long header was introduced that allows the insertion of 975 an extension byte (Figure 10): 977 for 15..270: 978 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 979 | Option Delta | 1 1 1 1 | Length - 15 | 980 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 981 | Option Value ... 982 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 984 Figure 10: Long Option Header 986 We might want to use the same technique for the CoAP header as well. 987 There are two obvious places where the extension byte could be 988 placed: 990 1. right after the byte carrying the OC field, so the structure is 991 the same as for the option header; 993 2. right after the fixed-size CoAP header. 995 Both solutions lose the fixed-size-ness of the CoAP header. 997 Solution 1 has the disadvantage that the CoAP header is also changing 998 in structure: The extension byte is wedged between the first and the 999 second byte of the CoAP header. This is unfortunate, as the number 1000 of options only comes into play when the option processing begins, so 1001 it is more natural to use solution 2 (Figure 11): 1003 0 1 2 3 1004 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 1005 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1006 |Ver| T | 15 | Code | Message ID | 1007 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1008 | OC - 15 | Options ... 1009 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1010 | Payload (if any) ... 1011 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1013 Figure 11: Extended header for CoAP Messages with 15+ options 1015 This would allow for up to 270 options in a CoAP message, which is 1016 very likely way beyond the "painless" threshold. 1018 B.1.2.1. Implementation considerations 1020 For a message decoder, this extension creates relatively little pain, 1021 as the number of options only becomes interesting when the encoding 1022 turns to the options part of the message, which is then simply lead 1023 in by the extension byte if the four-bit field is 15. 1025 For a message encoder, this extension is not so rosy. If the encoder 1026 is constructing the message serially, it may not know in advance 1027 whether the number of options will exceed 14. None of the following 1028 implementation strategies is particularly savory, but all of them do 1029 work: 1031 1. Encode the options serially under the assumption that the number 1032 of options will be 14 or less. When the 15th option needs to be 1033 encoded, abort the option encoding, and restart it from scratch 1034 one byte further to the left. 1036 2. Similar to 1, except that the bytes already encoded are all moved 1037 one byte to right, the extension byte is inserted, and the option 1038 encoding process is continued. 1040 3. The encoder always leaves space for the extension byte (at least 1041 if it can't prove the number will be less thatn 14). If the 1042 extension byte is not needed, an Option 0 with length 0 is 1043 encoded instead (i.e., one byte is wasted - this option is 1044 elective and will be ignored by the receiver). 1046 As a minimum, to enable strategy 3, the option 0 should be reserved 1047 at least for the case of length=0. 1049 B.1.2.2. What should we do now? 1051 As a minimum proposal for the next version of CoAP, the value 15 for 1052 OC should be marked as reserved today. 1054 B.1.2.3. Alternatives 1056 One alternative that has been discussed previously is to have an 1057 "Options" Option, which allows the carriage of multiple options in 1058 the belly of a single one. This could also be used to carry more 1059 than 15 options. However: 1061 o The conditional introduction of an Options option has 1062 implementation considerations that are likely to be more severe 1063 than the ones listed above; 1065 o since 270 bytes may not be enough for the encoding of _all_ 1066 options, the "Options" option would need to be repeatable. This 1067 creates many different ways to encode the same message, leading to 1068 combinatorial explosion in test cases for ensuring 1069 interoperability. 1071 B.1.2.4. Alternative: Going to a delimiter model 1073 Another alternative is to spend the additional byte not as an 1074 extended count, but as an option terminator. 1076 B.1.3. Implementing the option delimiter for 15 or more options 1078 Implementation note: As can be seen from the proof of concept code 1079 in Figure 12, the actual implementation cost for a decoder is 1080 around 4 lines of code (or about 8-10 machine code instructions). 1082 while numopt > 0 1083 nextbyte = ... get next byte 1085 if numopt == 15 # new 1086 break if nextbyte == 0xF0 # new 1087 else # new 1088 numopt -= 1 1089 end # new 1091 ... decode delta and length from nextbyte and handle them 1092 end 1094 Figure 12: Implementing the Option Terminator 1096 Similarly, creating the option terminator needs about four more lines 1097 (not marked "old" in the C code in Figure 13). 1099 b0 = 0x40 + (tt << 4); /* old */ 1100 buffer[0] = b0 + 15; /* guess first byte */ 1102 .... encode options .... /* old */ 1104 if (option_count >= 15 || first_fragment_already_shipped) 1105 buffer[pos++] = 0xF0; /* use delimiter */ 1106 else /* save a byte: */ 1107 buffer[0] = b0 + option_count; /* old: backpatch */ 1109 Figure 13: Creating the Option Terminator 1111 B.1.4. Option Length encoding beyond 270 bytes 1113 For option lengths beyond 270 bytes, we reserve the value 255 of an 1114 extension byte to mean "add 255, read another extension byte" Figure 1115 14. While this causes the length of the option header to grow 1116 linearly with the size of the option value, only 0.4 % of that size 1117 is used. With a focus on short options, this encoding is justified. 1119 for 15..269: 1120 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1121 | Option Delta | 1 1 1 1 | Length - 15 | 1122 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1123 | Option Value ... 1124 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1126 for 270..524: 1127 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1128 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 1129 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1130 | Length - 270 | Option Value ... 1131 +---+---+---+---+---+---+---+---+ 1132 | 1133 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1135 for 525..779: 1136 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1137 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 1138 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1139 | 1 1 1 1 1 1 1 1 | Length - 525 | 1140 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1141 | Option Value ... 1142 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1144 for 780..1034: 1145 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1146 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 1147 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1148 | 1 1 1 1 1 1 1 1 | 1 1 1 1 1 1 1 1 | 1149 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1150 | Length - 780 | Option Value ... 1151 +---+---+---+---+---+---+---+---+ 1152 | 1153 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 1155 Figure 14: Options beyond 270 bytes 1157 Options that are longer than 1034 bytes MUST NOT be sent; an option 1158 that has 255 (all one bits) in the field called "Length - 780" MUST 1159 be rejected upon reception as an invalid option. 1161 In the process, the maximum length of all options that are currently 1162 set at 270 should now be set to a carefully chosen value. With the 1163 purely encoding-based limit gone, Uri-Proxy should now be restored to 1164 be a non-repeatable option. 1166 A first proposal for a new set of per-option length restrictions 1167 follows: 1169 +--------+---------------------+-----+------+--------+--------+ 1170 | number | name | min | max | type | repeat | 1171 +--------+---------------------+-----+------+--------+--------+ 1172 | 1 | content_type | 0 | 2 | uint | - | 1173 | | | | | | | 1174 | 2 | max_age | 0 | 4 | uint | - | 1175 | | | | | | | 1176 | 3 | proxy_uri | 1 | 1023 | string | - | 1177 | | | | | | | 1178 | 4 | etag | 1 | 8 | opaque | yes | 1179 | | | | | | | 1180 | 5 | uri_host | 1 | 255 | string | - | 1181 | | | | | | | 1182 | 6 | location_path | 0 | 255 | string | yes | 1183 | | | | | | | 1184 | 7 | uri_port | 0 | 2 | uint | - | 1185 | | | | | | | 1186 | 8 | location_query | 0 | 255 | string | yes | 1187 | | | | | | | 1188 | 9 | uri_path | 0 | 255 | string | yes | 1189 | | | | | | | 1190 | 10 | observe | 0 | 2 | uint | - | 1191 | | | | | | | 1192 | 11 | token | 1 | 8 | opaque | - | 1193 | | | | | | | 1194 | 12 | accept | 0 | 2 | uint | yes | 1195 | | | | | | | 1196 | 13 | if_match | 0 | 8 | opaque | yes | 1197 | | | | | | | 1198 | 14 | registered_elective | 1 | 1023 | opaque | yes | 1199 | | | | | | | 1200 | 15 | uri_query | 1 | 255 | string | yes | 1201 | | | | | | | 1202 | 17 | block2 | 0 | 3 | uint | - | 1203 | | | | | | | 1204 | 18 | size | 0 | 4 | uint | - | 1205 | | | | | | | 1206 | 19 | block1 | 0 | 3 | uint | - | 1207 | | | | | | | 1208 | 21 | if_none_match | 0 | 0 | empty | - | 1209 | | | | | | | 1210 | 25 | registered_critical | 1 | 1023 | opaque | yes | 1211 +--------+---------------------+-----+------+--------+--------+ 1213 (Option 14 with a length of 0 is a fencepost only.) 1215 B.2. Registered Option 1217 CoAP's option encoding is highly efficient, but works best with small 1218 option numbers that do not require much fenceposting. The CoAP 1219 Option Number Registry therefore has a relatively heavyweight 1220 registration requirement: "IETF Review" as described in [RFC5226]. 1222 However, there is also considerable benefit in a much looser registry 1223 policy, enabling a first-come-first-served policy for a relatively 1224 large option number space. 1226 Here, we discuss two solutions that enable such a registry. One is 1227 to define a separate mechanism for registered options, discussed in 1228 Appendix B.2.1. Alternatively, we could make it easier to use a 1229 larger main option number space, discussed in Appendix B.2.2. 1231 B.2.1. A Separate Suboption Number Space 1233 This alternative defines a separate space of suboption numbers, with 1234 an expert review [RFC5226] (or even first-come-first-served) 1235 registration policy. If expert review is selected for this registry, 1236 it would be with a relatively loose policy delegated to the expert. 1237 This draft proposes leaving the registered suboption numbers 0-127 to 1238 expert review with a policy that mainly focuses on the availability 1239 of a specification, and 128-16383 for first-come-first-served where 1240 essentially only a name is defined. 1242 The "registered" options are used in conjunction with this suboption 1243 number registry. They use two normal CoAP option numbers, one for 1244 options with elective semantics (Registered-Elective) and one for 1245 options with critical semantics (Registered-Critical). The suboption 1246 numbers are not separate, i.e. one registered suboption number might 1247 have some elective semantics and some other critical semantics (e.g., 1248 for the request and the response leg of an exchange). The option 1249 value starts with an SDNV [RFC6256] of the registered suboption 1250 number. (Note that there is no need for an implementation to 1251 understand SDNVs, it can treat the prefixes as opaque. One could 1252 consider the SDNVs as a suboption prefix allocation guideline for 1253 IANA as opposed to a number encoding.) 1255 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1256 |1 0 0 0 0 0 0 1|0 1 1 1 0 0 1 1| value... | 1257 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1258 \___SDNV of registered number___/ 1260 Figure 15: Example option value for registered option 1262 Note that a Registered Option cannot be empty, because there would be 1263 no space for the SDNV. Also, the empty option 14 is reserved for 1264 fenceposting ([I-D.ietf-core-coap], section 3.2). (Obviously, once a 1265 Registered-Elective Option is in use, there is never a need for a 1266 fence-post for option number 14.) 1268 The Registered-Elective and Registered-Critical Options are 1269 repeatable. 1271 +------+----------+---------------------+--------+--------+---------+ 1272 | No. | C/E | Name | Format | Length | Default | 1273 +------+----------+---------------------+--------+--------+---------+ 1274 | 14 | Elective | Registered-Elective | (see | 1-1023 | (none) | 1275 | | | | above) | B | | 1276 | | | | | | | 1277 | 25 | Critical | Registered-Critical | (see | 1-1023 | (none) | 1278 | | | | above) | B | | 1279 +------+----------+---------------------+--------+--------+---------+ 1281 This solves CoRE issue #214 [CoRE214]. (How many options we need 1282 will depend on the resolution of #241 [CoRE241].) 1284 B.2.2. Opening Up the Option Number Space 1286 The disadvantage of the registered-... options is that there is a 1287 significant syntactic difference between options making use of this 1288 space and the usual standard options. This creates a problem not 1289 unlike that decried in [RFC6648]. 1291 The alternative discussed in this section reduces the distance by 1292 opening up the main Option number space instead. 1294 There is still a significant incentive to use low-numbered Options. 1295 However, the proposal reduces the penalty for using a high-numbered 1296 Option to two or three bytes. More importantly, using a cluster of 1297 related high-numbered options only carries a total penalty of two or 1298 three bytes. 1300 The main reason high-numbered options are expensive to use and thus 1301 the total space is relatively limited is that the option delta 1302 mechanism only allows increasing the current option number by up to 1303 14 per one-byte fencepost. To use, e.g., Option number 1234 together 1304 with the usual set of low-numbered Options, one needs to insert 88 1305 fence-post bytes. This is prohibitive. 1307 Enabling first-come-first-served probably requires easily addressing 1308 a 16-bit option number space, with some potential increase later in 1309 the lifetime of the protocol (say, 10 to 15 years from now). 1311 To enable the use of large option numbers, one needs a way to advance 1312 the Option number in bigger steps than possible by the Option Delta. 1313 So we propose a new construct, the Long Jump construct, to move the 1314 Option number forward. 1316 B.2.2.1. Long Jump construct 1317 The following construct can occur in front of any Option: 1319 0 1 2 3 4 5 6 7 1320 +---+---+---+---+---+---+---+---+ 1321 | 1 1 1 1 | 0 0 0 1 | 0xf1 (Delta = 15) 1322 +---+---+---+---+---+---+---+---+ 1324 0 1 2 3 4 5 6 7 1325 +---+---+---+---+---+---+---+---+ 1326 | 1 1 1 1 | 0 0 1 0 | 0xf2 1327 +---+---+---+---+---+---+---+---+ 1328 | Long Jump Value | (Delta/8)-2 1329 +---+---+---+---+---+---+---+---+ 1331 0 1 2 3 4 5 6 7 1332 +---+---+---+---+---+---+---+---+ 1333 | 1 1 1 1 | 0 0 1 1 | 0xf3 1334 +---+---+---+---+---+---+---+---+ 1335 | Long Jump Value, MSB | 1336 +---+---+---+---+---+---+---+---+ (Delta/8)-258 1337 | Long Jump Value, LSB | 1338 +---+---+---+---+---+---+---+---+ 1340 Figure 16: Long Jump Format 1342 This construct is not by itself an Option. It can occur in front of 1343 any Option to increase the current Option number that then goes into 1344 its Option number calculation. The increase is done in multiples of 1345 eight. More specifically, the actual addition to the current Option 1346 number is computed as follows: 1348 Delta = ((Long Jump Value) + N) * 8 1350 where N is 2 for the one-byte version and N is 258 for the two-byte 1351 version. 1353 A Long Jump MUST be followed by an actual Option, i.e., it MUST NOT 1354 be followed by another Long Jump or an end-of-options indicator. A 1355 message violating this MUST be rejected as malformed. 1357 Long Jumps do NOT count as Options in the Option Count field of the 1358 header (i.e., they cannot by themselves end the Option sequence). 1360 B.2.2.2. Discussion 1362 Adding a mechanism at this late stage creates concerns of backwards 1363 compatibility. A message sender never needs to implement long-jumps 1364 unless it wants to make use of a high-numbered option. So this 1365 mechanism can be added once a high-numbered option is added. A 1366 message receiver, though, would more or less unconditionally have to 1367 implement the mechanism, leading to unconditional additional 1368 complexity. There are good reasons to minimize this, as follows: 1370 o The increase in multiples of eight allows looking at an option and 1371 finding out whether it is critical or not even if the Long Jump 1372 value has just been skipped (as opposed to having been processed 1373 fully). (It also allows accessing up to approximately 2048 1374 options with a two-byte Long Jump.) This allows a basic 1375 implementation that does not implement any high-numbered options 1376 to simply ignore long jumps and any elective options behind them, 1377 while still properly reacting to critical options. 1379 o There is probably a good reason to disallow long-jumps that lead 1380 to an option number of 42 and less, enabling simple receivers to 1381 do the above simplification. 1383 o It might seem obvious to remove the fenceposting mechanism 1384 altogether in favor of long jumps. This is not advisable: 1385 Fenceposting already has zero implementation effort at the 1386 receiver, and the overhead at the sender is very limited (it is 1387 just a third kind of jump, at one byte per jump). Beyond 42, 1388 senders can ignore the existence of fenceposts if they want 1389 (possibly obviating the need for more complex base-14 arithmetic). 1391 There is no need for a finer granularity than 8, as the Option 1392 construct following can also specify a Delta of 0..14. (A 1393 granularity of 16 will require additional fenceposting where an 1394 option delta of 15 would happen to be required otherwise, which we 1395 have reserved. It can be argued that 16 is still the better choice, 1396 as fenceposting is already in the code path.) 1398 The Long Jump construct takes 0xf1 and 0xf2 from the space available 1399 for initial bytes of Options. (Note that we previously took 0xf0 to 1400 indicate end-of-options for OC=15.) 1402 Varying N with the length as defined above makes it unambiguous 1403 whether a one- or two-byte Long Jump is to be used. Setting N=2 for 1404 the one-byte version makes it clear that a Delta of 8 is to be 1405 handled the usual way (i.e., by Option Delta itself and/or 1406 fenceposting). If the delta is not small and not 7 modulo 8, there 1407 is still a choice between using the smaller multiple of 8 and a 1408 larger Delta in the actual Option or v.v., this biases the choice 1409 towards a larger Long Jump and a smaller following Delta, which is 1410 also easier to implement as it reduces the number of choice points. 1412 B.2.2.3. Example 1414 The following sequence of bytes would encode a Uri-Path Option of 1415 "foo" followed by Options 1357 (value "bar") and 1360 (value "baz"): 1417 93 65 6f 6f Option 9 (0 + 9, "foo") 1418 f1 a6 Long Jump by 1344 1419 43 62 61 72 Option 1357 (9 + 1344 + 4, "bar") 1420 33 62 61 7a Option 1360 (1357 + 3, "baz") 1422 Figure 17: Example using a Long Jump construct 1424 where f1 a6 is the long jump forward by (0xa6+2)*8=1344 option 1425 numbers. The total option count (OC) for the CoAP header is 3. Note 1426 that even if f1 a6 is skipped, the 1357 (which then appears as an 1427 Option number 13) is clearly visible as Critical. 1429 B.2.2.4. IANA considerations 1431 With the scheme proposed above, we could have three tiers of Option 1432 Numbers, differing in their allocation policy [RFC5226]: 1434 +---------------+-------------------------+ 1435 | Option Number | Policy | 1436 +---------------+-------------------------+ 1437 | 0..255 | Standards Action | 1438 | | | 1439 | 256..2047 | Designated Expert | 1440 | | | 1441 | 2048..65535 | First Come First Served | 1442 +---------------+-------------------------+ 1444 For the inventor of a new option, this would provide a small 1445 incentive to go through the designated expert for some minimal cross- 1446 checking in order to be able to use the two-byte long-jump. 1448 This draft adds option numbers to Table 2 of [I-D.ietf-core-coap]: 1450 +--------+---------------------+-----------+ 1451 | Number | Name | Reference | 1452 +--------+---------------------+-----------+ 1453 | 14 | Registered-Elective | [RFCXXXX] | 1454 | | | | 1455 | 25 | Registered-Critical | [RFCXXXX] | 1456 +--------+---------------------+-----------+ 1458 Table 1: New CoAP Option Numbers 1460 This draft adds a suboption registry, initially empty. 1462 +------------+-----------------------------+-----------+ 1463 | Number | Name | Reference | 1464 +------------+-----------------------------+-----------+ 1465 | 0..127 | (allocate on export review) | [RFCXXXX] | 1466 | | | | 1467 | 128..16383 | (allocate fcfs) | [RFCXXXX] | 1468 +------------+-----------------------------+-----------+ 1470 Table 2: CoAP Suboption Numbers 1472 B.3. Enabling Protocol Evolution 1474 To enable a protocol to evolve, it is critical that new capabilities 1475 can be introduced without requiring changes in components that don't 1476 really care about the capability. One such probem is exhibited by 1477 CoAP options: If a proxy does not understand an elective option in a 1478 request, it will not be able to forward it to the origin server, 1479 rendering the new option ineffectual. Worse, if a proxy does not 1480 understand a critical option in a request, it will not be able to 1481 operate on the request, rendering the new option damaging. 1483 As a conclusion to the Ticket #230 discussion in the June 4th interim 1484 call, we decided to solve the identification of options that a proxy 1485 can safely forward even if not understood (previously called Proxy- 1486 Elective). 1488 The proposal is to encode this information in the option number, just 1489 like the way the information that an option is critical is encoded 1490 now. This leads to two bits with semantics: the lowest bit continues 1491 to be the critical bit, and the next higher bit is now the "unsafe" 1492 bit (i.e., this option is not safe to forward unless understood by 1493 the proxy). 1495 Another consideration (for options that are not unsafe to forward) is 1496 whether the option should serve as a cache key in a request. HTTP 1497 has a vary header that indicates in the response which header fields 1498 were considered by the origin server to be cache keys. In order to 1499 avoid this complexity, we should be able to indicate this information 1500 right in the option number. However, reserving another bit is 1501 wasteful, in particular as there are few safe-to-forward options that 1502 are not cache-keys. 1504 Therefore, we propose the following bit allocation in an option 1505 number: 1507 xxx nnn UC 1509 Figure 18 1511 (where xxx is a variable length prefix, as option numbers are not 1512 bounded upwards). UC is the unsafe and critical bits. For U=0 only, 1513 if nnn is equal to 111 binary, the option does not serve as a cache 1514 key (for U=1, the proxy has to know the option to act on it, so there 1515 is no point in indicating whether it is a cache key). There is no 1516 semantic meaning of xxx. 1518 Note that clients and servers are generally not interested in this 1519 information. A proxy may use an equivalent of the following C code 1520 to derive the characteristics of an option number "onum": 1522 Critical = (onum & 1); 1523 UnSafe = (onum & 2); 1524 NoCache = ((onum & 0x1e) == 0x1c); 1526 Figure 19 1528 Discussion: This requires a renumbering of all options. 1530 This renumbering may also be considered as an opportunity to make 1531 the numbering straight again shortly before nailing down the 1532 protocol 1534 In particular, Content-Type is now probably better considered to 1535 be elective. 1537 B.3.1. Potential new option number allocation 1539 We want to give one example for a revised allocation of option 1540 numbers. Option numbers are given as decimal numbers, one each for 1541 xxx, nnn, and UC, with the UC values as follows 1543 +-----------+------------+------------------------------------+ 1544 | UC binary | UC decimal | meaning | 1545 +-----------+------------+------------------------------------+ 1546 | 00 | 0 | (safe, elective, 111=no-cache-key) | 1547 | | | | 1548 | 01 | 1 | (safe, critical, 111=no-cache-key) | 1549 | | | | 1550 | 10 | 2 | (unsafe, elective) | 1551 | | | | 1552 | 11 | 3 | (unsafe, critical) | 1553 +-----------+------------+------------------------------------+ 1555 The table is: 1557 +-----+-------+---------+-----------------------+-------------------+ 1558 | New | xx | Old | Name | Comment | 1559 | | nnn | | | | 1560 | | UC | | | | 1561 +-----+-------+---------+-----------------------+-------------------+ 1562 | 4 | 0 1 0 | 1 | Content-Type | category change | 1563 | | | | | (elective) | 1564 | | | | | | 1565 | 8 | 0 2 0 | 4 | ETag | | 1566 | | | | | | 1567 | 12 | 0 3 0 | 12 | Accept | | 1568 | | | | | | 1569 | 16 | 0 4 0 | 6 | Location-Path | | 1570 | | | | | | 1571 | 20 | 0 5 0 | 8 | Location-Query | | 1572 | | | | | | 1573 | 24 | 0 6 0 | - | (unused) | | 1574 | | | | | | 1575 | 28 | 0 7 0 | 18 | Size | needs nnn=111 | 1576 | | | | | | 1577 | 32 | 1 0 0 | 20/22 | Patience | | 1578 | | | | | | 1579 | 64 | 2 x 0 | - | Location-reserved | (nnn = 0..3, 4 | 1580 | | | | | reserved numbers) | 1581 | | | | | | 1582 | 1 | 0 0 1 | 13 | If-Match | | 1583 | | | | | | 1584 | 5 | 0 1 1 | 21 | If-None-Match | | 1585 | | | | | | 1586 | 2 | 0 0 2 | 2 | Max-Age | | 1587 | | | | | | 1588 | 6 | 0 1 2 | 10 | Observe | | 1589 | | | | | | 1590 | 10 | 0 2 2 | xx | Observe-2 | | 1591 | | | | | | 1592 | 14 | 0 3 2 | xx | (unused) | was fencepost | 1593 | | | | | | 1594 | 3 | 0 0 3 | 3 | Proxy-Uri | | 1595 | | | | | | 1596 | 7 | 0 1 3 | 5 | Uri-Host | | 1597 | | | | | | 1598 | 11 | 0 2 3 | 7 | Uri-Port | | 1599 | | | | | | 1600 | 15 | 0 3 3 | 9 | Uri-Path | | 1601 | | | | | | 1602 | 19 | 0 4 3 | 15 | Uri-Query | | 1603 | | | | | | 1604 | 23 | 0 5 3 | 11 | Token | | 1605 | | | | | | 1606 | 27 | 0 6 3 | 17 | Block2 | | 1607 | | | | | | 1608 | 31 | 0 7 3 | 19 | Block1 | yes, we can use | 1609 | | | | | nnn=111 with U=1 | 1610 +-----+-------+---------+-----------------------+-------------------+ 1612 B.4. Patience, Leisure, and Pledge 1614 A number of options might be useful for controlling the timing of 1615 interactions. 1617 (This section also addresses core-coap ticket #177.) 1619 B.4.1. Patience 1621 A client may have a limited time period in which it can actually make 1622 use of the response for a request. Using the Patience option, it can 1623 provide an (elective) indication how much time it is willing to wait 1624 for the response from the server, giving the server license to ignore 1625 or reject the request if it cannot fulfill it in this period. 1627 If the server knows early that it cannot fulfill the request in the 1628 time requested, it MAY indicate this with a 5.04 "Timeout" response. 1629 For non-safe methods (such as PUT, POST, DELETE), the server SHOULD 1630 indicate whether it has fulfilled the request by either responding 1631 with 5.04 "Timeout" (and not further processing the request) or by 1632 processing the request normally. 1634 Note that the value of the Patience option should be chosen such that 1635 the client will be able to make use of the result even in the 1636 presence of the expected network delays for the request and the 1637 response. Similarly, when a proxy receives a request with a Patience 1638 option and cannot fulfill that request from its cache, it may want to 1639 adjust the value of the option before forwarding it to an upstream 1640 server. 1642 (TBD: The various cases that arise when combining Patience with 1643 Observe.) 1644 The Patience option is elective. Hence, a client MUST be prepared to 1645 receive a normal response even after the chosen Patience period (plus 1646 an allowance for network delays) has elapsed. 1648 B.4.2. Leisure 1650 Servers generally will compute an internal value that we will call 1651 Leisure, which indicates the period of time that will be used for 1652 responding to a request. A Patience option, if present, can be used 1653 as an upper bound for the Leisure. Leisure may be non-zero for 1654 congestion control reasons, in particular for responses to multicast 1655 requests. For these, the server should have a group size estimate G, 1656 a target rate R (which both should be chosen conservatively) and an 1657 estimated response size S; a rough lower bound for Leisure can then 1658 be computed as follows: 1660 lb_Leisure = S * G / R 1662 Figure 20: Computing a lower bound for the Leisure 1664 E.g., for a multicast request with link-local scope on an 2.4 GHz 1665 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 1666 conservatively) set to 100, S to 100 bytes, and the target rate to 8 1667 kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10 1668 seconds. 1670 To avoid response implosion, responses to multicast requests SHOULD 1671 be dithered within a Leisure period chosen by the server to fall 1672 between these two bounds. 1674 Currently, we don't foresee a need to signal a value for Leisure from 1675 client to server (beyond the signalling provided by Patience) or from 1676 server to client, but an appropriate Option might be added later. 1678 B.4.3. Pledge 1680 In a basic observation relationship [I-D.ietf-core-observe], the 1681 server makes a pledge to keep the client in the observation 1682 relationship for a resource at least until the max-age for the 1683 resource is reached. 1685 To save the client some effort in re-establishing observation 1686 relationships each time max-age is reached, the server MAY want to 1687 extend its pledge beyond the end of max-age by signalling in a 1688 response/notification an additional time period using the Pledge 1689 Option, in parallel to the Observe Option. 1691 The Pledge Option MUST NOT be used unless the server can make a 1692 reasonable promise not to lose the observation relationship in this 1693 time frame. 1695 Currently, we don't foresee a need to signal a value for Pledge from 1696 client to server, but an appropriate behavior might be added later 1697 for this option when sent in a request. 1699 B.4.4. Option Formats 1701 +-----+----------+----------+-----------------+--------+---------+ 1702 | No. | C/E | Name | Format | Length | Default | 1703 +-----+----------+----------+-----------------+--------+---------+ 1704 | 22 | Elective | Patience | Duration in mis | 1 B | (none) | 1705 | | | | | | | 1706 | 24 | Elective | Pledge | Duration in s | 1 B | 0 | 1707 +-----+----------+----------+-----------------+--------+---------+ 1709 All timing options use the Duration data type (see Appendix D.2), 1710 however Patience (and Leisure, if that ever becomes an option) uses a 1711 timebase of mibiseconds (mis = 1/1024 s) instead of seconds. (This 1712 reduces the range of the Duration from ~ 91 days to 128 minutes.) 1714 Implementation note: As there are no strong accuracy requirements on 1715 the clocks employed, making use of any existing time base of 1716 milliseconds is a valid implementation approach (2.4 % off). 1718 None of the options may be repeated. 1720 Appendix C. The Cemetery (Things we won't do) 1722 This annex documents roads that the WG decided not to take, in order 1723 to spare readers from reinventing them in vain. 1725 C.1. Example envelope option: solving #230 1727 Ticket #230 [CoRE230] points out a design flaw of 1728 [I-D.ietf-core-coap]: When we split the elective Location option of 1729 draft -01 into multiple elective options, we made it possible that an 1730 implementation might process some of these and ignore others, leading 1731 to an incorrect interpretation of the Location expressed by the 1732 server. 1734 There are several more or less savory solutions to #230. 1736 Each of the elective options that together make up the Location could 1737 be defined in such a way that it makes a requirement on the 1738 processing of the related option (essentially revoking their elective 1739 status once the option under consideration is actually processed). 1740 This falls flat as soon as another option is defined that would also 1741 become part of the Location: existing implementations would not know 1742 that the new option is also part of the cluster that is re- 1743 interpreted as critical. The potential future addition of Location- 1744 Host and Location-Port makes this a valid consideration. 1746 A better solution would be to define an elective Envelope Option 1747 called Location. Within a Location Option, the following top-level 1748 options might be allowed (now or in the future): 1750 o Uri-Host 1752 o Uri-Port 1754 o Uri-Path 1756 o Uri-Query 1758 This would unify the code for interpreting the top-level request 1759 options that indicate the request URI with the code that interprets 1760 the Location URI. 1762 The four options listed are all critical, while the envelope is 1763 elective. This gives exactly the desired semantics: If the envelope 1764 is processed at all (which is elective), the nested options are 1765 critical and all need to be processed. 1767 C.2. Example envelope option: proxy-elective options 1769 Another potential application of envelope options is motivated by the 1770 observation that new critical options might not be implemented by all 1771 proxies on the CoAP path to an origin server. So that this does not 1772 become an obstacle to introducing new critical options that are of 1773 interest only to client and origin server, the client might want to 1774 mark some critical options proxy-elective, i.e. elective for a proxy 1775 but still critical for the origin server. 1777 One way to do this would be an Envelope option, the Proxy-Elective 1778 Option. A client might bundle a number of critical options into a 1779 critical Proxy-Elective Option. A proxy that processes the message 1780 is obliged to process the envelope (or reject the message), where 1781 processing means passing on the nested options towards the origin 1782 server (preferably again within a Proxy-Elective option). It can 1783 pass on the nested options, even ones unknown to the proxy, knowing 1784 that the client is happy with proxies not processing all of them. 1786 (The assumption here is that the Proxy-Elective option becomes part 1787 of the base standard, so all but the most basic proxies would know 1788 how to handle it.) 1790 C.3. Stateful URI compression 1792 Is the approximately 25 % average saving achievable with Huffman- 1793 based URI compression schemes worth the complexity? Probably not, 1794 because much higher average savings can be achieved by introducing 1795 state. 1797 Henning Schulzrinne has proposed for a server to be able to supply a 1798 shortened URI once a resource has been requested using the full- 1799 length URI. Let's call such a shortened referent a _Temporary 1800 Resource Identifier_, _TeRI_ for short. This could be expressed by a 1801 response option as shown in Figure 21. 1803 0 1804 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 1805 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1806 | duration | TeRI... 1807 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1809 Figure 21: Option for offering a TeRI in a response 1811 The TeRI offer option indicates that the server promises to offer 1812 this resources under the TeRI given for at least the time given as 1813 the duration. Another TeRI offer can be made later to extend the 1814 duration. 1816 Once a TeRI for a URI is known (and still within its lifetime), the 1817 client can supply a TeRI instead of a URI in its requests. The same 1818 option format as an offer could be used to allow the client to 1819 indicate how long it believes the TeRI will still be valid (so that 1820 the server can decide when to update the lifetime duration). TeRIs 1821 in requests could be distinguished from URIs e.g. by using a 1822 different option number. 1824 Proposal: Add a TeRI option that can be used in CoAP requests and 1825 responses. 1827 Add a way to indicate a TeRI and its duration in a link-value. 1829 Do not add any form of stateless URI encoding. 1831 Benefits: Much higher reduction of message size than any stateless 1832 URI encoding could achieve. 1834 As the use of TeRIs is entirely optional, minimal complexity nodes 1835 can get by without implementing them. 1837 Drawbacks: Adds considerable state and complexity to the protocol. 1839 It turns out that real CoAP URIs are short enough that TeRIs are 1840 not needed. 1842 (Discuss the security implications of TeRIs.) 1844 Appendix D. Experimental Options 1846 This annex documents proposals that need significant additional 1847 discussion before they can become part of (or go back to) the main 1848 CoAP specification. They are not dead, but might die if there turns 1849 out to be no good way to solve the problem. 1851 D.1. Options indicating absolute time 1853 HTTP has a number of headers that may indicate absolute time: 1855 o "Date", defined in Section 14.18 in [RFC2616] (Section 9.3 in 1856 [I-D.ietf-httpbis-p1-messaging]), giving the absolute time a 1857 response was generated; 1859 o "Last-Modified", defined in Section 14.29 in [RFC2616], 1860 (Section 6.6 in [I-D.ietf-httpbis-p4-conditional], giving the 1861 absolute time of when the origin server believes the resource 1862 representation was last modified; 1864 o "If-Modified-Since", defined in Section 14.25 in [RFC2616], "If- 1865 Unmodified-Since", defined in Section 14.28 in [RFC2616], and "If- 1866 Range", defined in Section 14.27 in [RFC2616] can be used to 1867 supply absolute time to gate a conditional request; 1869 o "Expires", defined in Section 14.21 in [RFC2616] (Section 3.3 in 1870 [I-D.ietf-httpbis-p6-cache]), giving the absolute time after which 1871 a response is considered stale. 1873 o The more obscure headers "Retry-After", defined in Section 14.37 1874 in [RFC2616], and "Warning", defined in section 14.46 in 1875 [RFC2616], also may employ absolute time. 1877 [I-D.ietf-core-coap] defines a single "Date" option, which however 1878 "indicates the creation time and date of a given resource 1879 representation", i.e., is closer to a "Last-Modified" HTTP header. 1880 HTTP's caching rules [I-D.ietf-httpbis-p6-cache] make use of both 1881 "Date" and "Last-Modified", combined with "Expires". The specific 1882 semantics required for CoAP needs further consideration. 1884 In addition to the definition of the semantics, an encoding for 1885 absolute times needs to be specified. 1887 In UNIX-related systems, it is customary to indicate absolute time as 1888 an integer number of seconds, after midnight UTC, January 1, 1970. 1889 Unless negative numbers are employed, this time format cannot 1890 represent time values prior to January 1, 1970, which probably is not 1891 required for the uses ob absolute time in CoAP. 1893 If a 32-bit integer is used and allowance is made for a sign-bit in a 1894 local implementation, the latest UTC time value that can be 1895 represented by the resulting 31 bit integer value is 03:14:07 on 1896 January 19, 2038. If the 32-bit integer is used as an unsigned 1897 value, the last date is 2106-02-07, 06:28:15. 1899 The reach can be extended by: - moving the epoch forward, e.g. by 40 1900 years (= 1262304000 seconds) to 2010-01-01. This makes it impossible 1901 to represent Last-Modified times in that past (such as could be 1902 gatewayed in from HTTP). - extending the number of bits, e.g. by 1903 one more byte, either always or as one of two formats, keeping the 1904 32-bit variant as well. 1906 Also, the resolution can be extended by expressing time in 1907 milliseconds etc., requiring even more bits (e.g., a 48-bit unsigned 1908 integer of milliseconds would last well after year 9999.) 1910 For experiments, an experimental "Date" option is defined with the 1911 semantics of HTTP's "Last-Modified". It can carry an unsigned 1912 integer of 32, 40, or 48 bits; 32- and 40-bit integers indicate the 1913 absolute time in seconds since 1970-01-01 00:00 UTC, while 48-bit 1914 integers indicate the absolute time in milliseconds since 1970-01-01 1915 00:00 UTC. 1917 However, that option is not really that useful until there is a "If- 1918 Modified-Since" option as well. 1920 (Also: Discuss nodes without clocks.) 1922 D.2. Representing Durations 1923 Various message types used in CoAP need the representation of 1924 *durations*, i.e. of the length of a timespan. In SI units, these 1925 are measured in seconds. CoAP durations represent integer numbers of 1926 seconds, but instead of representing these numbers as integers, a 1927 more compact single-byte pseudo-floating-point (pseudo-FP) 1928 representation is used (Figure 22). 1930 0 1 2 3 4 5 6 7 1931 +---+---+---+---+---+---+---+---+ 1932 | 0... value | 1933 +---+---+---+---+---+---+---+---+ 1935 +---+---+---+---+---+---+---+---+ 1936 | 1... mantissa | exponent | 1937 +---+---+---+---+---+---+---+---+ 1939 Figure 22: Duration in (8,4) pseudo-FP representation 1941 If the high bit is clear, the entire n-bit value (including the high 1942 bit) is the decoded value. If the high bit is set, the mantissa 1943 (including the high bit, with the exponent field cleared out but 1944 still present) is shifted left by the exponent to yield the decoded 1945 value. 1947 The (n,e)-pseudo-FP format can be decoded with a single line of code 1948 (plus a couple of constant definitions), as demonstrated in Figure 1949 23. 1951 #define N 8 1952 #define E 4 1953 #define HIBIT (1 << (N - 1)) 1954 #define EMASK ((1 << E) - 1) 1955 #define MMASK ((1 << N) - 1 - EMASK) 1957 #define DECODE_8_4(r) (r < HIBIT ? r : (r & MMASK) << (r & EMASK)) 1959 Figure 23: Decoding an (8,4) pseudo-FP value 1961 Note that a pseudo-FP encoder needs to consider rounding; different 1962 applications of durations may favor rounding up or rounding down the 1963 value encoded in the message. 1965 The highest pseudo-FP value, represented by an all-ones byte (0xFF), 1966 is reserved to indicate an indefinite duration. The next lower value 1967 (0xEF) is thus the highest representable value and is decoded as 1968 7340032 seconds, a little more than 12 weeks. 1970 D.3. Rationale 1972 Where CPU power and memory is abundant, a duration can almost always 1973 be adequately represented by a non-negative floating-point number 1974 representing that number of seconds. Historically, many APIs have 1975 also used an integer representation, which limits both the resolution 1976 (e.g., if the integer represents the duration in seconds) and often 1977 the range (integer machine types have range limits that may become 1978 relevant). UNIX's "time_t" (which is used for both absolute time and 1979 durations) originally was a signed 32-bit value of seconds, but was 1980 later complemented by an additional integer to add microsecond 1981 ("struct timeval") and then later nanosecond ("struct timespec") 1982 resolution. 1984 Three decisions need to be made for each application of the concept 1985 of duration: 1987 o the *resolution*. What rounding error is acceptable? 1989 o the *range*. What is the maximum duration that needs to be 1990 represented? 1992 o the *number of bits* that can be expended. 1994 Obviously, these decisions are interrelated. Typically, a large 1995 range needs a large number of bits, unless resolution is traded. For 1996 most applications, the actual requirement for resolution are limited 1997 for longer durations, but can be more acute for shorter durations. 1999 D.4. Pseudo-Floating Point 2001 Constrained systems typically avoid the use of floating-point (FP) 2002 values, as 2004 o simple CPUs often don't have support for floating-point datatypes 2006 o software floating-point libraries are expensive in code size and 2007 slow. 2009 In addition, floating-point datatypes used to be a significant 2010 element of market differentiation in CPU design; it has taken the 2011 industry a long time to agree on a standard floating point 2012 representation. 2014 These issues have led to protocols that try to constrain themselves 2015 to integer representation even where the ability of a floating point 2016 representation to trade range for resolution would be beneficial. 2018 The idea of introducing _pseudo-FP_ is to obtain the increased range 2019 provided by embedding an exponent, without necessarily getting stuck 2020 with hardware datatypes or inefficient software floating-point 2021 libraries. 2023 For the purposes of this draft, we define an (n,e)-pseudo-FP as a 2024 fixed-length value of n bits, e of which may be used for an exponent. 2025 Figure 22 illustrates an (8,4)-pseudo-FP value. 2027 If the high bit is clear, the entire n-bit value (including the high 2028 bit) is the decoded value. If the high bit is set, the mantissa 2029 (including the high bit, but with the exponent field cleared out) is 2030 shifted left by the exponent to yield the decoded value. 2032 The (n,e)-pseudo-FP format can be decoded with a single line of code 2033 (plus a couple of constant definition), as demonstrated in Figure 23. 2035 Only non-negative numbers can be represented by this format. It is 2036 designed to provide full integer resolution for values from 0 to 2037 2^(n-1)-1, i.e., 0 to 127 in the (8,4) case, and a mantissa of n-e 2038 bits from 2^(n-1) to (2^n-2^e)*2^(2^e-1), i.e., 128 to 7864320 in the 2039 (8,4) case. By choosing e carefully, resolution can be traded 2040 against range. 2042 Note that a pseudo-FP encoder needs to consider rounding; different 2043 applications of durations may favor rounding up or rounding down the 2044 value encoded in the message. This requires a little more than a 2045 single line of code (which is left as an exercise to the reader, as 2046 the most efficient expression depends on hardware details). 2048 D.5. A Duration Type for CoAP 2050 CoAP needs durations in a number of places. In [I-D.ietf-core-coap], 2051 durations occur in the option "Subscription-lifetime" as well as in 2052 the option "Max-age". (Note that the option "Date" is not a 2053 duration, but a point in time.) Other durations of this kind may be 2054 added later. 2056 Most durations relevant to CoAP are best expressed with a minimum 2057 resolution of one second. More detailed resolutions are unlikely to 2058 provide much benefit. 2060 The range of lifetimes and caching ages are probably best kept below 2061 the order of magnitude of months. An (8,4)-pseudo-FP has the maximum 2062 value of 7864320, which is about 91 days; this appears to be adequate 2063 for a subscription lifetime and probably even for a maximum cache 2064 age. Figure 24 shows the values that can be expressed. (If a larger 2065 range for the latter is indeed desired, an (8,5)-pseudo-FP could be 2066 used; this would last 15 milleniums, at the cost of having only 3 2067 bits of accuracy for values larger than 127 seconds.) 2069 Proposal: A single duration type is used throughout CoAP, based on 2070 an (8,4)-pseudo-FP giving a duration in seconds. 2072 Benefits: Implementations can use a single piece of code for 2073 managing all CoAP-related durations. 2075 In addition, length information never needs to be managed for 2076 durations that are embedded in other data structures: All 2077 durations are expressed by a single byte. 2079 It might be worthwhile to reserve one duration value, e.g. 0xFF, for 2080 an indefinite duration. 2082 Duration Seconds Encoded 2083 ----------- ---------- ------- 2084 00:00:00 0x00000000 0x00 2085 00:00:01 0x00000001 0x01 2086 00:00:02 0x00000002 0x02 2087 00:00:03 0x00000003 0x03 2088 00:00:04 0x00000004 0x04 2089 00:00:05 0x00000005 0x05 2090 00:00:06 0x00000006 0x06 2091 00:00:07 0x00000007 0x07 2092 00:00:08 0x00000008 0x08 2093 00:00:09 0x00000009 0x09 2094 00:00:10 0x0000000a 0x0a 2095 00:00:11 0x0000000b 0x0b 2096 00:00:12 0x0000000c 0x0c 2097 00:00:13 0x0000000d 0x0d 2098 00:00:14 0x0000000e 0x0e 2099 00:00:15 0x0000000f 0x0f 2100 00:00:16 0x00000010 0x10 2101 00:00:17 0x00000011 0x11 2102 00:00:18 0x00000012 0x12 2103 00:00:19 0x00000013 0x13 2104 00:00:20 0x00000014 0x14 2105 00:00:21 0x00000015 0x15 2106 00:00:22 0x00000016 0x16 2107 00:00:23 0x00000017 0x17 2108 00:00:24 0x00000018 0x18 2109 00:00:25 0x00000019 0x19 2110 00:00:26 0x0000001a 0x1a 2111 00:00:27 0x0000001b 0x1b 2112 00:00:28 0x0000001c 0x1c 2113 00:00:29 0x0000001d 0x1d 2114 00:00:30 0x0000001e 0x1e 2115 00:00:31 0x0000001f 0x1f 2116 00:00:32 0x00000020 0x20 2117 00:00:33 0x00000021 0x21 2118 00:00:34 0x00000022 0x22 2119 00:00:35 0x00000023 0x23 2120 00:00:36 0x00000024 0x24 2121 00:00:37 0x00000025 0x25 2122 00:00:38 0x00000026 0x26 2123 00:00:39 0x00000027 0x27 2124 00:00:40 0x00000028 0x28 2125 00:00:41 0x00000029 0x29 2126 00:00:42 0x0000002a 0x2a 2127 00:00:43 0x0000002b 0x2b 2128 00:00:44 0x0000002c 0x2c 2129 00:00:45 0x0000002d 0x2d 2130 00:00:46 0x0000002e 0x2e 2131 00:00:47 0x0000002f 0x2f 2132 00:00:48 0x00000030 0x30 2133 00:00:49 0x00000031 0x31 2134 00:00:50 0x00000032 0x32 2135 00:00:51 0x00000033 0x33 2136 00:00:52 0x00000034 0x34 2137 00:00:53 0x00000035 0x35 2138 00:00:54 0x00000036 0x36 2139 00:00:55 0x00000037 0x37 2140 00:00:56 0x00000038 0x38 2141 00:00:57 0x00000039 0x39 2142 00:00:58 0x0000003a 0x3a 2143 00:00:59 0x0000003b 0x3b 2144 00:01:00 0x0000003c 0x3c 2145 00:01:01 0x0000003d 0x3d 2146 00:01:02 0x0000003e 0x3e 2147 00:01:03 0x0000003f 0x3f 2148 00:01:04 0x00000040 0x40 2149 00:01:05 0x00000041 0x41 2150 00:01:06 0x00000042 0x42 2151 00:01:07 0x00000043 0x43 2152 00:01:08 0x00000044 0x44 2153 00:01:09 0x00000045 0x45 2154 00:01:10 0x00000046 0x46 2155 00:01:11 0x00000047 0x47 2156 00:01:12 0x00000048 0x48 2157 00:01:13 0x00000049 0x49 2158 00:01:14 0x0000004a 0x4a 2159 00:01:15 0x0000004b 0x4b 2160 00:01:16 0x0000004c 0x4c 2161 00:01:17 0x0000004d 0x4d 2162 00:01:18 0x0000004e 0x4e 2163 00:01:19 0x0000004f 0x4f 2164 00:01:20 0x00000050 0x50 2165 00:01:21 0x00000051 0x51 2166 00:01:22 0x00000052 0x52 2167 00:01:23 0x00000053 0x53 2168 00:01:24 0x00000054 0x54 2169 00:01:25 0x00000055 0x55 2170 00:01:26 0x00000056 0x56 2171 00:01:27 0x00000057 0x57 2172 00:01:28 0x00000058 0x58 2173 00:01:29 0x00000059 0x59 2174 00:01:30 0x0000005a 0x5a 2175 00:01:31 0x0000005b 0x5b 2176 00:01:32 0x0000005c 0x5c 2177 00:01:33 0x0000005d 0x5d 2178 00:01:34 0x0000005e 0x5e 2179 00:01:35 0x0000005f 0x5f 2180 00:01:36 0x00000060 0x60 2181 00:01:37 0x00000061 0x61 2182 00:01:38 0x00000062 0x62 2183 00:01:39 0x00000063 0x63 2184 00:01:40 0x00000064 0x64 2185 00:01:41 0x00000065 0x65 2186 00:01:42 0x00000066 0x66 2187 00:01:43 0x00000067 0x67 2188 00:01:44 0x00000068 0x68 2189 00:01:45 0x00000069 0x69 2190 00:01:46 0x0000006a 0x6a 2191 00:01:47 0x0000006b 0x6b 2192 00:01:48 0x0000006c 0x6c 2193 00:01:49 0x0000006d 0x6d 2194 00:01:50 0x0000006e 0x6e 2195 00:01:51 0x0000006f 0x6f 2196 00:01:52 0x00000070 0x70 2197 00:01:53 0x00000071 0x71 2198 00:01:54 0x00000072 0x72 2199 00:01:55 0x00000073 0x73 2200 00:01:56 0x00000074 0x74 2201 00:01:57 0x00000075 0x75 2202 00:01:58 0x00000076 0x76 2203 00:01:59 0x00000077 0x77 2204 00:02:00 0x00000078 0x78 2205 00:02:01 0x00000079 0x79 2206 00:02:02 0x0000007a 0x7a 2207 00:02:03 0x0000007b 0x7b 2208 00:02:04 0x0000007c 0x7c 2209 00:02:05 0x0000007d 0x7d 2210 00:02:06 0x0000007e 0x7e 2211 00:02:07 0x0000007f 0x7f 2212 00:02:08 0x00000080 0x80 2213 00:02:24 0x00000090 0x90 2214 00:02:40 0x000000a0 0xa0 2215 00:02:56 0x000000b0 0xb0 2216 00:03:12 0x000000c0 0xc0 2217 00:03:28 0x000000d0 0xd0 2218 00:03:44 0x000000e0 0xe0 2219 00:04:00 0x000000f0 0xf0 2220 00:04:16 0x00000100 0x81 2221 00:04:48 0x00000120 0x91 2222 00:05:20 0x00000140 0xa1 2223 00:05:52 0x00000160 0xb1 2224 00:06:24 0x00000180 0xc1 2225 00:06:56 0x000001a0 0xd1 2226 00:07:28 0x000001c0 0xe1 2227 00:08:00 0x000001e0 0xf1 2228 00:08:32 0x00000200 0x82 2229 00:09:36 0x00000240 0x92 2230 00:10:40 0x00000280 0xa2 2231 00:11:44 0x000002c0 0xb2 2232 00:12:48 0x00000300 0xc2 2233 00:13:52 0x00000340 0xd2 2234 00:14:56 0x00000380 0xe2 2235 00:16:00 0x000003c0 0xf2 2236 00:17:04 0x00000400 0x83 2237 00:19:12 0x00000480 0x93 2238 00:21:20 0x00000500 0xa3 2239 00:23:28 0x00000580 0xb3 2240 00:25:36 0x00000600 0xc3 2241 00:27:44 0x00000680 0xd3 2242 00:29:52 0x00000700 0xe3 2243 00:32:00 0x00000780 0xf3 2244 00:34:08 0x00000800 0x84 2245 00:38:24 0x00000900 0x94 2246 00:42:40 0x00000a00 0xa4 2247 00:46:56 0x00000b00 0xb4 2248 00:51:12 0x00000c00 0xc4 2249 00:55:28 0x00000d00 0xd4 2250 00:59:44 0x00000e00 0xe4 2251 01:04:00 0x00000f00 0xf4 2252 01:08:16 0x00001000 0x85 2253 01:16:48 0x00001200 0x95 2254 01:25:20 0x00001400 0xa5 2255 01:33:52 0x00001600 0xb5 2256 01:42:24 0x00001800 0xc5 2257 01:50:56 0x00001a00 0xd5 2258 01:59:28 0x00001c00 0xe5 2259 02:08:00 0x00001e00 0xf5 2260 02:16:32 0x00002000 0x86 2261 02:33:36 0x00002400 0x96 2262 02:50:40 0x00002800 0xa6 2263 03:07:44 0x00002c00 0xb6 2264 03:24:48 0x00003000 0xc6 2265 03:41:52 0x00003400 0xd6 2266 03:58:56 0x00003800 0xe6 2267 04:16:00 0x00003c00 0xf6 2268 04:33:04 0x00004000 0x87 2269 05:07:12 0x00004800 0x97 2270 05:41:20 0x00005000 0xa7 2271 06:15:28 0x00005800 0xb7 2272 06:49:36 0x00006000 0xc7 2273 07:23:44 0x00006800 0xd7 2274 07:57:52 0x00007000 0xe7 2275 08:32:00 0x00007800 0xf7 2276 09:06:08 0x00008000 0x88 2277 10:14:24 0x00009000 0x98 2278 11:22:40 0x0000a000 0xa8 2279 12:30:56 0x0000b000 0xb8 2280 13:39:12 0x0000c000 0xc8 2281 14:47:28 0x0000d000 0xd8 2282 15:55:44 0x0000e000 0xe8 2283 17:04:00 0x0000f000 0xf8 2284 18:12:16 0x00010000 0x89 2285 20:28:48 0x00012000 0x99 2286 22:45:20 0x00014000 0xa9 2287 1d 01:01:52 0x00016000 0xb9 2288 1d 03:18:24 0x00018000 0xc9 2289 1d 05:34:56 0x0001a000 0xd9 2290 1d 07:51:28 0x0001c000 0xe9 2291 1d 10:08:00 0x0001e000 0xf9 2292 1d 12:24:32 0x00020000 0x8a 2293 1d 16:57:36 0x00024000 0x9a 2294 1d 21:30:40 0x00028000 0xaa 2295 2d 02:03:44 0x0002c000 0xba 2296 2d 06:36:48 0x00030000 0xca 2297 2d 11:09:52 0x00034000 0xda 2298 2d 15:42:56 0x00038000 0xea 2299 2d 20:16:00 0x0003c000 0xfa 2300 3d 00:49:04 0x00040000 0x8b 2301 3d 09:55:12 0x00048000 0x9b 2302 3d 19:01:20 0x00050000 0xab 2303 4d 04:07:28 0x00058000 0xbb 2304 4d 13:13:36 0x00060000 0xcb 2305 4d 22:19:44 0x00068000 0xdb 2306 5d 07:25:52 0x00070000 0xeb 2307 5d 16:32:00 0x00078000 0xfb 2308 6d 01:38:08 0x00080000 0x8c 2309 6d 19:50:24 0x00090000 0x9c 2310 7d 14:02:40 0x000a0000 0xac 2311 8d 08:14:56 0x000b0000 0xbc 2312 9d 02:27:12 0x000c0000 0xcc 2313 9d 20:39:28 0x000d0000 0xdc 2314 10d 14:51:44 0x000e0000 0xec 2315 11d 09:04:00 0x000f0000 0xfc 2316 12d 03:16:16 0x00100000 0x8d 2317 13d 15:40:48 0x00120000 0x9d 2318 15d 04:05:20 0x00140000 0xad 2319 16d 16:29:52 0x00160000 0xbd 2320 18d 04:54:24 0x00180000 0xcd 2321 19d 17:18:56 0x001a0000 0xdd 2322 21d 05:43:28 0x001c0000 0xed 2323 22d 18:08:00 0x001e0000 0xfd 2324 24d 06:32:32 0x00200000 0x8e 2325 27d 07:21:36 0x00240000 0x9e 2326 30d 08:10:40 0x00280000 0xae 2327 33d 08:59:44 0x002c0000 0xbe 2328 36d 09:48:48 0x00300000 0xce 2329 39d 10:37:52 0x00340000 0xde 2330 42d 11:26:56 0x00380000 0xee 2331 45d 12:16:00 0x003c0000 0xfe 2332 48d 13:05:04 0x00400000 0x8f 2333 54d 14:43:12 0x00480000 0x9f 2334 60d 16:21:20 0x00500000 0xaf 2335 66d 17:59:28 0x00580000 0xbf 2336 72d 19:37:36 0x00600000 0xcf 2337 78d 21:15:44 0x00680000 0xdf 2338 84d 22:53:52 0x00700000 0xef 2339 91d 00:32:00 0x00780000 0xff (reserved) 2341 Figure 24 2343 D.6. CONTOUR (CoAP Non-trivial Option Useful Representation) 2345 So far, CoAP options have been simple. For non-trivial options of 2346 the future, e.g. for interaction with cellular systems, it is useful 2347 to have an option value encoding that can represent tree-structured 2348 data. Several such data structures are good candidates. If none of 2349 them work out, the CBOR encoding below may be useful. 2351 The term "byte" is used in its now customary sense as a synonym for 2352 "octet". All multi-byte values are encoded in network byte order. 2353 Where bit arithmetic or data types are explained, this document uses 2354 the notation familiar from the programming language C, except that 2355 the operator "**" stands for exponentiation. 2357 D.6.1. Objectives 2359 (The current text needs some editing because it says everything two 2360 or three times. Right now, we err on the side of redundancy. TBD.) 2362 The objectives of the Concise Binary Object Representation (CBOR), 2363 roughly in decreasing order of importance, are: 2365 1. The representation must be able to unambiguously encode most 2366 common data formats used in Internet standards. 2368 * Representing a reasonable set of basic data types and 2369 structures using binary encoding. "Reasonable" here is 2370 largely influenced by the capabilities of JSON, with the major 2371 addition of binary byte strings. The structures supported are 2372 limited to trees; no loops or lattice-style graphs. 2374 * There is no requirement that all data formats be uniquely 2375 encoded; that is, it is acceptable that the number 7 might be 2376 encoded in multiple different ways. 2378 2. The code for an encoder or parser must be able to be compact in 2379 order to support systems with very limited memory and processor 2380 power and instruction sets. 2382 * Being implementable in a very small amount of code, thus being 2383 applicable to constrained nodes [I-D.ietf-lwig-terminology], 2384 even of class 1. (Complexity goal.) 2386 * As a corollary: Being close to contemporary machine 2387 representations of data (e.g., not requiring binary-to-decimal 2388 conversion). 2390 3. A data stream must be able to be parsed without a schema 2391 description. 2393 4. The serialization must be compact, but data compactness is 2394 secondary to code compactness for the encoder or parser. 2396 * Being reasonably compact: "Reasonable" here is bounded by JSON 2397 as an upper bound in size, and by implementation complexity 2398 maintaining a lower bound. The use of general compression 2399 schemes and/or extensive bit-fiddling violates both of the 2400 complexity goals. 2402 5. Applicable to both constrained nodes and high-volume 2403 applications. 2405 * Being reasonably frugal in CPU usage. (The other complexity 2406 goal.) This is relevant both for constrained nodes and for 2407 potential usage in high-volume applications. 2409 6. The format must support all JSON data types for conversion to and 2410 from JSON. 2412 * Supporting a reasonable level of round-tripping with JSON, as 2413 long as the data represented are within the capabilities of 2414 JSON. Defining a unidirectional mapping towards JSON for all 2415 types of data. 2417 7. Evolvability: The format must be designed for decades. 2419 * The format must support optional tagging of items so that a 2420 parser that does not understand an optional tag can still 2421 parse the message. 2423 * The format must be able to be extended in the future by later 2424 IETF standards. 2426 D.6.2. Specification of the CBOR Encoding 2428 A CBOR encoded data item is structured and encoded as described in 2429 this section. For the impatient reader, the encoding is summarized 2430 in Table 3 at the end of this section. 2432 The encoding of each data item consists of one initial byte that 2433 might be followed by additional bytes for length and/or content 2434 information. The initial byte contains both information about the 2435 major type (the high-order 3 bits) and additional information (the 2436 low-order 5 bits); the additional information might be actual data or 2437 length information, depending on the major type. There may also be 2438 other bytes beyond the initial bytes. 2440 A CBOR parser implementation can be based on the jump table with all 2441 256 defined values (Table 3). A parser in a constrained 2442 implementation can instead use the structure of the initial byte and 2443 following bytes for more compact code. 2445 The following list shows the major types and the additional 2446 information and other bytes associated with the type. 2448 Major type 0b000: an unsigned integer. The 5-bit additional 2449 information is either the integer itself (for additional 2450 information values 0b00000 through 0b11011), or the length of 2451 additional data. Additional information 0b11100 means the value 2452 is represented in an additional uint8_t, 0b11101 means a uint16_t, 2453 0b11110 means a uint32_t, and 0b11111 means a uint64_t. For 2454 example, the integer 10 is denoted as the one byte 0b00001010; the 2455 integer 500 would be 0b00011101 followed by the two bytes 0x01f4. 2457 Major type 0b001: a negative integer. The encoding follows the 2458 rules for unsigned integers (major type 0b000), except that the 2459 value is then -1 minus the encoded unsigned integer. 2461 Major type 0b010: a small number of various types of data which fit 2462 in exactly 0, 1, 2, 4, or 8 bytes of additional data. See 2463 Appendix D.6.2.1. 2465 Major type 0b011: optional semantic tagging of other major types, as 2466 defined in Appendix D.6.3.1. The initial bytes of the tag follow 2467 the rules for positive integers (major type 0b000). The tag is 2468 followed by a single data item of any type except another tag; 2469 that is, the data item that follows the semantic tagging can have 2470 any major type other than 0b011. Understanding the semantic tags 2471 is optional for a parser; it can just jump over the initial bytes 2472 of the tag and interpret the tagged data item itself. 2474 Major type 0b100: a byte string. The string's length in memory is 2475 represented following the rules for positive integers (major type 2476 0b000). For example, a byte string whose length is 5 would have 2477 an initial byte of 0b10000101 followed by 5 bytes of binary 2478 content; a byte string whose length is 500 would have 3 initial 2479 bytes of 0b10011101 followed by the two bytes 0x01f4, then 2480 followed by 500 bytes of binary content. 2482 Major type 0b101: string of Unicode characters that is encoded as 2483 UTF-8. The format of this type is identical to that of byte 2484 strings (major type 0b100). This type is provided for systems 2485 that need to interpret or display human-readable text. 2487 Major type 0b110: an array of data items. The array's length 2488 follows the rules for byte strings (major type 0b100), except that 2489 the length denotes the number of data items, not the length in 2490 memory that the array takes up. For example, an array that 2491 contains 10 items of any type would have an initial byte of 2492 0b11001010 followed by the remaining items. 2494 Major type 0b111: a map of pairs of data items. The map's length 2495 follows the rules for byte strings (major type 0b100), except that 2496 the length denotes the number of pairs, not the length in memory 2497 that the map takes up. 2499 This leads to a simple table showing which of the 256 possible values 2500 for the initial byte of a data item are used for what (Table 3). 2502 +----------------+--------------------------------------------------+ 2503 | Byte | Structure/Semantics | 2504 +----------------+--------------------------------------------------+ 2505 | 0x00..0x1b | Integer 0x00..0x1b (0..27) | 2506 | | | 2507 | 0x1c | Unsigned integer (one-byte uint8_t follows) | 2508 | | | 2509 | 0x1d | Unsigned integer (two-byte uint16_t follows) | 2510 | | | 2511 | 0x1e | Unsigned integer (four-byte uint32_t follows) | 2512 | | | 2513 | 0x1f | Unsigned integer (eight-byte uint64_t follows) | 2514 | | | 2515 | 0x20..0x3b | Negative Integer -1-0x00..-1-0x1b (-1..-28) | 2516 | | | 2517 | 0x3c | Negative Integer -1-n (one-byte uint8_t for n | 2518 | | follows) | 2519 | | | 2520 | 0x3d | Negative integer -1-n (two-byte uint16_t for n | 2521 | | follows) | 2522 | | | 2523 | 0x3e | Negative integer -1-n (four-byte uint32_t for n | 2524 | | follows) | 2525 | | | 2526 | 0x3f | Negative integer -1-n (eight-byte uint64_t for n | 2527 | | follows) | 2528 | | | 2529 | 0x58 | False | 2530 | | | 2531 | 0x59 | True | 2532 | | | 2533 | 0x5a | Null | 2534 | | | 2535 | 0x5b | Undefined | 2536 | | | 2537 | 0x5d | Half-Precision Float (two-byte IEEE 754) | 2538 | | | 2539 | 0x5e | Single-Precision Float (four-byte IEEE 754) | 2540 | | | 2541 | 0x5f | Double-Precision Float (eight-byte IEEE 754) | 2542 | | | 2543 | 0x60..0x67 | Bit String with 0..7 bits padding in last byte | 2544 | | (data item "byte string" follows) | 2545 | | | 2546 | 0x68 | positive bignum (data item "byte string" | 2547 | | follows) | 2548 | | | 2549 | 0x69 | negative bignum (data item "byte string" | 2550 | | follows) | 2551 | | | 2552 | 0x71 | date/time (data item follows, see Appendix | 2553 | | D.6.3.1.3) | 2554 | | | 2555 | 0x72 | base64url (data item "byte string" follows) | 2556 | | | 2557 | 0x73 | base64 (data item "byte string" follows) | 2558 | | | 2559 | 0x74 | base32 (data item "byte string" follows) | 2560 | | | 2561 | 0x75 | base32hex (data item "byte string" follows) | 2562 | | | 2563 | 0x76 | base16 (data item "byte string" follows) | 2564 | | | 2565 | 0x80..0x9b | byte string (0x00..0x1b bytes follow) | 2566 | | | 2567 | 0x9c | byte string (one-byte uint8_t for n, and then n | 2568 | | bytes follow) | 2569 | | | 2570 | 0x9d | byte string (two-byte uint16_t for n, and then n | 2571 | | bytes follow) | 2572 | | | 2573 | 0x9e | byte string (four-byte uint32_t for n, and then | 2574 | | n bytes follow) | 2575 | | | 2576 | 0x9f | byte string (eight-byte uint64_t for n, and then | 2577 | | n bytes follow) | 2578 | | | 2579 | 0xa0..0xbb | UTF-8 string (0x00..0x1b bytes follow) | 2580 | | | 2581 | 0xbc | UTF-8 string (one-byte uint8_t for n, and then n | 2582 | | bytes follow) | 2583 | | | 2584 | 0xbd | UTF-8 string (two-byte uint16_t for n, and then | 2585 | | n bytes follow) | 2586 | | | 2587 | 0xbe | UTF-8 string (four-byte uint32_t for n, and then | 2588 | | n bytes follow) | 2589 | | | 2590 | 0xbf | UTF-8 string (eight-byte uint64_t for n, and | 2591 | | then n bytes follow) | 2592 | | | 2593 | 0xc0..0xdb | array (0x00..0x1b data items follow) | 2594 | | | 2595 | 0xdc | array (one-byte uint8_t for n, and then n data | 2596 | | items follow) | 2597 | | | 2598 | 0xdd | array (two-byte uint16_t for n, and then n data | 2599 | | items follow) | 2600 | | | 2601 | 0xde | array (four-byte uint32_t for n, and then n data | 2602 | | items follow) | 2603 | | | 2604 | 0xdf | array (eight-byte uint64_t for n, and then n | 2605 | | data items follow) | 2606 | | | 2607 | 0xe0..0xfb | map (0x00..0x1b pairs of data items follow) | 2608 | | | 2609 | 0xfc | map (one-byte uint8_t for n, and then n pairs of | 2610 | | data items follow) | 2611 | | | 2612 | 0xfd | map (two-byte uint16_t for n, and then n pairs | 2613 | | of data items follow) | 2614 | | | 2615 | 0xfe | map (four-byte uint32_t for n, and then n pairs | 2616 | | of data items follow) | 2617 | | | 2618 | 0xff | map (eight-byte uint64_t for n, and then n pairs | 2619 | | of data items follow) | 2620 +----------------+--------------------------------------------------+ 2622 Table 3: Resulting Jump Table for initial byte 2624 This jump table does not show initial bytes that are currently 2625 reserved for future extension; these are listed in Table 4. 2627 +------------+--------------------------------------------------+ 2628 | Byte | Structure | 2629 +------------+--------------------------------------------------+ 2630 | 0x40..0x57 | (Reserved) | 2631 | | | 2632 | 0x5c | (Reserved) (one byte follows) | 2633 | | | 2634 | 0x70 | (Reserved) (data item follows) | 2635 | | | 2636 | 0x77..0x7b | (Reserved) (data item follows) | 2637 | | | 2638 | 0x7c | (Reserved) (one byte, then data item follows) | 2639 | | | 2640 | 0x7d | (Reserved) (two bytes, then data item follows) | 2641 | | | 2642 | 0x7e | (Reserved) (four bytes, then data item follows) | 2643 | | | 2644 | 0x7f | (Reserved) (eight bytes, then data item follows) | 2645 +------------+--------------------------------------------------+ 2647 Table 4: Reserved values for initial byte 2649 D.6.2.1. Various Items 2651 The major type mt=010 picks up several unrelated things that don't 2652 need a whole major type of its own; each value of the 5-bit 2653 additional information has its own separate meaning, as defined in 2654 Table 5. Like integers, items of this major type do not carry 2655 content data; all the information is in the initial bytes. 2657 +--------+--------------------------------------------------------+ 2658 | ai | semantics | 2659 +--------+--------------------------------------------------------+ 2660 | 0..15 | reserved for future optimization | 2661 | | | 2662 | 16..23 | (reserved for special16..special23) | 2663 | | | 2664 | 24 | False | 2665 | | | 2666 | 25 | True | 2667 | | | 2668 | 26 | Nil (Null) | 2669 | | | 2670 | 27 | Undefined | 2671 | | | 2672 | 28 | (one byte follows; reserved for special28..special255) | 2673 | | | 2674 | 29 | IEEE 754 Half-Precision Float (16 bits follow) | 2675 | | | 2676 | 30 | IEEE 754 Single-Precision Float (32 bits follow) | 2677 | | | 2678 | 31 | IEEE 754 Double-Precision Float (64 bits follow) | 2679 +--------+--------------------------------------------------------+ 2681 Table 5: Various Items (ai = additional information) 2683 The use of ai=29 to ai=31 for 2- to 8-byte values retains the general 2684 structure of the initial bytes, the length of which always depends on 2685 the additional information in the first byte. 2687 D.6.2.1.1. Four Special Values 2689 False, True, Nil, and Undefined are four special values that can be 2690 encoded in CBOR. False, True, and Nil play the same roles as false, 2691 true, and null in JSON. A value of Undefined can be used as a 2692 substitute for a data item with an encoding problem, in order to 2693 allow the rest of the enclosing data items to be encoded without 2694 harm. 2696 D.6.2.1.2. Floating Point Values 2698 Floating point values are encoded in the additional data of the 2699 appropriate size. CBOR supports 16-bit, 32-bit, and 64-bit IEEE 754 2700 binary floating point values. 2702 As a quality of implementation concern, implementations are expected 2703 to use the shortest representation for a floating point value. As 2704 Half-Precision is not yet as universally supported in programming 2705 languages and libraries as the other two sizes, there is less of an 2706 expectation that it will be used. Implementations MAY also replace 2707 floating point value that happen to have zero fractional parts by the 2708 equivalent integer, in particular if the encoding is shorter. (See 2709 also Appendix D.6.4.2.) 2711 D.6.2.1.3. Reserved special item numbers 2713 For mt=010, many ai values (including ai=28 that carries one byte of 2714 additional data) have not been assigned semantics in this 2715 specification; they are reserved for future definition. These values 2716 are registered in an IANA registry and allocated by Standards Action 2717 ([RFC5226]). (TBD: Do we need experimental values here?) 2719 D.6.2.2. Tagged Items 2721 In CBOR, a data item can be "tagged" to give it different or 2722 additional semantics while retaining its structure. The tag is an 2723 integer number as indicated by the tag's integer value; the (sole) 2724 data item is carried as content data. If a tag requires structured 2725 data, this structure is encoded into the data item as defined by the 2726 tag. 2728 While tagging is a required part of CBOR, the support of any specific 2729 tag is an optional feature (see Appendix D.6.3.1). 2731 D.6.2.3. Byte Strings 2733 The strings transported in major type mt=100 have application- 2734 specific semantics. In a schemaless environment, the semantics is 2735 typically specified by adjacent data items, such as keys in a map. 2736 Byte strings are also useful as data items within tagged items. 2738 D.6.2.4. UTF-8 Text Strings 2740 The text strings transported in major type mt=101 MUST be UTF-8 2741 strings [RFC3629]. (The general assumption is that these UTF-8 2742 strings are in Network Unicode form [RFC5198].) 2744 D.6.2.5. Arrays 2746 Arrays (mt=110) are sequences of data items, which need not all be of 2747 the same type. The integer value gives the number of data items that 2748 follow the initial bytes. 2750 D.6.2.6. Maps 2752 The content data for a map (mt=111, often also called table, 2753 dictionary, or hash; or object in JSON) is comprised of pairs of data 2754 items, the even-numbered ones serving as keys and the following odd- 2755 numbered ones serving as values for this key. The integer value 2756 gives the number of pairs of data items that follow the initial bytes 2757 (i.e., 2*av data items follow). 2759 For JSON interworking, applications may want to restrict keys to 2760 UTF-8 strings. 2762 D.6.3. Optional Features 2764 This section describes features that may not be used in every 2765 implementation of CBOR. While it is easy to build a complete CBOR 2766 implementation on a general purpose computer, more specialized 2767 implementations, such as on constrained nodes, may want to leave off 2768 one or more of the features described here. 2770 D.6.3.1. Tags 2772 Applications may use specific tags defined in the following list and/ 2773 or defined by standard action or in the registry. 2775 +-----------+---------------------+---------------------------------+ 2776 | tag | data item | semantics | 2777 +-----------+---------------------+---------------------------------+ 2778 | 0..7 | byte string | bit string, tag value = number | 2779 | | | of padding bits in last byte | 2780 | | | | 2781 | 8 | byte string | positive bignum: interpret data | 2782 | | | as uint | 2783 | | | | 2784 | 9 | byte string | negative bignum: data (as uint) | 2785 | | | subtracted from -1 | 2786 | | | | 2787 | 10 | unsigned integer | Reserved | 2788 | | | | 2789 | 11 | (see below) | date/time | 2790 | | | | 2791 | 12 | byte string | base64url encoding | 2792 | | | | 2793 | 13 | byte string | base64 encoding | 2794 | | | | 2795 | 14 | byte string | base32 encoding | 2796 | | | | 2797 | 15 | byte string | base32hex encoding | 2798 | | | | 2799 | 16 | byte string | base16 encoding | 2800 | | | | 2801 | 17..23 | (reserved) | allocated by IETF review | 2802 | | | | 2803 | 24..39 | (reserved) | for experimental use only | 2804 | | | | 2805 | 40..255 | (reserved) | allocated by IETF review | 2806 | | | | 2807 | 256.. | (unallocated) | allocated by Expert Review | 2808 +-----------+---------------------+---------------------------------+ 2810 Table 6: Values for tags 2812 D.6.3.1.1. Bit Strings 2814 Bit strings are sequences of bits. They are represented as byte 2815 strings, in most significant bit first order. If the byte string is 2816 empty, the tag value MUST be 0. If the byte string is non-empty, the 2817 tag value gives the number of bits in the final byte of the byte 2818 string that are not part of the bit string. These bits MUST be 2819 transmitted as 0. (As a result, the number of bits is "sz*8-tv", 2820 where "sz" is the number of bytes in the byte string and "tv" is the 2821 numeric value of the Tag.) 2823 D.6.3.1.2. Bignums 2825 Bignums are integers that do not fit into the basic integer 2826 representations provided by mt=000 and mt=001. 2828 As a quality of implementation concern, encoders are expected to use 2829 the minimum number of bytes required to represent the bignum (i.e., 2830 no leading zeroes). However, a decoder MUST be able to decode 2831 bignums with leading zeroes. 2833 D.6.3.1.3. Date/Time 2835 A Date/Time tag may be placed before one of the following four kinds 2836 of data items: 2838 +--------------+----------------------------------------------+ 2839 | data item | Semantics | 2840 +--------------+----------------------------------------------+ 2841 | UTF-8 string | Internet date/time [RFC3339] | 2842 | | | 2843 | number | UTC in seconds relative to 1970-01-01T00:00Z | 2844 | | | 2845 | byte string | NTP timestamp: 4, 8, or 16 bytes [RFC5905] | 2846 | | | 2847 | array | see below | 2848 +--------------+----------------------------------------------+ 2850 Table 7: Date/Time data items 2852 Note that the number can be fractional and/or negative. The array 2853 contains two numbers, one for seconds, and one (< 10**9) for 2854 nanoseconds, since 1970-01-01T00:00Z; a third number can be added to 2855 the array to indicate a timezone in minutes east of UTC (the time 2856 itself stays in UTC). If the first number is a floating point 2857 number, the second number MUST be the integer number zero. 2859 An application may restrict the variations allowed. 2861 D.6.3.1.4. Base Encoding 2863 To encode a UTF-8 string that happens to exactly encode a byte string 2864 in one of the encodings defined in [RFC4648], the equivalent tagged 2865 encoding of that byte string can be used. 2867 For example, to encode the UTF-8 string "Zm9vYmFy", which happens to 2868 be both the base64 and base64url encoding for the bytes "foobar", 2869 either of the following two encodings can be used: 2871 6c 86 66 6f 6f 62 61 72 (= tag12(bytes(6, foobar))) 2872 6d 86 66 6f 6f 62 61 72 (= tag13(bytes(6, foobar))) 2874 Figure 25: Example base encoding 2876 (This is intended to enable JSON roundtripping with reasonably coding 2877 efficiency where large binary values are base-encoded. The initial 2878 CBOR encoder does not actually have to base-encode. If CBOR encoding 2879 is used on the entire path, actual base encoding may never need to 2880 occur.) 2882 D.6.3.1.5. Registry of Tags 2884 Tags are the main extension mechanism provided by CBOR. New tags are 2885 registered in an IANA registry. For tags numbered below 256, a 2886 strict allocation policy applies: IETF review [RFC5226]. Within this 2887 space, the tags numbered 24 to 39 are reserved for experimental use, 2888 they MUST NOT be used in production use. 2890 D.6.4. Discussion 2892 D.6.4.1. Single-Byte Argument Data 2894 For increased coding efficiency, the argument value of a single byte 2895 of argument data could alternatively be determined by adding 28 to 2896 the integer value of the argument data byte. This would trade some 2897 minor complexity (adding 28) for some minor enhancement in coding 2898 efficiency (saving a byte for "av" values within 256 to 283.) This 2899 is not done in this specification to make it as accessible as 2900 possible. 2902 D.6.4.2. Integer vs Floating Point encoding 2904 For the purposes of this specification, all number representations 2905 are equivalent. This means that an encoder can encode a floating 2906 point value of 0.0 as the integer 0. It, however, also means that an 2907 application that expects to find integer values only might find 2908 floating point values if the encoder decides these are desirable, 2909 e.g., where the floating point value is more compact than a 64-bit 2910 integer. 2912 An integer-only application may want to exclude the use of floating 2913 point values. 2915 A compact application may want to exclude integer encodings that are 2916 longer than necessary, e.g. to save the need to implement 64-bit 2917 integers. 2919 D.6.5. Diagnostic Notation 2921 CBOR is a binary interchange format. To facilitate documentation and 2922 debugging, and in particular to facilitate communication between 2923 entities cooperating in debugging, this section defines a simple 2924 human-readable diagnostic notation. Actual interchange always 2925 happens in the binary format. 2927 From JSON, the diagnostic notation borrows the syntax for numbers 2928 (integer and floating point), True, False, Nil (notated null as in 2929 JSON), UTF-8 strings, arrays and maps (maps are called objects in 2930 JSON; the diagnostic notation extends JSON here by allowing any data 2931 item in the key position). Undefined is written >undefined< as in 2932 JavaScript. A tagged item is written as an integer number for the 2933 tag followed by the item in parentheses, e.g. an RFC 3339 (ISO 8601) 2934 date could be notated as: 2936 11("2013-03-21T20:04:00Z") 2938 or the equivalent relative time as 2940 11(1363896240) 2942 Any reserved specials encountered are written as >special0< to 2943 >special255<. 2945 Byte strings are notated in one of the base encodings, enclosed in 2946 single quotes, prefixed by >h< for base16, >b32< for base32, >b32h< 2947 for base32hex, >b64< for base64 or base64url (the actual encodings do 2948 not overlap, so the string remains unambiguous). E.g., the byte 2949 string 0x12345678 could be written h'12345678', b32'CI2FM6A=', or 2950 b64'EjRWeA=='. 2952 There is no way to indicate in the diagnostic notation which of 2953 several alternative representations were actually used, so a data 2954 item written >1.5< be a diagnostic decoder might have been encoded as 2955 a Half, a Float, or a Double. (Future versions of the diagnostic 2956 notation might want to add some annotations for those fine 2957 differences.) 2959 D.6.6. Examples 2961 +------------------------+------------------------------------------+ 2962 | Diagnostic | Encoded | 2963 +------------------------+------------------------------------------+ 2964 | 0 | 0x00 | 2965 | | | 2966 | 1 | 0x01 | 2967 | | | 2968 | 10 | 0x0a | 2969 | | | 2970 | 27 | 0x1b | 2971 | | | 2972 | 28 | 0x1c1c | 2973 | | | 2974 | 29 | 0x1c1d | 2975 | | | 2976 | 100 | 0x1c64 | 2977 | | | 2978 | 1000 | 0x1d03e8 | 2979 | | | 2980 | 1000000 | 0x1e000f4240 | 2981 | | | 2982 | 1000000000000 | 0x1f000000e8d4a51000 | 2983 | | | 2984 | -1 | 0x20 | 2985 | | | 2986 | -10 | 0x29 | 2987 | | | 2988 | -100 | 0x3c63 | 2989 | | | 2990 | -1000 | 0x3d03e7 | 2991 | | | 2992 | 0.0 | 0x5d0000 | 2993 | | | 2994 | -0.0 | 0x5d8000 | 2995 | | | 2996 | 1.0 | 0x5d3c00 | 2997 | | | 2998 | 1.1 | 0x5f3ff199999999999a | 2999 | | | 3000 | 1.5 | 0x5d3e00 | 3001 | | | 3002 | 65504.0 | 0x5d7bff | 3003 | | | 3004 | 100000.0 | 0x5e47c35000 | 3005 | | | 3006 | 3.4028234663852886e+38 | 0x5e7f7fffff | 3007 | | | 3008 | 1.0e+300 | 0x5f7e37e43c8800759c | 3009 | | | 3010 | 5.960464477539063e-08 | 0x5d0001 | 3011 | | | 3012 | 6.103515625e-05 | 0x5d0400 | 3013 | | | 3014 | -4.0 | 0x5dc400 | 3015 | | | 3016 | -4.1 | 0x5fc010666666666666 | 3017 | | | 3018 | Infinity | 0x5d7c00 | 3019 | | | 3020 | NaN | 0x5ffff8000000000000 | 3021 | | | 3022 | -Infinity | 0x5dfc00 | 3023 | | | 3024 | 11("2013-03-21T20:04:0 | 0x6bb4323031332d30332d32315432303a30343a | 3025 | 0Z") | 30305a | 3026 | | | 3027 | 11(1363896240) | 0x6b1e514b67b0 | 3028 | | | 3029 | "" | 0xa0 | 3030 | | | 3031 | "a" | 0xa161 | 3032 | | | 3033 | "\u00FC" | 0xa2c3bc | 3034 | | | 3035 | "IETF" | 0xa449455446 | 3036 | | | 3037 | [] | 0xc0 | 3038 | | | 3039 | [1, 2, 3] | 0xc3010203 | 3040 | | | 3041 | {} | 0xe0 | 3042 | | | 3043 | {1: 2, 3: 4} | 0xe201020304 | 3044 | | | 3045 | {"a": 1, "b": [2, 3]} | 0xe2a16101a162c20203 | 3046 | | | 3047 | ["a", {"b": "c"}] | 0xc2a161e1a162a163 | 3048 +------------------------+------------------------------------------+ 3050 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 3051 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30] 3053 -> 0xdc1e0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1c1c 3054 1d1c1e 3056 {"a": "A", "b": "B", "c": "C", "d": "D", "e": "E"} 3058 -> 0xe5a161a141a162a142a163a143a164a144a165a145 3060 (TODO: more) 3062 D.6.7. Acknowledgements 3064 (This subsection needs a proper acknowledgements subsubsection.) 3066 The encoding of the argument information in CBOR was inspired by the 3067 encoding of length information designed by Klaus Hartke for CoAP. 3069 Authors' Addresses 3070 Carsten Bormann 3071 Universitaet Bremen TZI 3072 Postfach 330440 3073 Bremen D-28359 3074 Germany 3076 Phone: +49-421-218-63921 3077 Email: cabo@tzi.org 3079 Klaus Hartke 3080 Universitaet Bremen TZI 3081 Postfach 330440 3082 Bremen D-28359 3083 Germany 3085 Phone: +49-421-218-63905 3086 Email: hartke@tzi.org