idnits 2.17.1 draft-ietf-core-coap-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 187: '...est. The A Flag SHOULD be set request...' RFC 2119 keyword, line 189: '....1). The A Flag MAY be unset in cases...' RFC 2119 keyword, line 191: '...The Method field MUST be set with a va...' RFC 2119 keyword, line 205: '... o The Version Field MUST be 0....' RFC 2119 keyword, line 207: '... o The Type Flag MUST be 0....' (62 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The Content-type Identifier Option indicates the Internet Media Type of the message-body, see Section 11.2 for the encoding and identifier tables. A Content-type Identifier Option SHOULD be included if there is a payload included with a CoAP message, and MUST not be included for a zero-length payload. In the absence of the Content-type Option the MIME type "text/plain" MUST be assumed. -- The document date (June 7, 2010) is 5072 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC4346' is defined on line 1227, but no explicit reference was found in the text == Unused Reference: 'RFC4347' is defined on line 1230, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-nottingham-http-link-header-09 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4346 (Obsoleted by RFC 5246) ** Obsolete normative reference: RFC 4347 (Obsoleted by RFC 6347) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) == Outdated reference: A later version (-15) exists of draft-cheshire-dnsext-multicastdns-11 Summary: 6 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Z. Shelby 3 Internet-Draft Sensinode 4 Intended status: Standards Track B. Frank 5 Expires: December 9, 2010 SkyFoundry 6 D. Sturek 7 Pacific Gas & Electric 8 June 7, 2010 10 Constrained Application Protocol (CoAP) 11 draft-ietf-core-coap-00 13 Abstract 15 This document specifies the Constrained Application Protocol (CoAP), 16 a specialized transfer protocol for use with constrained networks and 17 nodes for machine-to-machine applications such as smart energy and 18 building automation. These constrained nodes often have 8-bit 19 microcontrollers with small amounts of ROM and RAM, while networks 20 such as 6LoWPAN often have high packet error rates and typical 21 throughput of 10s of kbit/s. CoAP provides request/reply and 22 subscribe/notify interaction models between application end-points, 23 supports built-in resource discovery, and includes key web concepts 24 such as URIs and RESTful methods. CoAP easily translates to HTTP for 25 integration with the web while meeting specialized requirements such 26 as multicast support, very low overhead and simplicity for 27 constrained environments. 29 Status of this Memo 31 This Internet-Draft is submitted to IETF in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF), its areas, and its working groups. Note that 36 other groups may also distribute working documents as Internet- 37 Drafts. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 The list of current Internet-Drafts can be accessed at 45 http://www.ietf.org/ietf/1id-abstracts.txt. 47 The list of Internet-Draft Shadow Directories can be accessed at 48 http://www.ietf.org/shadow.html. 50 This Internet-Draft will expire on December 9, 2010. 52 Copyright Notice 54 Copyright (c) 2010 IETF Trust and the persons identified as the 55 document authors. All rights reserved. 57 This document is subject to BCP 78 and the IETF Trust's Legal 58 Provisions Relating to IETF Documents 59 (http://trustee.ietf.org/license-info) in effect on the date of 60 publication of this document. Please review these documents 61 carefully, as they describe your rights and restrictions with respect 62 to this document. Code Components extracted from this document must 63 include Simplified BSD License text as described in Section 4.e of 64 the Trust Legal Provisions and are provided without warranty as 65 described in the BSD License. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 70 2. Constrained Application Protocol . . . . . . . . . . . . . . . 4 71 2.1. Interaction Model . . . . . . . . . . . . . . . . . . . . 4 72 2.1.1. Request messages . . . . . . . . . . . . . . . . . . . 5 73 2.1.2. Notify messages (Experimental) . . . . . . . . . . . . 6 74 2.1.3. Response message . . . . . . . . . . . . . . . . . . . 6 75 2.1.4. Option fields . . . . . . . . . . . . . . . . . . . . 7 76 2.1.5. Transaction IDs . . . . . . . . . . . . . . . . . . . 7 77 2.2. Methods . . . . . . . . . . . . . . . . . . . . . . . . . 7 78 2.2.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 7 79 2.2.2. POST . . . . . . . . . . . . . . . . . . . . . . . . . 7 80 2.2.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 8 81 2.2.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . . 8 82 2.2.5. SUBSCRIBE (Experimental) . . . . . . . . . . . . . . . 8 83 2.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 84 2.4. CoAP Codes . . . . . . . . . . . . . . . . . . . . . . . . 9 85 2.5. Content-type encoding . . . . . . . . . . . . . . . . . . 9 86 3. Message Formats . . . . . . . . . . . . . . . . . . . . . . . 10 87 3.1. CoAP header . . . . . . . . . . . . . . . . . . . . . . . 10 88 3.2. Header options . . . . . . . . . . . . . . . . . . . . . . 13 89 3.2.1. Content-type Option . . . . . . . . . . . . . . . . . 15 90 3.2.2. Uri Option . . . . . . . . . . . . . . . . . . . . . . 15 91 3.2.3. Max-age Option . . . . . . . . . . . . . . . . . . . . 15 92 3.2.4. Etag Option . . . . . . . . . . . . . . . . . . . . . 15 93 3.2.5. Date Option . . . . . . . . . . . . . . . . . . . . . 15 94 3.2.6. Subscription-lifetime Option (Experimental) . . . . . 16 95 4. UDP Binding . . . . . . . . . . . . . . . . . . . . . . . . . 16 96 4.1. Retransmission . . . . . . . . . . . . . . . . . . . . . . 17 97 4.2. Default Port . . . . . . . . . . . . . . . . . . . . . . . 17 98 5. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 99 5.1. Cache control . . . . . . . . . . . . . . . . . . . . . . 18 100 5.2. Cache refresh . . . . . . . . . . . . . . . . . . . . . . 18 101 5.3. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 19 102 6. Resource Discovery . . . . . . . . . . . . . . . . . . . . . . 19 103 6.1. Link Format . . . . . . . . . . . . . . . . . . . . . . . 20 104 7. HTTP Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 21 105 8. Protocol Constants . . . . . . . . . . . . . . . . . . . . . . 21 106 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 107 10. Security Considerations . . . . . . . . . . . . . . . . . . . 23 108 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 109 11.1. Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 23 110 11.2. Content Types . . . . . . . . . . . . . . . . . . . . . . 24 111 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 26 112 13. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 26 113 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 114 14.1. Normative References . . . . . . . . . . . . . . . . . . . 28 115 14.2. Informative References . . . . . . . . . . . . . . . . . . 28 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 118 1. Introduction 120 The use of web services on the Internet has become ubiquitous in most 121 applications, and depends on the fundamental Representational State 122 Transfer (REST) architecture of the web. The Constrained RESTful 123 Environments (CoRE) working group aims at realizing the REST 124 architecture in a suitable form for the most constrained nodes (e.g. 125 8-bit microcontrollers with limited RAM and ROM) and networks (e.g. 126 6LoWPAN). One of the main goals of CoRE is to design a generic 127 RESTful protocol for the special requirements of this constrained 128 environment, especially considering energy and building automation 129 applications. 131 This document specifies the RESTful Constrained Application Protocol 132 (CoAP) which easily translates to HTTP for integration with the web 133 while meeting specialized requirements such as multicast support, 134 very low overhead and simplicity for constrained environments 135 [I-D.shelby-core-coap-req]. CoAP has the following main features: 137 o RESTful protocol design minimizing the complexity of mapping with 138 HTTP. 140 o UDP binding with multicast and retransmission support. 142 o Low header overhead and parsing complexity. 144 o URI and Content-type support. 146 o Built-in resource discovery. 148 o Simple subscription for a resource with a resulting notification 149 mechanism. 151 o Simple caching based on a relative time limit ("max-age"). 153 The mapping of CoAP with HTTP is defined, allowing proxies to be 154 built providing access to CoAP resources via HTTP in a uniform way. 156 2. Constrained Application Protocol 158 This section specifies the basic functionality and processing rules 159 of CoAP. 161 2.1. Interaction Model 163 The interaction model of CoAP is client/server with request or notify 164 messages initiating a transaction responded to with a matching 165 response based on a transaction ID. Machine-to-machine interactions 166 with a RESTful design typically result in a CoAP implementation 167 acting in both client and server roles (called an end-point). A CoAP 168 request is similar to an HTTP request, and is sent by a client to 169 request an action (using a method) on a resource (identified by a 170 URI) on a server. 172 In addition to this typical request/response model, CoAP also 173 supports an asynchronous subscribe/notify interaction model. A CoAP 174 notify is the inverse of a request, where a server sends a notify 175 message to a client about a resource on the server (identified by a 176 URI). A notify includes the representation, Etag and/or Date of the 177 resource. Example message exchanges can be found from Section 9. 179 This document specifies the interaction of two CoAP end-points, one 180 of which acting as a client, and the other acting as a server. A 181 host may run any number of CoAP end-points. 183 2.1.1. Request messages 185 A CoAP end-point acting as a client sends a request with the 186 following rules. The Version field is set to 0. The Type Flag is 187 set to 0 indicating a request. The A Flag SHOULD be set requesting a 188 response and enabling retransmission in case of a timeout (see 189 Section 4.1). The A Flag MAY be unset in cases when a response is 190 too costly (such as a multicast message) or not useful (e.g. real- 191 time streaming). The Method field MUST be set with a value of 0-4. 192 A new TRANSACTION_ID is generated, and this value is placed in the 193 Transaction ID Field. See Section 2.1.4 for options rules. If a 194 payload is to be included in the message, it immediately follows the 195 last option or the Transaction ID if none. 197 For each request sent with the A flag set, a CoAP end-point keeps 198 track of the destination IP address and Transaction ID of the request 199 for the purpose of matching responses. The retransmission procedure 200 is described in Section 4.1. 202 Upon receiving a request, a CoAP end-point performs the following 203 validation and processing: 205 o The Version Field MUST be 0. 207 o The Type Flag MUST be 0. 209 o The Method Field MUST be 0-4. 211 o If the Number of Options Field is > 0, then each option is 212 validated and processed as in Section 2.1.4. 214 o The length of the Payload is calculated from the datagram 215 length. 217 o The Method, URI, any options and Payload are passed on to the 218 corresponding application process. 220 o If the A bit is set, an appropriate response message MUST be 221 sent to the source IPv6 address and port of the request with the 222 same Transaction ID of the request. If the A bit is unset, a 223 response message MUST NOT be sent. 225 2.1.2. Notify messages (Experimental) 227 The sending of a notify message is similar to sending a request 228 message, with the following difference: The Type Flag is set to 2. 229 The processing of a notify message is similar to processing a request 230 message. 232 2.1.3. Response message 234 A response message is created with the following rules. The Version 235 Field is set to 0. The Type Flag is set to 1. The Code is set to 236 one of the supported response codes in Section 11.1. The Transaction 237 ID MUST be set to that of the corresponding request. See 238 Section 2.1.4 for options rules. An optional Payload may be included 239 as appropriate for the request. 241 Upon receiving a response, a CoAP end-point performs the following 242 validation and processing: 244 o The Version Field MUST be 0. 246 o The Type Flag MUST be 1. 248 o The Code Field MUST contain a valid code. 250 o If the Number of Options Field is > 0, then each option is 251 validated and processed as in Section 2.1.4. 253 o The length of the Payload is calculated from the datagram 254 length. 256 o The Transaction ID is used to match the response to an open 257 request entry, and the response code, any options and Payload are 258 passed on to the corresponding application process. If no match 259 is found, the message is silently discarded. 261 2.1.4. Option fields 263 If no options are to be included, the Option Number Field is set to 0 264 and the Payload (if any) immediately follows the Transaction ID. If 265 options are to be included, the following rules apply. The number of 266 options is placed in the Number of Options Field. Each option is 267 then placed in order of Type, immediately following the Transaction 268 ID with no padding. Upon reception, unknown options MUST be silently 269 skipped. 271 2.1.5. Transaction IDs 273 The Transaction ID is an unsigned integer kept by a CoAP end-point 274 for all of the CoAP request or notify messages it sends. Each CoAP 275 end-point keeps a single Transaction ID variable, which is changed 276 each time a new request or notify message is sent regardless of the 277 destination address or port. The Transaction ID is used to match a 278 response with an outstanding request or notify, for retransmission 279 and to discard duplicate messages. The initial Transaction ID should 280 be randomized. 282 2.2. Methods 284 CoAP supports the basic RESTful methods of GET, POST, PUT, DELETE, 285 which are easily mapped to HTTP methods. In this section each method 286 is defined along with its behavior. In addition, CoAP defines a new 287 SUBSCRIBE method for requesting soft-state subscriptions for 288 resources. 290 As CoAP methods manipulate resources, they have the same properties 291 of safe (only retrieval) and idempotent (you can invoke it multiple 292 times with the same effects) as HTTP Section 9.1 [RFC2616]. The GET 293 method is safe, therefore it MUST NOT take any other action on a 294 resource other than retrieval. The GET, PUT and DELETE methods MUST 295 be performed in such a way that they are idempotent. 297 2.2.1. GET 299 The GET method retrieves the information of the resource identified 300 by the request URI. Upon success a 200 (OK) response SHOULD be sent. 302 The response to a GET is cacheable if it meets the requirements in 303 Section 5. 305 2.2.2. POST 307 The POST method is used to request the server to create a new 308 resource under the requested URI. If a resource has been created on 309 the server, the response should be 201 (Created) including the URI of 310 the new resource in the header and any possible status in the message 311 body. If the POST does not result in a new resource being created on 312 the server, a 200 (OK) response code is returned. 314 Responses to this method are not cacheable. 316 2.2.3. PUT 318 The PUT method requests that the resource identified by the request 319 URI be updated with the enclosed message body. If a resource exists 320 at that URI the message body SHOULD be considered a modified version 321 of that resource. If no resource exists then the server MAY create a 322 new resource with that URI. 324 Responses to this method are not cacheable. 326 2.2.4. DELETE 328 The DELETE method requests that the resource identified by the 329 request URI be deleted. The response 200 (OK) SHOULD be sent on 330 success. 332 Responses to this method are not cacheable. 334 2.2.5. SUBSCRIBE (Experimental) 336 CoAP supports a built-in subscribe/notify push model for an end-point 337 to notify another end-point about a resource of interest. This push 338 is accomplished using the CoAP notify message type, whose URI 339 corresponds to the resource of interest on the end-point sending the 340 notify message. A notify may include the latest representation of 341 the resource in its payload and/or the Etag Option. 343 The SUBSCRIBE method allows an end-point to request notifications 344 about a resource. A request of this method MAY include the 345 Subscription-lifetime Option defined in Section 3.2.6. In the 346 absence of this Option, its maximum lifetime is assumed. End-points 347 MUST NOT send notify messages without a valid subscription. 348 Subscriptions are soft-state, and must be refreshed by sending a new 349 SUBSCRIBE message before the end of its lifetime. 351 Servers keep track of subscriptions, and upon change a notify message 352 is sent to the source address and port of the original SUBSCRIBE 353 request with the URI of the resource in question. Notifications MAY 354 be sent with the A bit set, enabling a server to detect if a 355 subscriber is no longer valid. A subscription SHOULD be removed 356 after MAX_RETRANSMIT failures when the A bit is set. A server is not 357 required to support subscriptions for its resources (thus this 358 feature is optional), and MAY limit the number of simultaneous 359 subscriptions. 361 2.3. URIs 363 The Universal Resource Identifier (URI) [RFC3986] is an important 364 feature of the REST architecture, where the relative part of the URI 365 indicates which resource is being manipulated. CoAP supports 366 variable-length string URIs with the Uri Option. As this URI is used 367 as a locator, CoAP only supports Universal Resource Locator features 368 of [RFC3986] although throughout the document we refer to URI. CoAP 369 supports relative references in the Uri Option (e.g. /sensors/ 370 temperature) for messages to a CoAP end-point, and absolute URIs for 371 use with a proxy (coap://[2001:1ba3::450a]/sensors/temperature), and 372 does not support "." and ".." schemes. A CoAP implementation MAY 373 support query "?" processing if needed, however fragment "#" 374 processing is not supported. IRIs are not supported. All URI 375 strings in CoAP MUST use the US-ASCII encoding defined in [RFC3986]. 376 When including a relative reference URI in the Uri Option, the 377 leading slash MUST be omitted. Thus the above example "/sensors/ 378 temperature" is included in the Uri Option as "sensors/temperature". 380 The CoAP protocol scheme is identified in URIs with "coap://" (TODO: 381 IANA considerations). 383 2.4. CoAP Codes 385 When a response message is sent in response to a request or notify 386 message it MUST always include a response code in the header. Notify 387 messages also include a code field, which is set to "200 OK" by 388 default. CoAP makes use of a subset of HTTP response codes as 389 defined in Section 11.1. 391 2.5. Content-type encoding 393 In order to support heterogeneous uses, CoAP is transparent to the 394 use of different application payloads. In order for the application 395 process receiving a packet to properly parse a payload, its content- 396 type should be explicitly known from the header (as e.g. with HTTP). 397 The use of typical binary encodings for XML is discussed in 398 [I-D.shelby-6lowapp-encoding]. 400 String names of Internet media types [RFC2046] are not optimal for 401 use in the CoAP header. Instead, CoAP simply assigns identifiers to 402 a subset of common MIME and content transfer encoding types. The 403 content-type identifier is optionally included in the Content-type 404 Option Header of messages to indicate the type of the message body. 406 CoAP Content-type identifiers are defined in Section 11.2. In the 407 absence of the Content-type Option the MIME type "text/plain" MUST BE 408 assumed. 410 3. Message Formats 412 CoAP makes use of three message types - request, notify and response, 413 using a simple binary header format. This base header may be 414 followed by options in Type-Length-Value (TLV) format. CoAP is bound 415 to UDP as described in Section 4. 417 Any bytes after the headers in the packet are considered the message 418 payload, if any. The length of the message payload is implied by the 419 datagram length or the Length Field of the magic byte header if 420 included. When bound to UDP the entire message MUST fit within a 421 single datagram. When used with 6LoWPAN [RFC4944], messages SHOULD 422 fit into a single IEEE 802.15.4 frame to minimize fragmentation. 424 3.1. CoAP header 426 This section defines the CoAP header, which is shared for all message 427 types. 429 Request: A CoAP request message is sent by a client to request a URI 430 on a server using one of the methods listed in Table 1. 432 Response: A CoAP response message is sent in response to a CoAP 433 request or notify when appropriate. Responses include a 434 Transaction ID corresponding to that of the request. A response 435 is always sent when the A flag is set in a request, and is never 436 sent when the A flag is not set. A response is always sent to the 437 source IP address and port of the corresponding request or notify. 439 Notify: (Experimental) A CoAP notify message is sent by a server to 440 notify a client about a resource (identified by a URI) on the 441 server as a result of a valid subscription for that resource. 443 Template: 445 0 1 2 3 446 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 447 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 448 |Ver| T | O | Type Specific | Transaction ID | 449 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 450 | Options (if any) ... 452 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 453 | Payload (if any) ... 454 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 456 Request (T=0): 458 0 1 2 3 459 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 460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 461 |Ver|0 0| O |A|_____| Meth | Transaction ID | 462 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 463 | Options (if any) ... 464 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 465 | Payload (if any) ... 466 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 468 Response (T=1): 470 0 1 2 3 471 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 472 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 473 |Ver|0 1| O |___| Code | Transaction ID | 474 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 475 | Options (if any) ... 476 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 477 | Payload (if any) ... 478 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 480 Notify (T=2): 482 0 1 2 3 483 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 484 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 485 |Ver|1 0| O |A|_| Code | Transaction ID | 486 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 487 | Options (if any) ... 488 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 489 | Payload (if any) ... 490 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 492 Figure 1: CoAP header format 494 Header Fields: 496 Ver: Version. 2-bit unsigned integer. Indicates the version of 497 CoAP. Implementations of this specification MUST set this 498 field to 0. The values 1-3 are reserved for future versions. 500 T: 2-bit Message Type flag. Indicates if this message is a CoAP 501 request (0), response (1) or notify (2) header. The value 3 is 502 forbidden to avoid collision with the magic byte 'r'. 504 O: 4-bit Number of Options field. Indicates if there are Option 505 Headers following the base header. If set to 0 the payload (if 506 any) immediately follows the base header. If greater than zero 507 the field indicates the number of options to immediately follow 508 the header. 510 A: 1-bit Acknowledgement flag. When set to 1, indicates that the 511 destination MUST respond with a response message matching this 512 request (see Section 4). When set to 0, the destination MUST 513 NOT send a response to this request. 515 Meth: 4-bit unsigned integer. This field indicates the CoAP 516 Method of the request according to Table 1. Methods are 517 described in detail in Section 2.2. 519 Code: 6-bit unsigned integer. This field indicates the code of a 520 response or notify message as defined in Section 11.1. 522 Transaction ID: 16-bit unsigned integer. A unique Transaction ID 523 assigned by the source and used to match responses. The 524 Transaction ID MUST be changed for each new request (regardless 525 of the end-point) and MUST NOT be changed when retransmitting a 526 request. 528 _: This field is unused. It MUST be initialized to zero by the 529 sender and MUST be ignored by the receiver. 531 +-----------+------+ 532 | Method | Code | 533 +-----------+------+ 534 | GET | 0 | 535 | POST | 1 | 536 | PUT | 2 | 537 | DELETE | 3 | 538 | SUBSCRIBE | 4 | 539 +-----------+------+ 541 Table 1: Method codes 543 3.2. Header options 545 CoAP messages may also include one or more header options in TLV 546 format. Each option has the following format: 548 Template: 550 0 551 0 1 2 3 4 5 552 +-+-+-+-+-+-+ 553 | Type |X| 554 +-+-+-+-+-+-+ 556 Length of 0-4: 558 0 1 2 3 559 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 560 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 561 | Type |0|Len| Option Value ... 562 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 564 Length of 5-1024: 566 0 1 2 3 567 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 568 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 569 | Type |1| Len | Option Value ... 570 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 572 Figure 2: Header option format 574 Type: 5-bit unsigned integer. The type of the option as defined in 575 Table 2, allowing for up to 32 options. Future specifications may 576 define new CoAP option types. Option types 30-32 are reserved for 577 experimental purposes. 579 X: 1-bit Extended Length Flag. When 0 the Length is a 2-bit unsigned 580 integer. When 1 the option header is extended by an octet and 581 Length is a 10-bit unsigned integer. 583 Len: Length Field. When X is 0 Length is a 2-bit unsigned integer 584 allowing values of 0-3 octets. When X is 1 Length is a 10-bit 585 unsigned integer allowing values of 0-1023 octets. 587 Option Value The value in the format defined for that option in 588 Table 2 with a length of Option Len octets. Options may use 589 variable length unsigned integer values of Len Field octets in 590 network byte order as shown in Figure 3. 592 0 593 0 1 2 3 4 5 6 7 594 +-+-+-+-+-+-+-+-+ 595 Len = 1 | 0-255 | 596 +-+-+-+-+-+-+-+-+ 598 0 1 599 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 600 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 601 Len = 2 | 0-65535 | 602 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 604 Len = 3 is 24 bits, Len = 4 is 32 bits etc. 606 Figure 3: Variable length unsigned integer value format 608 The following options are defined in this document. 610 +------+-----------------------+-----------+---------+--------------+ 611 | Type | Name | Data type | Length | Rules | 612 +------+-----------------------+-----------+---------+--------------+ 613 | 0 | Content-type | Variable | 1-2 B | | 614 | | | uint | | | 615 | 1 | Uri | String | 1-32768 | Never in | 616 | | | | B | response | 617 | 2 | Not used | - | - | - | 618 | 3 | Max-age | Variable | 0-4 B | | 619 | | | uint | | | 620 | 4 | Etag | Variable | 1-4 B | | 621 | | | uint | | | 622 | 5 | Date | Variable | 4-6 B | Never in | 623 | | | integer | | request | 624 | 6 | Subscription-lifetime | Variable | 1-3 B | With | 625 | | | uint | | SUBSCRIBE or | 626 | | | | | its response | 627 +------+-----------------------+-----------+---------+--------------+ 629 Table 2: Option headers 631 3.2.1. Content-type Option 633 The Content-type Identifier Option indicates the Internet Media Type 634 of the message-body, see Section 11.2 for the encoding and identifier 635 tables. A Content-type Identifier Option SHOULD be included if there 636 is a payload included with a CoAP message, and MUST not be included 637 for a zero-length payload. In the absence of the Content-type Option 638 the MIME type "text/plain" MUST be assumed. 640 3.2.2. Uri Option 642 The Uri Option indicates the string URI of the resource that may be 643 included in request and notify messages. In the absence of this 644 option, the URI is assumed to be "/". Section 2.3 specifies the 645 rules for URIs in CoAP. When including a relative reference URI in 646 the Uri Option, the leading slash MUST be omitted. 648 3.2.3. Max-age Option 650 The Max-age Option indicates the maximum age of the resource for use 651 in cache control in seconds. The option is represented as a variable 652 length unsigned integer maximum 32-bits in length. A length of 0 is 653 used to indicate a Max-age of 0. 655 When included in a request, Max-age indicates the maximum age of a 656 cached representation of that resource the client will accept. When 657 included in a response or a notify, Max-age indicates the maximum 658 time the representation may be cached before it MUST be discarded. 660 3.2.4. Etag Option 662 The Etag Option is a variable length unsigned integer which specifies 663 the version of a resource representation. An Etag may be generated 664 for a resource in any number of ways including a version, checksum, 665 hash or time. An end-point receiving an Etag MUST treat it as opaque 666 and make no assumptions about its format. The Etag MAY be included 667 in a notify message to indicate to a client if a resource has 668 changed. 670 3.2.5. Date Option 672 The Date Option indicates the creation time and date of a given 673 resource representation. It MAY be used in response and notify 674 messages. The integer value is the number of seconds, after midnight 675 UTC, January 1, 1970. This time format cannot represent time values 676 prior to January 1, 1970. The latest UTC time value that can be 677 represented by a 31 bit integer value is 03:14:07 on January 19, 678 2038. Time values beyond 03:14:07 on January 19, 2038, are 679 represented by 39 bit integer values which is sufficient to represent 680 dates that should be enough for anyone. For applications requiring 681 more accuracy, a 48-bit integer MAY be included representing this 682 value in milliseconds instead of seconds. 684 3.2.6. Subscription-lifetime Option (Experimental) 686 The Subscription-lifetime Option indicates the subscription lifetime 687 and is optionally included with the SUBSCRIBE method (see 688 Section 2.2.5). The corresponding response MUST include a 689 Subscription-lifetime Option confirming (or modifying) the 690 subscription lifetime. 692 The value of this option is a variable length unsigned integer up to 693 24-bits indicating the lifetime of the subscription in seconds with a 694 maximum value of 194 days. In a response the server MAY return a 695 different value that fits its own scheduling better. A value of all 696 0 in a request indicates cancellation of a subscription and in a 697 response indicates subscription failure or rejection. 699 4. UDP Binding 701 The CoAP protocol operates by default over UDP. CoAP could be used 702 over other transports such as TCP or SCTP, the specification of which 703 is out of this document's scope. 705 The goal of binding CoAP to UDP is to provide the bare minimum 706 features for the protocol to operate over UDP, without trying to re- 707 create the full feature set of TCP. CoAP over UDP has the following 708 features: 710 o Simple stop-and-wait retransmission reliability with exponential 711 back-off as described in Section 4.1 when the A Flag is set. 713 o Transaction ID for response matching as described in 714 Section 2.1.5. 716 o Multicast support without retransmission. CoAP supports the use 717 of multicast destination addresses when bound to UDP. Although 718 the A bit may be used to force a response, retransmission MUST NOT 719 be performed. 721 When a CoAP message is sent using UDP, the length of the Payload is 722 calculated from the datagram length. When bound to UDP the entire 723 message MUST fit within a single datagram of length 1024 octets. 724 When used with 6LoWPAN [RFC4944], messages SHOULD fit into a single 725 link-layer frame to minimize fragmentation if possible (often on the 726 order of 60-90 octets). 728 4.1. Retransmission 730 A CoAP end-point keeps track of open request or notify messages 731 expecting a response (A Flag set). Each entry includes at least the 732 destination address and port of the original message, the message 733 itself, a retransmission counter (UDP only) and a timeout. When a 734 request or notify message is sent with the A Flag set, an entry is 735 made for that message with a default initial timeout of 736 RESPONSE_TIMEOUT and the retransmission counter set to 0. When a 737 matching response is received for an entry, the entry is removed. 738 When a timeout is triggered for an entry and the retransmission 739 counter is less than MAX_RETRANSMIT, the original message is 740 retransmitted to the destination without modification, the 741 retransmission counter is incremented, and the timeout is doubled. 742 If the retransmission counter reaches MAX_RETRANSMIT on a timeout, 743 then the entry is removed and the application process informed of 744 delivery failure. 746 For CoAP messages sent to IP multicast addresses, retransmission MUST 747 NOT be performed. Therefore MAX_RETRANSMIT is always set to 0 when 748 the destination address is multicast. 750 4.2. Default Port 752 CoAP SHOULD use a default port of 61616 which is within the 753 compressed UDP port space defined in [RFC4944]. As this port is in 754 the dynamic port space, it however can not be reserved for CoAP use. 756 5. Caching 758 CoAP end-points are by definition constrained by bandwidth and 759 processing power. To optimize the performance of data transfer under 760 these constraints, we use caching features consistent with HTTP. 761 Caching includes the following concepts: 763 o cache life of a resource is controlled via the Max-Age header 764 option 766 o cache refresh and versioning of a resource is controlled via the 767 Etag header option 769 o proxies between a client and end-point may participate in the 770 caching process on behalf of sleeping end-points and to avoid 771 unnecessary traffic on the constrained network 773 5.1. Cache control 775 When an end-point publishes a resource for a GET request, it SHOULD 776 specify the Max-Age header option. The Max-Age specifies the cache 777 life of the resource in seconds. Resources which change rapidly will 778 have a short cache life, and resources which change infrequently 779 should specify a long cache life. If Max-Age is unspecified in a GET 780 response, then it is assumed to be 60 seconds. If an end-point 781 wishes to disable caching, it must explicitly specify a Max-Age of 782 zero seconds. 784 When a client reads the response from a GET request, it should cache 785 the resource representation for the cache lifetime as specified by 786 the Max-Age header. During the cache lifetime, the client SHOULD use 787 its cached version and avoid performing additional GETs for the 788 resource. 790 In general, the origin server end-point is responsible for 791 determining cache age. However, in some cases a client may wish to 792 determine its own tolerance for cache staleness. In this case, a 793 client may specify the Max-Age header during a GET request. If the 794 client's Max-Age is of a shorter duration than the age of a cached 795 resource, then the proxy or end-point SHOULD perform a cache refresh. 796 If the client specifies a Max-Age of zero seconds, then the response 797 MUST discard the cached representation and return a fresh 798 representation. 800 5.2. Cache refresh 802 After the expiration of the cache lifetime, clients and proxies can 803 refresh their cached representation of a resource. Cache refresh is 804 accomplished using GET request which will return a representation of 805 the resource's current state. 807 If the end-point has the capability to version the resource, then the 808 end-point should include the Etag header option in the response to a 809 GET request. The Etag is a variable length integer which captures a 810 version checksum of the resource. The Etag is an opaque identifier; 811 clients MUST NOT infer any semantics from the Etag value. 813 If an end-point specifies the Etag header option, then the client 814 SHOULD specify a matching Etag header option in their GET request 815 during cache refresh. If the end-point's version of the resource is 816 unmodified, then it SHOULD specify a 304 response with no payload to 817 avoid retransmitting the resource representation. 819 5.3. Proxying 821 See [I-D.frank-6lowapp-chopan]. 823 TODO: 825 o Are interception proxies are still required to deal with a) 826 sleeping nodes and b) protecting Internet HTTP traffic from 827 overwhelming the CoAP network? 829 o But interception proxies breaks end-to-end IP encapsulation and 830 requires support at the routing level 832 o Often the interception proxy is the same as the HTTP-to-CoAP 833 gateway, so we need to decide how these topics dovetail 835 o In Chopan, the sleeping problem was tackled by having sleeping 836 nodes check-in with their proxies while awake, notify model might 837 solve this problem to some extent but still have to coordinate the 838 sleep/awake times 840 o In Chopan we actually used caching to deal with POSTs, etc because 841 otherwise how do you send a request to a sleeping node? The 842 current caching sections are to be exclusive to GETs, but we still 843 need to solve the problem for other types if methods. 845 6. Resource Discovery 847 The discovery of resources offered by a CoAP end-point is extremely 848 important in machine-to-machine applications where there are no 849 humans in the loop and static interfaces result in fragility. The 850 discovery of resources provided by an HTTP Web Server is called Web 851 Discovery. In this document we refer to the discovery of resources 852 offered by a CoAP end-point as Resource Discovery. 854 CoAP makes the assumption that end-points are available on the 855 default CoAP port, or otherwise have been configured or discovered 856 using some general service discovery mechanism such as 857 [I-D.cheshire-dnsext-multicastdns]. This section assumes that such a 858 configuration or service discovery has already been performed, if 859 needed. 861 Resource Discovery in CoAP is accomplished through the use of well- 862 known resources which describe the links offered by that CoAP end- 863 point. Well-known resources have the URI form "/.well-known/" as 864 specified in [RFC5785]. Every CoAP end-point MUST support this well- 865 known resource. The resource representation of this is described in 866 Section 6.1. 868 CoAP requests the following well-known URL for discovery: "/.well- 869 known/resources" (TODO: Formal description for use in request as per 870 [RFC5785]). 872 CoAP Resource Discovery supports the following interactions: 874 o [request GET /.well-known/resources] returns the list of links 875 available from a CoAP end-point. 877 o A CoAP end-point may notify interested clients when this 878 description has changed by sending [notify /.well-known/ 879 resources]. This resource MAY support subscription. 881 o More capable end-points such as proxies MAY support a resource 882 directory by accepting [request POST /.well-known/resources] 883 messages from other CoAP end-points. This adds the resources of 884 other end-points to an agent directory in which absolute URIs are 885 included for the links. 887 End-points with a large number of resources SHOULD organize their 888 resource descriptions into a hierarchy of link resources. This is 889 done by including links in the /.well-known/resources list which 890 point to other resource lists, e.g. /.well-known/resources/sensors. 892 6.1. Link Format 894 CoAP resource discovery makes use of the HTTP Link Header format 895 specified in [I-D.nottingham-http-link-header]. This specification 896 allows for the use of this simple link format by other protocols, 897 thus not limiting it to the actual HTTP Link Header. The format does 898 not require special XML or binary parsing, and is extensible. 900 CoAP defines a subset of the [I-D.nottingham-http-link-header] 901 features and specific parameters that have known meaning for CoAP 902 resource discovery. A CoAP end-point MAY make use of link extension 903 parameters as needed. The CoAP link format does not start with the 904 "Link:" text. The following formal description is used for forming 905 and parsing this link format: 907 link-value = "<" URI-Reference ">" *( ";" link-param ) 908 link-param = ( ( "desc" "=" URI ) 909 | ( "name" "=" quoted-string ) 910 | ( "type" "=" ( media-type | media-code) ) 911 | ( "id" "=" integer ) 912 | ( link-extension ) ) 913 link-extension = ( parmname [ "=" ( ptoken | quoted-string ) ] ) 914 ptoken = 1*ptokenchar 915 ptokenchar = "!" | "#" | "$" | "%" | "&" | "'" | "(" 916 | ")" | "*" | "+" | "-" | "." | "/" | DIGIT 917 | ":" | "<" | "=" | ">" | "?" | "@" | ALPHA 918 | "[" | "]" | "^" | "_" | "`" | "{" | "|" 919 | "}" | "~" 920 media-code = see Section 11.2 921 media-type = type-name "/" subtype-name 923 The link-value is the relative URI of the resource on that end-point 924 or an absolute URI in the case of a directory agent. The desc 925 parameter is a URI that points to the definition of that resource 926 interface, for example in WADL. The name parameter is a descriptive 927 or ontology name of the resource class. This name parameter SHOULD 928 be in an m-DNS [I-D.cheshire-dnsext-multicastdns] compatible form. 929 The type parameter includes Internet media type this resource returns 930 in ascii or code format. The id field is a unique identifier (e.g. 931 UUID) for this resource for use in e.g. search directories. All link 932 parameters are optional and custom link-extensions may be defined. 933 An example of a typical CoAP link description in this format would 934 be: 936 ; name="TemperatureC"; type=text/xml; 937 ; name="LightLux"; type=text/xml; 939 7. HTTP Mapping 941 TODO 943 8. Protocol Constants 945 This section defines the relevant protocol constants defined in this 946 document: 948 RESPONSE_TIMEOUT 1 second 950 MAX_RETRANSMIT 5 952 9. Examples 954 Figure 4 shows a basic request sequence. A client makes a GET 955 request for the resource /temperature to the server. The A Flag is 956 set, requesting a response and the Transaction ID is 1234. The 957 request includes one Uri Option "temperature" of Len = 11. This 958 request is a total of 17 octets long. The corresponding response is 959 of code 200 OK and includes a Payload of "22.3 C". The Transaction 960 ID is 1234, thus the transaction is successfully completed. The 961 response is 10 octets long. 963 CLIENT SERVER 964 | | 965 | ------ GET /temperature [A, TID=1234] ------> | 966 | | 968 0 1 2 3 969 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 970 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 971 | 0 | 0 | 1 |1| R |Meth=0 | TID=1234 | 972 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 973 | Type=1 |1| Len = 11 | "temperature" (11 Octets) ... 974 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 976 CLIENT SERVER 977 | | 978 | <-------- 200 OK [TID=1234] --------- | 979 | | 981 0 1 2 3 982 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 983 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 984 | 0 | 1 | 0 | R | Code=0 | TID=1234 | 985 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 986 | "22.3 C" (6 Octets) ... 987 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 988 Figure 4: Basic request/response 990 TODO: Request with multiple packed messages (magic byte example..) 992 TODO: Request - Response (with retransmission) 994 TODO: Request - Response (discovery) 996 TODO: Request (SUBSCRIBE) - Response ... Resulting Notify - Response 998 10. Security Considerations 1000 TODO: Expand this section to a full security analysis, including how 1001 to use CoAP with various security options. 1003 Some of the features considered in this document will need further 1004 security considerations during a protocol design. For example the 1005 use of string URLs may have entail security risks due to complex 1006 processing on limited microcontroller implementations. 1008 The CoAP protocol will be designed for use with e.g. (D)TLS, IPsec 1009 or object security. A protocol design should consider how 1010 integration with these security methods will be done, how to secure 1011 the CoAP header and other implications. 1013 11. IANA Considerations 1015 TODO (See IANA comments in the document). 1017 11.1. Codes 1019 CoAP makes use of (a subset of) the HTTP status codes defined in 1020 [RFC2616]. The HTTP status code is encoded into a 6-bit unsigned 1021 integer code with the mapping defined in Table 3. The use of these 1022 codes is defined throughout this document using the HTTP Name. 1024 +------+----------------------------+ 1025 | Code | HTTP Name | 1026 +------+----------------------------+ 1027 | 0 | 200 OK | 1028 | 1 | 201 Created | 1029 | 14 | 304 Not Modified | 1030 | 20 | 400 Bad Request | 1031 | 21 | 401 Unauthorized | 1032 | 23 | 403 Forbidden | 1033 | 24 | 404 Not Found | 1034 | 25 | 405 Method Not Allowed | 1035 | 29 | 409 Conflict | 1036 | 35 | 415 Unsupported Media Type | 1037 | 40 | 500 Internal Server Error | 1038 | 43 | 503 Service Unavailable | 1039 | 44 | 504 Gateway Timeout | 1040 +------+----------------------------+ 1042 Table 3: CoAP Codes 1044 11.2. Content Types 1046 Internet media types are identified by a string in HTTP, such as 1047 "application/xml". This string is made up of a top-level type 1048 "application" and a sub-type "xml" [RFC2046]. In order to minimize 1049 the overhead of using these media types to indicate the type of 1050 message payload, CoAP defines an identifier encoding scheme for a 1051 subset of Internet media types. It is expected that this table of 1052 identifiers will be extensible and maintained by IANA. 1054 The Content-type Option is formatted as a variable length unsigned 1055 integer, thus the most common media types are encoded into an 8-bit 1056 unsigned integer. This identifier is encoded as follows. Regardless 1057 of the length of the integer, the most significant 3 bits indicates 1058 the top-level media type (text, application etc.) as defined in 1059 Table 4. The five initial top-level types defined in [RFC2046] are 1060 supported. Composite high-level types (multipart and message) are 1061 not supported. The remaining bits indicate the sub-types [RFC2046]. 1062 This allows for up to 8 high-level types, with up to 32 sub-types for 1063 each in an 8-bit identifier and up to 8192 sub-types in a 16-bit 1064 identifier. 1066 For example, "application/xml" would be encoded in 8-bits as: 1068 5 << 5 | 00 = 10100000 1069 +----------------+------------+ 1070 | Top-level type | Identifier | 1071 +----------------+------------+ 1072 | text | 1 | 1073 | image | 2 | 1074 | audio | 3 | 1075 | video | 4 | 1076 | application | 5 | 1077 +----------------+------------+ 1079 Table 4: Top-level type identifiers 1081 +----------+------------+ 1082 | Sub-type | Identifier | 1083 +----------+------------+ 1084 | xml | 0 | 1085 | plain | 1 | 1086 | csv | 2 | 1087 | html | 3 | 1088 +----------+------------+ 1090 Table 5: text sub-type identifiers 1092 +----------+------------+ 1093 | Sub-type | Identifier | 1094 +----------+------------+ 1095 | gif | 0 | 1096 | jpeg | 1 | 1097 | png | 2 | 1098 | tiff | 3 | 1099 +----------+------------+ 1101 Table 6: image sub-type identifiers 1103 +----------+------------+ 1104 | Sub-type | Identifier | 1105 +----------+------------+ 1106 | raw | 0 | 1107 +----------+------------+ 1109 Table 7: audio sub-type identifiers 1110 +----------+------------+ 1111 | Sub-type | Identifier | 1112 +----------+------------+ 1113 | raw | 0 | 1114 +----------+------------+ 1116 Table 8: video sub-type identifiers 1118 +------------------+------------+ 1119 | Sub-type | Identifier | 1120 +------------------+------------+ 1121 | xml | 0 | 1122 | octet-stream | 1 | 1123 | rdf+xml | 2 | 1124 | soap+xml | 3 | 1125 | atom+xml | 4 | 1126 | xmpp+xml | 5 | 1127 | exi | 6 | 1128 | x-bxml | 7 | 1129 | fastinfoset | 8 | 1130 | soap+fastinfoset | 9 | 1131 | json | 10 | 1132 +------------------+------------+ 1134 Table 9: application sub-type identifiers 1136 12. Acknowledgments 1138 Thanks to Carsten Bormann, Michael Stuber, Richard Kelsey, Cullen 1139 Jennings, Guido Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa 1140 Dussealt, Alexey Melnikov, Gilbert Clark, Salvatore Loreto, Petri 1141 Mutka, Szymon Sasin, Robert Quattlebaum, Robert Cragie, Angelo 1142 Castellani, Tom Herbst and David Ryan for helpful comments and 1143 discussions. 1145 13. Changelog 1147 Changes from shelby-01 to ietf-00: 1149 o Removed the TCP binding section, left open for the future. 1151 o Fixed a bug in the example. 1153 o Marked current Sub/Notify as (Experimental) while under WG 1154 discussion. 1156 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 1157 CoAP-CoAP proxying to work). 1159 o Temporarily removed the Magic Byte header as TCP is no longer 1160 included as a binding. 1162 o Removed the Uri-code Option as different URI encoding schemes 1163 are being discussed. 1165 o Changed the rel= field to desc= for resource discovery. 1167 o Changed the maximum message size to 1024 bytes to allow for IP/ 1168 UDP headers. 1170 o Made the URI slash optimization and method impotence MUSTs 1172 o Minor editing and bug fixing. 1174 Changes from shelby-00 to shelby-01: 1176 o Unified the message header and added a notify message type. 1178 o Renamed methods with HTTP names and removed the NOTIFY method. 1180 o Added a number of options field to the header. 1182 o Combines the Option Type and Length into an 8-bit field. 1184 o Added the magic byte header. 1186 o Added new Etag option. 1188 o Added new Date option. 1190 o Added new Subscription option. 1192 o Completed the HTTP Code - CoAP Code mapping table appendix. 1194 o Completed the Content-type Identifier appendix and tables. 1196 o Added more simplifications for URI support. 1198 o Initial subscription and discovery sections. 1200 o A Flag requirements simplified. 1202 14. References 1203 14.1. Normative References 1205 [I-D.frank-6lowapp-chopan] 1206 Frank, B., "Chopan - Compressed HTTP Over PANs", 1207 draft-frank-6lowapp-chopan-00 (work in progress), 1208 September 2009. 1210 [I-D.nottingham-http-link-header] 1211 Nottingham, M., "Web Linking", 1212 draft-nottingham-http-link-header-09 (work in progress), 1213 April 2010. 1215 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1216 Extensions (MIME) Part Two: Media Types", RFC 2046, 1217 November 1996. 1219 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1220 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1221 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1223 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1224 Resource Identifier (URI): Generic Syntax", STD 66, 1225 RFC 3986, January 2005. 1227 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 1228 (TLS) Protocol Version 1.1", RFC 4346, April 2006. 1230 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1231 Security", RFC 4347, April 2006. 1233 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1234 Uniform Resource Identifiers (URIs)", RFC 5785, 1235 April 2010. 1237 14.2. Informative References 1239 [I-D.cheshire-dnsext-multicastdns] 1240 Cheshire, S. and M. Krochmal, "Multicast DNS", 1241 draft-cheshire-dnsext-multicastdns-11 (work in progress), 1242 March 2010. 1244 [I-D.shelby-6lowapp-encoding] 1245 Shelby, Z., Luimula, M., and D. Peintner, "Efficient XML 1246 Encoding and 6LowApp", draft-shelby-6lowapp-encoding-00 1247 (work in progress), October 2009. 1249 [I-D.shelby-core-coap-req] 1250 Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R. 1252 Kelsey, "CoAP Requirements and Features", 1253 draft-shelby-core-coap-req-01 (work in progress), 1254 April 2010. 1256 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 1257 "Transmission of IPv6 Packets over IEEE 802.15.4 1258 Networks", RFC 4944, September 2007. 1260 Authors' Addresses 1262 Zach Shelby 1263 Sensinode 1264 Kidekuja 2 1265 Vuokatti 88600 1266 FINLAND 1268 Phone: +358407796297 1269 Email: zach@sensinode.com 1271 Brian Frank 1272 SkyFoundry 1273 Richmond, VA 1274 USA 1276 Phone: 1277 Email: brian@skyfoundry.com 1279 Don Sturek 1280 Pacific Gas & Electric 1281 77 Beale Street 1282 San Francisco, CA 1283 USA 1285 Phone: +1-619-504-3615 1286 Email: d.sturek@att.net