idnits 2.17.1 draft-shelby-core-coap-01.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 : ---------------------------------------------------------------------------- ** 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 202: '.... For a UDP binding the A Flag SHOULD...' RFC 2119 keyword, line 204: '...1.1). The A Flag MAY be unset for TCP...' RFC 2119 keyword, line 206: '...The Method field MUST be set with a va...' RFC 2119 keyword, line 213: '...agic byte header MUST be included if m...' RFC 2119 keyword, line 224: '... o The Version Field MUST be 0....' (74 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. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 10, 2010) is 5100 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == 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 == Outdated reference: A later version (-04) exists of draft-shelby-core-coap-req-01 Summary: 6 errors (**), 0 flaws (~~), 6 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: Informational B. Frank 5 Expires: November 11, 2010 SkyFoundry 6 D. Sturek 7 Pacific Gas & Electric 8 May 10, 2010 10 Constrained Application Protocol (CoAP) 11 draft-shelby-core-coap-01 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 kbps. CoAP provides request/reply and 22 subscribe/notify interaction models between appliciation 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 November 11, 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 This document may contain material from IETF Documents or IETF 68 Contributions published or made publicly available before November 69 10, 2008. The person(s) controlling the copyright in some of this 70 material may not have granted the IETF Trust the right to allow 71 modifications of such material outside the IETF Standards Process. 72 Without obtaining an adequate license from the person(s) controlling 73 the copyright in such materials, this document may not be modified 74 outside the IETF Standards Process, and derivative works of it may 75 not be created outside the IETF Standards Process, except to format 76 it for publication as an RFC or to translate it into languages other 77 than English. 79 Table of Contents 81 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 82 2. Constrained Application Protocol . . . . . . . . . . . . . . . 4 83 2.1. Interaction Model . . . . . . . . . . . . . . . . . . . . 4 84 2.1.1. Request messages . . . . . . . . . . . . . . . . . . . 5 85 2.1.2. Notify messages . . . . . . . . . . . . . . . . . . . 6 86 2.1.3. Response message . . . . . . . . . . . . . . . . . . . 6 87 2.1.4. Option fields . . . . . . . . . . . . . . . . . . . . 7 88 2.1.5. Transaction IDs . . . . . . . . . . . . . . . . . . . 7 89 2.2. Methods . . . . . . . . . . . . . . . . . . . . . . . . . 7 90 2.2.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 7 91 2.2.2. POST . . . . . . . . . . . . . . . . . . . . . . . . . 8 92 2.2.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 8 93 2.2.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . . 8 94 2.2.5. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . 8 95 2.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 96 2.4. CoAP Codes . . . . . . . . . . . . . . . . . . . . . . . . 10 97 2.5. Content-type encoding . . . . . . . . . . . . . . . . . . 10 98 3. Message Formats . . . . . . . . . . . . . . . . . . . . . . . 10 99 3.1. CoAP magic byte header . . . . . . . . . . . . . . . . . . 10 100 3.2. CoAP header . . . . . . . . . . . . . . . . . . . . . . . 12 101 3.3. Header options . . . . . . . . . . . . . . . . . . . . . . 14 102 3.3.1. Content-type Option . . . . . . . . . . . . . . . . . 16 103 3.3.2. Uri Option . . . . . . . . . . . . . . . . . . . . . . 17 104 3.3.3. Uri-code Option . . . . . . . . . . . . . . . . . . . 17 105 3.3.4. Max-age Option . . . . . . . . . . . . . . . . . . . . 17 106 3.3.5. Etag Option . . . . . . . . . . . . . . . . . . . . . 17 107 3.3.6. Date Option . . . . . . . . . . . . . . . . . . . . . 17 108 3.3.7. Subscription-lifetime Option . . . . . . . . . . . . . 18 109 4. Transport Binding . . . . . . . . . . . . . . . . . . . . . . 18 110 4.1. UDP . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 111 4.1.1. Retransmission . . . . . . . . . . . . . . . . . . . . 19 112 4.2. Datagram TLS . . . . . . . . . . . . . . . . . . . . . . . 19 113 4.3. TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 114 4.4. TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 115 4.5. Default Port . . . . . . . . . . . . . . . . . . . . . . . 20 116 5. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 117 5.1. Cache control . . . . . . . . . . . . . . . . . . . . . . 21 118 5.2. Cache refresh . . . . . . . . . . . . . . . . . . . . . . 21 119 5.3. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 22 120 6. Resource Discovery . . . . . . . . . . . . . . . . . . . . . . 22 121 6.1. Link Format . . . . . . . . . . . . . . . . . . . . . . . 23 122 7. HTTP Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 24 123 8. Protocol Constants . . . . . . . . . . . . . . . . . . . . . . 24 124 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 125 10. Security Considerations . . . . . . . . . . . . . . . . . . . 27 126 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 127 11.1. Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 27 128 11.2. Content Types . . . . . . . . . . . . . . . . . . . . . . 28 129 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 130 13. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 30 131 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 132 14.1. Normative References . . . . . . . . . . . . . . . . . . . 30 133 14.2. Informative References . . . . . . . . . . . . . . . . . . 31 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32 136 1. Introduction 138 The use of web services on the Internet has become ubiquitous in most 139 applications, and depends on the fundamental Representational State 140 Transfer (REST) architecture of the web. The proposed Constrained 141 RESTful Environments (CoRE) working group aims at realizing the REST 142 architecture in a suitable form for the most constrained nodes (e.g. 143 8-bit microcontrollers with limited RAM and ROM) and networks (e.g. 144 6LoWPAN). One of the main goals of CoRE is to design a generic 145 RESTful protocol for the special requirements of this constrained 146 environment, especially considering energy and building automation 147 applications. 149 This document specifies the RESTful Constrained Application Protocol 150 (CoAP) which easily translates to HTTP for integration with the web 151 while meeting specialized requirements such as multicast support, 152 very low overhead and simplicity for constrained environments 153 [I-D.shelby-core-coap-req]. CoAP has the following main features: 155 o RESTful protocol design minimizing the complexity of mapping with 156 HTTP. 158 o Low header overhead and parsing complexity. 160 o URI and Content-type support. 162 o Support for the discovery of resources provided by known CoAP end- 163 points. 165 o Simple subscription for a resource and a resulting notification 166 mechanism. 168 o Simple caching based on max-age. 170 The mapping of CoAP with HTTP is defined, allowing proxies to be 171 built providing access to CoAP resources via HTTP in a uniform way. 173 2. Constrained Application Protocol 175 This section specifies the basic functionality and processing rules 176 of CoAP. 178 2.1. Interaction Model 180 The interaction model of CoAP is client/server with request or notify 181 messages initiating a transaction responded to with a matching 182 response based on a transaction ID if the A bit is set. Machine-to- 183 machine interactions with RESTful design typically result in a CoAP 184 implementation acting in both client and server roles. A CoAP 185 request is equivalent to an HTTP request, and is sent by a client to 186 request an action (using a method) on a resource (identified by a 187 URI) on a server. A CoAP notify is the inverse of a request, where a 188 server sends a notify message to a client about a resource on the 189 server (identified by a URI). A notify includes the representation, 190 Etag and/or Date of the resource. Examples message exchanges can be 191 found from Section 9. 193 This document specifies the interaction of two CoAP end-point acting 194 as a client or server. We can consider an end-point of CoAP to be an 195 application process using one source port for sending or receiving 196 CoAP messages. Thus a host may run any number of CoAP end-points. 198 2.1.1. Request messages 200 A CoAP end-point acting as a client sends a request with the 201 following rules. The Version field is set to 0. The Type Flag is 202 set to 0 indicating a request. For a UDP binding the A Flag SHOULD 203 be set requesting a response and enabling retransmission in case of 204 timeout (see Section 4.1.1). The A Flag MAY be unset for TCP 205 bindings or for a UDP binding where reliability is too costly or not 206 useful. The Method field MUST be set with a value of 0-4. The 207 TRANSACTION_ID variable is increased by one, and this value is placed 208 in the Transaction ID Field. See Section 2.1.4 for options rules. 210 If a payload is to be included in the message, it immediately follows 211 the last option or the Transaction ID if none. If a magic byte 212 header is included, its Length value indicates the length of the 213 message in octets. A magic byte header MUST be included if multiple 214 messages are packed into a single UDP datagram or over TCP. 216 For each request sent with the A flag set, a CoAP end-point keeps 217 track of the destination IP address and Transaction ID of the request 218 for the purpose of matching responses. For unicast destination over 219 UDP, the retransmission procedure is described in Section 4.1.1. 221 Upon receiving a request, a CoAP end-point performs the following 222 validation and processing: 224 o The Version Field MUST be 0. 226 o The Type Flag MUST be 0. 228 o The Method Field MUST be 0-4. 230 o If the Number of Options Field is > 0, then each option is 231 validated and processed as in Section 2.1.4. 233 o The length of the Payload is taken from the Content-length 234 Option or calculated from the datagram length otherwise. 236 o The Method, URI, any options and Payload are passed on to the 237 corresponding application process. 239 o If the A bit is set, an appropriate response message MUST be 240 sent to the source IPv6 address and port of the request with the 241 same Transaction ID of the request. If the A bit is unset, a 242 response message MUST NOT be sent. 244 TODO: Define the behavior on failure. Error or silent discard? 246 2.1.2. Notify messages 248 The sending of a notify message is similar to sending a request 249 message, with the following difference: The Type Flag is set to 2. 250 The processing of a notify message is similar to processing a request 251 message. 253 2.1.3. Response message 255 A response message is created with the following rules. The Version 256 Field is set to 0. The Type Flag is set to 1. The Code is set to 257 one of the supported response codes in Section 11.1. The Transaction 258 ID MUST be set to that of the corresponding request. See 259 Section 2.1.4 for options rules. An optional Payload may be included 260 as appropriate for the request. 262 Upon receiving a response, a CoAP end-point performs the following 263 validation and processing: 265 o The Version Field MUST be 0. 267 o The Type Flag MUST be 1. 269 o The Code Field MUST contain a valid code. 271 o If the Number of Options Field is > 0, then each option is 272 validated and processed as in Section 2.1.4. 274 o The length of the Payload is taken from the Content-length 275 Option or calculated from the datagram length otherwise. 277 o The Transaction ID is used to match the response to an open 278 request entry, and the response code, any options and Payload are 279 passed on to the corresponding application process. If no match 280 is found, the message is silently discarded. 282 TODO: Define the behavior on failure. Error or silent discard? 284 2.1.4. Option fields 286 If no options are to be included, the Option Number Field is set to 0 287 and the Payload (if any) immediately follows the Transaction ID. If 288 options are to be included, the following rules apply. The number of 289 options is placed in the Number of Options Field. Each option is 290 then placed in order of Type, immediately following the Transaction 291 ID with no padding. Unknown options MUST be silently skipped. 293 TODO: Option validation and processing. 295 2.1.5. Transaction IDs 297 The Transaction ID is a unique unsigned integer kept by a CoAP end- 298 point for all of the CoAP request or notify messages it sends. Each 299 CoAP end-point keeps a single Transaction ID variable, which is 300 changed each time a new request or notify message is sent regardless 301 of the destination address or port. The Transaction ID is used to 302 match a response with an outstanding request or notify, for 303 retransmission and to discard duplicate messages. The initial 304 Transaction ID should be randomized. 306 2.2. Methods 308 CoAP supports the basic RESTful methods of GET, POST, PUT, DELETE, 309 which are easily mapped to HTTP methods. In this section each method 310 is defined along with its behavior. In addition, CoAP defines a new 311 SUBSCRIBE method for requesting soft-state subscriptions for 312 resources. 314 As CoAP methods manipulate resources, they have the same properties 315 of safe (only retrieval) and idempotent (you can invoke it multiple 316 times with the same effects) as HTTP Section 9.1 [RFC2616]. The GET 317 method is safe, therefore it SHOULD NOT take any other action on a 318 resource other than retrieval. The GET, PUT and DELETE methods can 319 be considered idempotent. 321 2.2.1. GET 323 The GET method retrieves the information of the resource identified 324 by the request URI. Upon success a 200 (OK) response SHOULD be sent. 326 All GET requests MUST be idempotent in that they produce no side- 327 effects. 329 The response to a GET is cacheable if it meets the requirements in 330 Section 5. 332 2.2.2. POST 334 The POST method is used to request the server to create a new 335 resource under the requested URI. If a resource has been created on 336 the server, the response should be 201 (Created) including the URI of 337 the new resource in the header and any possible status in the message 338 body. If the POST does not result in a new resource being created on 339 the server, a 200 (OK) response code is returned. 341 Responses to this method are not cacheable. 343 2.2.3. PUT 345 The PUT method requests that the resource identified by the request 346 URI be updated with the enclosed message body. If a resource exists 347 at that URI the message body SHOULD be considered a modified version 348 of that resource. If no resource exists then the server MAY create a 349 new resource with that URI. 351 All PUT requests MUST be idempotent in that they produce no side- 352 effects. 354 Responses to this method are not cacheable. 356 2.2.4. DELETE 358 The DELETE method requests that the resource identified by the 359 request URI be deleted. The response 200 (OK) SHOULD be sent on 360 success. 362 All DELETE requests MUST be idempotent in that they produce no side- 363 effects. 365 Responses to this method are not cacheable. 367 2.2.5. SUBSCRIBE 369 CoAP supports a built-in subscribe/notify push model for an end-point 370 to notify another end-point about a resource of interest. This push 371 is accomplished using the CoAP notify message type, whose URI 372 corresponds to the resource of interest on the end-point sending the 373 notify message. A notify may include the latest representation of 374 the resource in its payload and/or the Etag Option. 376 The SUBSCRIBE method allows an end-point to request notifications 377 about a resource. A request of this method MAY include the 378 Subscription-lifetime Option defined in Section 3.3.7. In the 379 absence of this Option, its maximum lifetime is assumed. End-points 380 MUST NOT send notify messages without a valid subscription. 381 Subscriptions are soft-state, and must be refreshed by sending a new 382 SUBSCRIBE message before the end of its lifetime. 384 Servers keep track of subscriptions its resources, and upon change a 385 notify message is sent to the source address and port of the original 386 SUBSCRIBE request with the URI of the resource in question. 387 Notifications MAY be sent with the A bit set, enabling a server to 388 detect if a subscriber is no longer valid. A subscription SHOULD be 389 removed after MAX_RETRANSMIT failures when the A bit is set. A 390 server is not required to support subscriptions for its resources, 391 and MAY limit the number of simultaneous subscriptions. 393 2.3. URIs 395 The Universal Resource Identifier (URI) [RFC3986] is an important 396 feature of the REST architecture, where the relative part of the URI 397 indicates which resource is being manipulated. CoAP supports 398 variable-length string URIs with the Uri Option. As this URI is used 399 as a locator, CoAP only supports Universal Resource Locator features 400 of [RFC3986] although throughout the document we refer to URI. CoAP 401 supports relative references in the Uri Option (e.g. /sensors/ 402 temperature) for messages to a CoAP end-point, and absolute URIs for 403 use with a proxy (coap://2001:1ba3::450a/sensors/temperature), and 404 does not support "." and ".." schemes. A CoAP implementation MAY 405 support query "?" processing if needed, however fragment "#" 406 processing is not supported. IRIs are not supported. All URI 407 strings in CoAP MUST use the US-ASCII encoding defined in [RFC3986]. 409 The CoAP protocol scheme is identified in URIs with "coap://" (TODO: 410 IANA considerations). 412 All resources URIs MUST begin with a leading "/" slash character. 413 During transmission of the URI in the Uri header, the leading slash 414 MAY be omitted. If the Uri header does start with a "/" leading 415 slash, then it is implied. 417 TODO: Describe the use of binary URI codes and the Uri-code Option. 419 2.4. CoAP Codes 421 When a response message is sent in response to a request or notify 422 message it MUST always include a response code in the header. Notify 423 messages also include a code field, which is set to "200 OK" by 424 default. CoAP makes use of a subset of HTTP response codes as 425 defined in Section 11.1. 427 2.5. Content-type encoding 429 In order to support heterogeneous uses, CoAP is transparent to the 430 use of different application payloads. In order for the application 431 process receiving a packet to properly parse a payload, its content- 432 type should be explicitly known from the header (as e.g. with HTTP). 433 The use of typical binary encodings for XML is discussed in 434 [I-D.shelby-6lowapp-encoding]. 436 It is obvious that string names of Internet media types [RFC2046] are 437 not appropriate for use in the CoAP header. Instead, CoAP simply 438 assigns identifiers to a subset of common MIME and content transfer 439 encoding types. The content-type identifier is optionally included 440 in the Content-type Option Header of messages to indicate the type of 441 the message body. CoAP Content-type identifiers are defined in 442 Section 11.2. 444 3. Message Formats 446 CoAP makes use of three message types - request, notify and response, 447 using a simple binary header format. This base header may be 448 followed by options in Type-Length-Value (TLV) format. CoAP is by 449 default bound to UDP and optionally to TCP as described in Section 4. 450 In addition, a CoAP magic byte header is used when multiple messages 451 are packed into a UDP payload and over TCP. 453 Any bytes after the headers in the packet are considered the message 454 payload, if any. The length of the message payload is implied by the 455 datagram length or the Length Field of the magic byte header if 456 included. When bound to UDP the entire message MUST fit within a 457 single datagram. When used with 6LoWPAN [RFC4944], messages SHOULD 458 fit into a single 802.15.4 frame to minimize fragmentation. 460 3.1. CoAP magic byte header 462 This section defines the CoAP magic byte header shown in Figure 1. 463 This header provides a clear delimiter between CoAP messages and the 464 total message length. The magic byte header MUST be included before 465 the CoAP header when packing multiple messages in a single UDP 466 datagram or over a TCP connection, and MAY be included otherwise. 468 Template: 470 0 471 0 1 2 3 4 5 6 7 8 472 +-+-+-+-+-+-+-+-+-+ 473 | 'r' |X| 474 +-+-+-+-+-+-+-+-+-+ 476 Length of 0-127: 478 0 1 2 3 479 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 480 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 481 | 'r' |0| Length | CoAP header ... 482 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 484 Length of 128-32768: 486 0 1 2 3 487 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 488 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 489 | 'r' |1| Length | CoAP header ... 490 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 492 Figure 1: CoAP magic byte header 494 'r': CoAP magic byte which is US-ASCII character 'r' = 0x72 = 495 0b01110010. The magic byte 'r' stands for RESTful :-) 497 X: 1-bit Extended Length Flag. When 0 the Length is a 7-bit unsigned 498 integer. When 1 the Length Field is extended by an octet and 499 Length Field is a 15-bit unsigned integer. 501 Len: Length Field. When X is 0 Length is a 7-bit unsigned integer 502 allowing values of 0-127 octets. When X is 1 Length is a 15-bit 503 unsigned integer allowing values of 128-32767 octets. The Length 504 field indicates the length of the CoAP message following the 505 Length Field in octets. 507 CoAP header The CoAP header immediately follows the Length Field. 509 3.2. CoAP header 511 This section defines the CoAP header, which is shared for all message 512 types. 514 Request: A CoAP request message is sent by a client to request a URI 515 on a server using one of the methods listed in Table 1. 517 Notify: A CoAP notify message is sent by a server to notify a client 518 about a resource (identified by a URI) on the server as a result 519 of a valid subscription for that resource. 521 Response: A CoAP response message is sent in response to a CoAP 522 request or notify when appropriate. Responses include a 523 Transaction ID corresponding to that of the request. A response 524 is always sent when the A flag is set in a request, and is never 525 sent when the A flag is not set. A response is always sent to the 526 source IP address and port of the corresponding request or notify. 528 Template: 530 0 1 2 3 531 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 532 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 533 |Ver| T | O | Type Specific | Transaction ID | 534 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 535 | Options (if any) ... 536 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 537 | Payload (if any) ... 538 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 540 Request (T=0): 542 0 1 2 3 543 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 544 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 545 |Ver|0 0| O |A| R | Meth | Transaction ID | 546 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 547 | Options (if any) ... 548 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 549 | Payload (if any) ... 550 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 552 Response (T=1): 554 0 1 2 3 555 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 556 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 557 |Ver|0 1| O | R | Code | Transaction ID | 558 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 559 | Options (if any) ... 560 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 561 | Payload (if any) ... 562 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 564 Notify (T=2): 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 |Ver|1 0| O |A|R| Code | Transaction ID | 570 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 571 | Options (if any) ... 572 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 573 | Payload (if any) ... 574 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 576 Figure 2: CoAP header format 578 Header Fields: 580 Ver: Version. 2-bit unsigned integer. Indicates the version of 581 CoAP. Implementations of this specification MUST set this 582 field to 0. The values 1-3 are reserved for future versions. 584 T: 2-bit Message Type flag. Indicates if this message is a CoAP 585 request (0), response (1) or notify (2) header. The value 3 is 586 forbidden to avoid collision with the magic byte 'r'. 588 O: 4-bit Number of Options field. Indicates if there are Option 589 Headers following the base header. If set to 0 the payload (if 590 any) immediately follows the base header. If greater than zero 591 the field indicates the number of options to immediately follow 592 the header. 594 A: 1-bit Acknowledgement flag. When set to 1, indicates that the 595 destination MUST respond with a response message matching this 596 request (see Section 4.1). When set to 0, the destination MUST 597 NOT send a response to this request. 599 Meth: 4-bit unsigned integer. This field indicates the CoAP 600 Method of the request according to Table 1. Methods are 601 described in detail in Section 2.2. 603 Code: 6-bit unsigned integer. This field indicates the code of a 604 response or notify message as defined in Section 11.1. 606 Transaction ID: 16-bit unsigned integer. A unique Transaction ID 607 assigned by the source and used to match responses. The 608 Transaction ID MUST be changed for each new request (regardless 609 of the end-point) and MUST NOT be changed when retransmitting a 610 request. 612 R: This field is unused. It MUST be initialized to zero by the 613 sender and MUST be ignored by the receiver. 615 +-----------+------+ 616 | Method | Code | 617 +-----------+------+ 618 | GET | 0 | 619 | POST | 1 | 620 | PUT | 2 | 621 | DELETE | 3 | 622 | SUBSCRIBE | 4 | 623 +-----------+------+ 625 Table 1: Method codes 627 3.3. Header options 629 CoAP messages may also include one or more header options in TLV 630 format. Each option has the following format: 632 Template: 634 0 635 0 1 2 3 4 5 636 +-+-+-+-+-+-+ 637 | Type |X| 638 +-+-+-+-+-+-+ 640 Length of 0-4: 642 0 1 2 3 643 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 644 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 645 | Type |0|Len| Option Value ... 646 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 648 Length of 5-1024: 650 0 1 2 3 651 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 652 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 653 | Type |1| Len | Option Value ... 654 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 656 Figure 3: Header option format 658 Type: 5-bit unsigned integer. The type of the option as defined in 659 Table 2, allowing for up to 32 options. Future specifications may 660 define new CoAP option types. Option types 30-32 are reserved for 661 experimental purposes. 663 X: 1-bit Extended Length Flag. When 0 the Length is a 2-bit unsigned 664 integer. When 1 the option header is extended by an octet and 665 Length is a 10-bit unsigned integer. 667 Len: Length Field. When X is 0 Length is a 2-bit unsigned integer 668 allowing values of 0-4 octets. When X is 1 Length is a 10-bit 669 unsigned integer allowing values of 5-1024 octets. 671 Option Value The value in the format defined for that option in 672 Table 2 with a length of Option Len octets. Options may use 673 variable length unsigned integer values of Len Field octets in 674 network byte order as shown in Figure 4. 676 0 677 0 1 2 3 4 5 6 7 678 +-+-+-+-+-+-+-+-+ 679 Len = 1 | 0-255 | 680 +-+-+-+-+-+-+-+-+ 682 0 1 683 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 684 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 685 Len = 2 | 0-65535 | 686 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 688 Len = 3 is 24 bits, Len = 4 is 32 bits etc. 690 Figure 4: Variable length unsigned integer value format 692 The following options are defined in this document. 694 +------+-----------------------+-----------+---------+--------------+ 695 | Type | Name | Data type | Length | Rules | 696 +------+-----------------------+-----------+---------+--------------+ 697 | 0 | Content-type | Variable | 1-2 B | | 698 | | | uint | | | 699 | 1 | Uri | String | 1-32768 | Never in | 700 | | | | B | response | 701 | 2 | Uri-code | Variable | 1-2 B | Never with | 702 | | | uint | | Uri Option | 703 | 3 | Max-age | Variable | 1-4 B | | 704 | | | uint | | | 705 | 4 | Etag | Variable | 1-4 B | | 706 | | | uint | | | 707 | 5 | Date | Variable | 4-6 B | Never in | 708 | | | integer | | request | 709 | 6 | Subscription-lifetime | Variable | 1-3 B | With | 710 | | | uint | | SUBSCRIBE or | 711 | | | | | its response | 712 +------+-----------------------+-----------+---------+--------------+ 714 Table 2: Option headers 716 3.3.1. Content-type Option 718 The Content-type Identifier Option indicates the Internet Media Type 719 of the message-body, see Section 11.2 for the encoding and identifier 720 tables. A Content-type Identifier Option SHOULD be included if there 721 is a payload included with a CoAP message, and MUST not be included 722 for a zero-length payload. 724 3.3.2. Uri Option 726 The Uri Option indicates the string URI of the resource that may be 727 included in request and notify messages. In the absence of this 728 option, the URI is assumed to be "/". Section 2.3 specifies the 729 rules for URIs in CoAP. 731 3.3.3. Uri-code Option 733 The Uri-code Option is used as an alternative to the Uri Option, and 734 indicates a variable length code assigned globally to well-known URI 735 strings or by the CoAP end-point in a link description entry "code" 736 field (see Section 6). The Uri-code Option MUST NOT be used at the 737 same time as the Uri Option. If both options appear in a message 738 then the Uri-code Option is ignored. 740 3.3.4. Max-age Option 742 The Max-age Option indicates the maximum age of the resource for use 743 in cache control in seconds. The option is represented as a variable 744 length unsigned integer maximum 32-bits in length. 746 When included in a request, Max-age indicates the maximum age of a 747 cached representation of that resource the client will accept. When 748 included in a response or a notify, Max-age indicates the maximum 749 time the representation may be cached before it MUST be discarded. 751 3.3.5. Etag Option 753 The Etag Option is a variable length unsigned integer which specifies 754 the version of a resource representation. An Etag may be generated 755 for a resource in any number of ways including a version, checksum, 756 hash or time. An end-point receiving an Etag MUST treat it as opaque 757 and make no assumptions about its format. The Etag MAY be included 758 in a notify message to indicate to a client if a resource has 759 changed. 761 3.3.6. Date Option 763 The Date Option indicates the creation time and date of a given 764 resource representation. It MAY be used in response and notify 765 messages. The integer value is the number of seconds, excluding leap 766 seconds, after midnight UTC, January 1, 1970. This time format 767 cannot represent time values prior to January 1, 1970. The latest 768 UTC time value that can be represented by a 31 bit integer value is 769 03:14:07 on January 19, 2038. Time values beyond 03:14:07 on January 770 19, 2038, are represented by 39 bit integer values which is 771 sufficient to represent dates that should be enough for anyone. For 772 applications requiring more accuracy, a 48-bit integer MAY be 773 included representing this value in milliseconds instead of seconds. 775 3.3.7. Subscription-lifetime Option 777 The Subscription-lifetime Option indicates the subscription lifetime 778 and is optionally included with the SUBSCRIBE method (see 779 Section 2.2.5). The corresponding response MUST include a 780 Subscription-lifetime Option confirming (or modifying) the 781 subscription lifetime. 783 The value of this option is a variable length unsigned integer up to 784 24-bits indicating the lifetime of the subscription in seconds with a 785 maximum value of 194 days. In a response the server MAY return a 786 different value that fits its own scheduling better. A value of all 787 0 in a request indicates cancellation of a subscription and in a 788 response indicates subscription failure or rejection. 790 4. Transport Binding 792 The CoAP protocol will operate by default over UDP. There may be 793 optional functions in CoAP (e.g. delivery of larger chunks of data) 794 which if implemented are implemented over TCP. This section defines 795 the binding of CoAP over UDP and TCP. 797 4.1. UDP 799 The goal of binding CoAP to UDP is to provide the bare minimum 800 features for the protocol to operate over UDP, without trying to re- 801 create the full feature set of TCP. CoAP over UDP has the following 802 features: 804 o Simple stop-and-wait retransmission reliability with exponential 805 back-off as described in Section 4.1.1 when the A Flag is set. 807 o Transaction ID for response matching as described in 808 Section 2.1.5. 810 o Multicast support without retransmission. CoAP supports the use 811 of multicast destination addresses when bound to UDP. Although 812 the A bit may be used to force a response, retransmission MUST NOT 813 be performed. 815 When a single CoAP message is sent using UDP, the length of the 816 Payload can be calculated from the datagram length. Multiple CoAP 817 messages MAY also be concatenated in a single UDP payload. In this 818 case each message header MUST be precluded by a magic byte header 819 making the start and length of each message explicit. When multiple 820 messages are packed in a UDP payload, they are processed by the CoAP 821 end-point in order and independently. The responses to packed 822 messages SHOULD also be packed if space permits. 824 When bound to UDP the entire message MUST fit within a single 825 datagram of length 576 octets over IPv4 and 1280 octets over IPv6. 826 When used with 6LoWPAN [RFC4944], messages SHOULD fit into a single 827 link-layer frame to minimize fragmentation (often on the order of 828 60-90 octets). 830 4.1.1. Retransmission 832 A CoAP end-point keeps track of open request or notify messages 833 expecting a response (A Flag set) using a conceptual data structure 834 or entries awaiting a response. Each entry includes at least the 835 destination address and port of the original message, the message 836 itself, a retransmission counter (UDP only) and a timeout. When a 837 request of notify message is sent with the A Flag set, an entry is 838 made for that message with a default initial timeout of 839 RESPONSE_TIMEOUT and the retransmission counter set to 0. When a 840 matching response is received for an entry, the entry is removed. 841 When a timeout is triggered for an entry and the retransmission 842 counter is less than MAX_RETRANSMIT, the original message is 843 retransmitted to the destination without modification, the 844 retransmission counter is incremented, and the timeout is doubled. 845 If the retransmission couter reaches MAX_RETRANSMIT on a timeout, 846 then the entry is removed and the application process informed of 847 delivery failure. 849 For CoAP messages sent to IP multicast addresses, retransmission MUST 850 NOT be performed. Therefore MAX_RETRANSMIT is always set to 0 when 851 the destination address is multicast. 853 4.2. Datagram TLS 855 CoAP may also be bound to Datagram Transport Layer Security [RFC4347] 856 in order to prevent eavesdropping, tampering, or message forgery. 858 TODO: Define the DTLS binding in detail. Expected as a contribution 859 from security people in the WG. Use the simplest possible 860 configuration and AES-128 encryption as this is usually supported by 861 e.g. IEEE 802.15.4 hardware. The current suggestion is to make AES, 862 RSA, and SHA1 mandatory to implement and one with SHA256 RECOMMENDED. 864 4.3. TCP 866 The CoAP protocol also may also be bound to TCP in special cases. As 867 TCP provides a reliable stream this binding does not require anything 868 special from the CoAP protocol design. Retransmission MUST BE 869 disabled, thus MAX_RETRANSMIT is always set to 0. The Transaction ID 870 MUST also be used over TCP and the magic byte header MUST always be 871 included. CoAP end-points are not expected to support both UDP and 872 TCP, and SHOULD NOT attempt to dynamically negotiate between 873 transports. 875 The following cases have been identified where TCP MAY be used: 877 o When an application returns large resource representations, which 878 do not fit in a single datagram. 880 o For providing congestion control if CoAP is being applied across 881 the wider Internet in a topology where congestion is a concern. 883 It should be noted that using a similar configuration. CoAP could be 884 used over other stream media such as serial ports. Such a 885 configuration is however out of scope of this document. 887 4.4. TLS 889 CoAP may also be bound to Transport Layer Security [RFC4346] in order 890 to prevent eavesdropping, tampering, or message forgery. 892 TODO: Define the TLS binding in detail. Expected as a contribution 893 from security people in the WG. Use the simplest possible 894 configuration and AES-128 encryption as this is usually supported by 895 e.g. IEEE 802.15.4 hardware. The current suggestion is to make AES, 896 RSA, and SHA1 mandatory to implement and one with SHA256 RECOMMENDED. 898 4.5. Default Port 900 CoAP has a default port of 61616 (TODO: IANA) which is within the 901 compressed UDP port space defined in [RFC4944]. This default port is 902 the same for UDP and TCP. 904 5. Caching 906 CoAP end-points are by definition constrained by bandwidth and 907 processing power. To optimize the performance of data transfer under 908 these constraints, we leverage caching features consistent with HTTP. 909 Caching includes the following concepts: 911 o cache life of a resource is controlled via the Max-Age header 912 option 914 o cache refresh and versioning of a resource is controlled via the 915 Etag header option 917 o proxies between a client and end-point may participate in the 918 caching process on behalf of sleeping end-points and to avoid 919 unnecessary traffic on the constrained network 921 5.1. Cache control 923 When an end-point publishes a resource for a GET request, it SHOULD 924 specify the Max-Age header option. The Max-Age specifies the cache 925 life of the resource in seconds. Resources which change rapidly will 926 have a short cache life, and resources which change infrequently 927 should specify a long cache life. If Max-Age is unspecified in a GET 928 response, then it is assumed to be 60 seconds. If an end-point 929 wishes to disable caching, it must explicitly specify a Max-Age of 930 zero seconds. 932 When a client reads the response from a GET request, it should cache 933 the resource representation for the cache lifetime as specified by 934 the Max-Age header. During the cache lifetime, the client SHOULD use 935 its cached version and avoid performing additional GETs for the 936 resource. 938 In general, the origin server end-point is responsible for 939 determining cache age. However, in some cases a client may wish to 940 determine its own tolerance for cache staleness. In this case, a 941 client may specify the Max-Age header during a GET request. If the 942 client's Max-Age is of a shorter duration than the age of a cached 943 resource, then the proxy or end-point SHOULD perform a cache refresh. 944 If the client specifies a Max-Age of zero seconds, then the response 945 MUST discard the cached representation and return a fresh 946 representation. 948 5.2. Cache refresh 950 After the expiration of the cache lifetime, clients and proxies must 951 refresh their cached representation of a resource. Cache refresh is 952 accomplished using GET request which will return a representation of 953 the resource's current state. 955 If the end-point has the capability to version the resource, then the 956 end-point should include the Etag header option in the response to a 957 GET request. The Etag is a variable length integer which captures a 958 version checksum of the resource. The Etag is an opaque identifier; 959 clients MUST NOT infer any semantics from the Etag value. 961 If an end-point specifies the Etag header option, then the client 962 SHOULD specify a matching Etag header option in their GET request 963 during cache refresh. If the end-point's version of the resource is 964 unmodified, then it SHOULD specify a 304 response with no payload to 965 avoid retransmitting the resource representation. 967 5.3. Proxying 969 See [I-D.frank-6lowapp-chopan]. 971 TODO: 973 o Are interception proxies are still required to deal with a) 974 sleeping nodes and b) protecting Internet HTTP traffic from 975 overwhelming the CoAP network? 977 o But interception proxies breaks end-to-end IP encapsulation and 978 requires support at the routing level 980 o Often the interception proxy is the same as the HTTP-to-CoAP 981 gateway, so we need to decide how these topics dovetail 983 o In Chopan, the sleeping problem was tackled by having sleeping 984 nodes check-in with their proxies while awake, notify model might 985 solve this problem to some extent but still have to coordinate the 986 sleep/awake times 988 o In Chopan we actually used caching to deal with POSTs, etc because 989 otherwise how do you send a request to a sleeping node? The 990 current caching sections are to be exclusive to GETs, but we still 991 need to solve the problem for other types if methods. 993 6. Resource Discovery 995 The discovery of resources offered by a CoAP end-point is extremely 996 important in machine-to-machine applications where there are no 997 humans in the loop and static interfaces results in fragility. The 998 discovery of resources provided by an HTTP Web Server is called Web 999 Discovery. In this document we refer to the discovery of resources 1000 offered by a CoAP end-point as Resource Discovery. 1002 CoAP makes the assumption that end-points are available on the 1003 default CoAP port, or otherwise have been configured or discovered 1004 using some general service discovery mechanism such as 1005 [I-D.cheshire-dnsext-multicastdns]. This section assumes that such a 1006 configuration or service discovery has already been performed, if 1007 needed. 1009 Resource Discovery in CoAP is accomplished through the use of well- 1010 known resources which describe the links offered by that CoAP end- 1011 point. Well-known resources have the URI form "/.well-known/" as 1012 specified in [RFC5785]. Every CoAP end-point MUST support this well- 1013 known resource. The resource representation of this is described in 1014 Section 6.1. 1016 CoAP requests the following well-known URL for discovery: "/.well- 1017 known/resources" (TODO: Formal description for use in request as per 1018 [RFC5785]). 1020 CoAP Resource Discovery supports the following interactions: 1022 o [request GET /.well-known/resources] returns the list of links 1023 available from a CoAP end-point. 1025 o A CoAP end-point may notify interested clients when this 1026 description has changed by sending [notify /.well-known/ 1027 resources]. This resources MAY support subscription. 1029 o More capable end-points such as proxies MAY support a resource 1030 directory by accepting [request POST /.well-known/resources] 1031 messages from other CoAP end-points. This adds the resources of 1032 other end-points to an agent directory in which absolute URIs are 1033 included for the links. 1035 End-points with a large number of resources SHOULD organize their 1036 resource descriptions into a hierarchy of link resources. This is 1037 done by including links in the /.well-known/resources list which 1038 point to other resource lists, e.g. /.well-known/resources/sensors. 1040 6.1. Link Format 1042 CoAP resource discovery makes use of the HTTP Link Header format 1043 specified in [I-D.nottingham-http-link-header]. This specification 1044 allows for the use of this simple link format by other protocols, 1045 thus not limiting it to the actual HTTP Link Header. The format does 1046 not require special XML or binary parsing, and is extensible. 1048 CoAP defines a subset of the [I-D.nottingham-http-link-header] 1049 features and specific parameters that have known meaning for CoAP 1050 resource discovery. A CoAP end-point MAY make use of link extension 1051 parameters as needed. The CoAP link format does not start with the 1052 "Link:" text. The following formal description is used for forming 1053 and parsing this link format: 1055 link-value = "<" URI-Reference ">" *( ";" link-param ) 1056 link-param = ( ( "rel" "=" URI ) 1057 | ( "name" "=" quoted-string ) 1058 | ( "type" "=" ( media-type | media-code) ) 1059 | ( "id" "=" integer ) 1060 | ( "code" "=" integer ) 1061 | ( link-extension ) ) 1062 link-extension = ( parmname [ "=" ( ptoken | quoted-string ) ] ) 1063 ptoken = 1*ptokenchar 1064 ptokenchar = "!" | "#" | "$" | "%" | "&" | "'" | "(" 1065 | ")" | "*" | "+" | "-" | "." | "/" | DIGIT 1066 | ":" | "<" | "=" | ">" | "?" | "@" | ALPHA 1067 | "[" | "]" | "^" | "_" | "`" | "{" | "|" 1068 | "}" | "~" 1069 media-code = see Appendix B 1070 media-type = type-name "/" subtype-name 1072 The link-value is the relative URI of the resource on that end-point 1073 or an absolute URI in the case of a directory agent. The rel 1074 parameter is a URI that points to the definition of that resource 1075 interface, for example in WADL. The name parameter is a descriptive 1076 or ontology name of the resource class. This name parameter SHOULD 1077 be in an m-DNS [I-D.cheshire-dnsext-multicastdns] compatible form. 1078 The type parameter includes Internet media type this resource returns 1079 in ascii or code format. The id field is a unique identifier (e.g. 1080 UUID) for this resource for use in e.g. search directories. Finally, 1081 the code field is used to identify this resource for reference with 1082 the Uri-code Option. All link parameters are optional and custom 1083 link-extensions may be defined. An example of a typical CoAP link 1084 description in this format would be: 1086 ; rel="sensor.wadl"; name="TemperatureC"; type=text/plain 1087 ; rel="sensor.wadl"; name="LightLux"; type=text/plain 1089 7. HTTP Mapping 1091 TODO. 1093 8. Protocol Constants 1095 This section defines the relevant protocol constants defined in this 1096 document: 1098 RESPONSE_TIMEOUT 0.5 seconds 1100 MAX_RETRANSMIT 5 1102 9. Examples 1104 Figure 5 shows a basic request/response sequence. A client makes a 1105 GET request for the resource /temp to the server. The A Flag is set, 1106 requesting a response and the Transaction ID is 1234. The request 1107 includes one Uri Option "temp" of Len = 4. This request is 9 octets 1108 long. The corresponding response is of code 200 OK and includes a 1109 text/plain Payload of "22.3 C". The Transaction ID is 1234, thus the 1110 transaction is successfully completed. The response is 10 octets 1111 long. 1113 CLIENT SERVER 1114 | | 1115 | ---------- GET /temp [A, TID=1234] --------> | 1116 | | 1118 0 1 2 3 1119 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 1120 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1121 | 0 | 0 | 1 |1| R | 0 | TID=1234 | 1122 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1123 | 1 |0| 4 | "temp" (4 Octets) 1124 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1125 | 1126 +-+-+-+-+-+-+-+-+ 1128 CLIENT SERVER 1129 | | 1130 | <-------- 200 OK [TID=1234] --------- | 1131 | | 1133 0 1 2 3 1134 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 1135 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1136 | 0 | 1 | 0 | R | Code=0 | TID=1234 | 1137 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1138 | "22.3 C" (6 Octets) 1139 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1140 | 1141 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1143 Figure 5: Basic request/response 1145 TODO: Request with multiple packed messages (magic byte example..) 1147 TODO: Request - Response (with retransmission) 1149 TODO: Request - Response (discovery) 1151 TODO: Request - Response (with subscription)... Resulting Notify - 1152 Response 1154 10. Security Considerations 1156 TODO: Expand this section to a full security analysis, including how 1157 to use CoAP with various security options. 1159 Some of the features considered in this document will need further 1160 security considerations during a protocol design. For example the 1161 use of string URLs may have entail security risks due to complex 1162 processing on limited microcontroller implementations. 1164 The CoAP protocol will be designed for use with e.g. (D)TLS or 1165 object security. A protocol design should consider how integration 1166 with these security methods will be done, how to secure the CoAP 1167 header and other implications. 1169 11. IANA Considerations 1171 TODO (See IANA comments in the document). 1173 11.1. Codes 1175 CoAP makes use of (a subset of) the HTTP status codes defined in 1176 [RFC2616]. The HTTP status code is encoded into a 6-bit unsigned 1177 integer code with the mapping defined in Table 3. The use of these 1178 codes is defined throughout this document using the HTTP Name. 1180 +------+----------------------------+ 1181 | Code | HTTP Name | 1182 +------+----------------------------+ 1183 | 0 | 200 OK | 1184 | 1 | 201 Created | 1185 | 14 | 304 Not Modified | 1186 | 20 | 400 Bad Request | 1187 | 21 | 401 Unauthorized | 1188 | 23 | 403 Forbidden | 1189 | 24 | 404 Not Found | 1190 | 25 | 405 Method Not Allowed | 1191 | 29 | 409 Conflict | 1192 | 35 | 415 Unsupported Media Type | 1193 | 40 | 500 Internal Server Error | 1194 | 43 | 503 Service Unavailable | 1195 | 44 | 504 Gateway Timeout | 1196 +------+----------------------------+ 1198 Table 3: CoAP Codes 1200 11.2. Content Types 1202 Internet media types are identified by a string in HTTP, such as 1203 "application/xml". This string is made up of a top-level type 1204 "application" and a sub-type "xml" [RFC2046]. In order to minimize 1205 the overhead of using these media types to indicate the type of 1206 message payload, CoAP defines an identifier encoding scheme for a 1207 subset of Internet media types. It is expected that this table of 1208 identifiers will be extensible and maintained by IANA. 1210 The Content-type Option is formatted as a variable length unsigned 1211 integer, thus the most common media types are encoded into an 8-bit 1212 unsigned integer. This identifier is encoded as follows. Regardless 1213 of the length of the integer, the most significant 3 bits indicates 1214 the top-level media type (text, application etc.) as defined in 1215 Table 4. The five initial top-level types defined in [RFC2046] are 1216 supported. Composite high-level types (multipart and message) are 1217 not supported. The remaining bits indicate the sub-types [RFC2046]. 1218 This allows for up to 8 high-level types, with up to 32 sub-types for 1219 each in an 8-bit identifier and up to 8192 sub-types in a 16-bit 1220 identifier. 1222 For example, "application/xml" would be encoded in 8-bits as: 1224 5 << 5 | 00 = 10100000 1226 +----------------+------------+ 1227 | Top-level type | Identifier | 1228 +----------------+------------+ 1229 | text | 1 | 1230 | image | 2 | 1231 | audio | 3 | 1232 | video | 4 | 1233 | application | 5 | 1234 +----------------+------------+ 1236 Table 4: Top-level type identifiers 1238 +----------+------------+ 1239 | Sub-type | Identifier | 1240 +----------+------------+ 1241 | xml | 0 | 1242 | plain | 1 | 1243 | csv | 2 | 1244 | html | 3 | 1245 +----------+------------+ 1247 Table 5: text sub-type identifiers 1248 +----------+------------+ 1249 | Sub-type | Identifier | 1250 +----------+------------+ 1251 | gif | 0 | 1252 | jpeg | 1 | 1253 | png | 2 | 1254 | tiff | 3 | 1255 +----------+------------+ 1257 Table 6: image sub-type identifiers 1259 +----------+------------+ 1260 | Sub-type | Identifier | 1261 +----------+------------+ 1262 | raw | 0 | 1263 +----------+------------+ 1265 Table 7: audio sub-type identifiers 1267 +----------+------------+ 1268 | Sub-type | Identifier | 1269 +----------+------------+ 1270 | raw | 0 | 1271 +----------+------------+ 1273 Table 8: video sub-type identifiers 1275 +------------------+------------+ 1276 | Sub-type | Identifier | 1277 +------------------+------------+ 1278 | xml | 0 | 1279 | octet-stream | 1 | 1280 | rdf+xml | 2 | 1281 | soap+xml | 3 | 1282 | atom+xml | 4 | 1283 | xmpp+xml | 5 | 1284 | exi | 6 | 1285 | x-bxml | 7 | 1286 | fastinfoset | 8 | 1287 | soap+fastinfoset | 9 | 1288 | json | 10 | 1289 +------------------+------------+ 1291 Table 9: application sub-type identifiers 1293 12. Acknowledgments 1295 Thanks to Carsten Bormann, Michael Stuber, Richard Kelsey, Cullen 1296 Jennings, Guido Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa 1297 Dussealt, Alexey Melnikov, Gilbert Clark, Salvatore Loreto, Petri 1298 Mutka, Szymon Sasin, Robert Quattlebaum, Robert Cragie, Angelo 1299 Castellani and David Ryan for helpful comments and discussions. 1301 13. Changelog 1303 Changes from -00 to -01: 1305 o Unified the message header and added a notify message type. 1307 o Renamed methods with HTTP names and removed the NOTIFY method. 1309 o Added a number of options field to the header. 1311 o Combines the Option Type and Length into an 8-bit field. 1313 o Added the magic byte header. 1315 o Added new Etag option. 1317 o Added new Date option. 1319 o Added new Subscription option. 1321 o Completed the HTTP Code - CoAP Code mapping table appendix. 1323 o Completed the Content-type Identifier appendix and tables. 1325 o Added more simplifications for URI support. 1327 o Initial subscription and discovery sections. 1329 o A Flag requirements simplified. 1331 14. References 1333 14.1. Normative References 1335 [I-D.frank-6lowapp-chopan] 1336 Frank, B., "Chopan - Compressed HTTP Over PANs", 1337 draft-frank-6lowapp-chopan-00 (work in progress), 1338 September 2009. 1340 [I-D.nottingham-http-link-header] 1341 Nottingham, M., "Web Linking", 1342 draft-nottingham-http-link-header-09 (work in progress), 1343 April 2010. 1345 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1346 Extensions (MIME) Part Two: Media Types", RFC 2046, 1347 November 1996. 1349 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1350 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1351 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1353 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1354 Resource Identifier (URI): Generic Syntax", STD 66, 1355 RFC 3986, January 2005. 1357 [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security 1358 (TLS) Protocol Version 1.1", RFC 4346, April 2006. 1360 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1361 Security", RFC 4347, April 2006. 1363 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1364 Uniform Resource Identifiers (URIs)", RFC 5785, 1365 April 2010. 1367 14.2. Informative References 1369 [I-D.cheshire-dnsext-multicastdns] 1370 Cheshire, S. and M. Krochmal, "Multicast DNS", 1371 draft-cheshire-dnsext-multicastdns-11 (work in progress), 1372 March 2010. 1374 [I-D.shelby-6lowapp-encoding] 1375 Shelby, Z., Luimula, M., and D. Peintner, "Efficient XML 1376 Encoding and 6LowApp", draft-shelby-6lowapp-encoding-00 1377 (work in progress), October 2009. 1379 [I-D.shelby-core-coap-req] 1380 Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R. 1381 Kelsey, "CoAP Requirements and Features", 1382 draft-shelby-core-coap-req-01 (work in progress), 1383 April 2010. 1385 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 1386 "Transmission of IPv6 Packets over IEEE 802.15.4 1387 Networks", RFC 4944, September 2007. 1389 Authors' Addresses 1391 Zach Shelby 1392 Sensinode 1393 Kidekuja 2 1394 Vuokatti 88600 1395 FINLAND 1397 Phone: +358407796297 1398 Email: zach@sensinode.com 1400 Brian Frank 1401 SkyFoundry 1402 Richmond, VA 1403 USA 1405 Phone: 1406 Email: brian@skyfoundry.com 1408 Don Sturek 1409 Pacific Gas & Electric 1410 77 Beale Street 1411 San Francisco, CA 1412 USA 1414 Phone: +1-619-504-3615 1415 Email: d.sturek@att.net