idnits 2.17.1 draft-ietf-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 375: '...domized. The same Transaction ID MUST...' RFC 2119 keyword, line 384: '...rted Method Code MUST generate a messa...' RFC 2119 keyword, line 390: '...fe, therefore it MUST NOT take any oth...' RFC 2119 keyword, line 391: '... The GET, PUT and DELETE methods MUST...' RFC 2119 keyword, line 397: '...ss a 200 (OK) response SHOULD be sent....' (72 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2010) is 5034 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) == 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 5785 (Obsoleted by RFC 8615) == Outdated reference: A later version (-11) exists of draft-cheshire-dnsext-dns-sd-06 == Outdated reference: A later version (-01) exists of draft-eggert-core-congestion-control-00 == Outdated reference: A later version (-04) exists of draft-shelby-core-coap-req-01 Summary: 4 errors (**), 0 flaws (~~), 5 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: January 9, 2011 SkyFoundry 6 D. Sturek 7 Pacific Gas & Electric 8 July 8, 2010 10 Constrained Application Protocol (CoAP) 11 draft-ietf-core-coap-01 13 Abstract 15 This document specifies the Constrained Application Protocol (CoAP), 16 a specialized RESTful transfer protocol for use with constrained 17 networks and nodes for machine-to-machine applications such as smart 18 energy and building automation. These constrained nodes often have 19 8-bit microcontrollers with small amounts of ROM and RAM, while 20 networks such as 6LoWPAN often have high packet error rates and a 21 typical throughput of 10s of kbit/s. CoAP provides the REST Method/ 22 Response interaction model between application end-points, supports 23 built-in resource discovery, and includes key web concepts such as 24 URIs and content-types. 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 January 9, 2011. 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 . . . . . . . . . . . . . . . 5 71 2.1. Interaction Model . . . . . . . . . . . . . . . . . . . . 5 72 2.1.1. Synchronous response . . . . . . . . . . . . . . . . . 6 73 2.1.2. Asynchronous response . . . . . . . . . . . . . . . . 6 74 2.2. Transaction messages . . . . . . . . . . . . . . . . . . . 8 75 2.2.1. Confirmable (CON) . . . . . . . . . . . . . . . . . . 8 76 2.2.2. Non-Confirmable (NON) . . . . . . . . . . . . . . . . 8 77 2.2.3. Acknowledgment (ACK) . . . . . . . . . . . . . . . . . 8 78 2.2.4. Reset (RST) . . . . . . . . . . . . . . . . . . . . . 8 79 2.2.5. Transaction IDs . . . . . . . . . . . . . . . . . . . 9 80 2.3. Methods . . . . . . . . . . . . . . . . . . . . . . . . . 9 81 2.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 9 82 2.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . . 9 83 2.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 10 84 2.3.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . . 10 85 2.4. Response Codes . . . . . . . . . . . . . . . . . . . . . . 10 86 2.5. Options . . . . . . . . . . . . . . . . . . . . . . . . . 10 87 2.5.1. Option Processing . . . . . . . . . . . . . . . . . . 10 88 2.5.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . 11 89 2.5.3. Content-type encoding . . . . . . . . . . . . . . . . 11 90 3. Message Formats . . . . . . . . . . . . . . . . . . . . . . . 12 91 3.1. CoAP header . . . . . . . . . . . . . . . . . . . . . . . 12 92 3.2. Header options . . . . . . . . . . . . . . . . . . . . . . 13 93 3.2.1. Content-type Option . . . . . . . . . . . . . . . . . 15 94 3.2.2. Uri-Scheme Option . . . . . . . . . . . . . . . . . . 15 95 3.2.3. Uri-Authority Option . . . . . . . . . . . . . . . . . 16 96 3.2.4. Uri-Path Option . . . . . . . . . . . . . . . . . . . 16 97 3.2.5. Location Option . . . . . . . . . . . . . . . . . . . 16 98 3.2.6. Max-age Option . . . . . . . . . . . . . . . . . . . . 16 99 3.2.7. Etag Option . . . . . . . . . . . . . . . . . . . . . 16 100 4. UDP Binding . . . . . . . . . . . . . . . . . . . . . . . . . 17 101 4.1. Multicast . . . . . . . . . . . . . . . . . . . . . . . . 17 102 4.2. Retransmission . . . . . . . . . . . . . . . . . . . . . . 17 103 4.3. Congestion Control . . . . . . . . . . . . . . . . . . . . 18 104 4.4. Default Port . . . . . . . . . . . . . . . . . . . . . . . 18 105 5. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 106 5.1. Cache control . . . . . . . . . . . . . . . . . . . . . . 19 107 5.2. Cache refresh . . . . . . . . . . . . . . . . . . . . . . 19 108 5.3. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 20 109 6. Resource Discovery . . . . . . . . . . . . . . . . . . . . . . 21 110 6.1. Link Format . . . . . . . . . . . . . . . . . . . . . . . 22 111 6.2. Naming . . . . . . . . . . . . . . . . . . . . . . . . . . 24 112 6.3. Query Filtering . . . . . . . . . . . . . . . . . . . . . 24 113 6.4. HTTP Resource Discovery . . . . . . . . . . . . . . . . . 25 114 7. HTTP Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 25 115 8. Protocol Constants . . . . . . . . . . . . . . . . . . . . . . 26 116 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 117 10. Security Considerations . . . . . . . . . . . . . . . . . . . 29 118 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 119 11.1. Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 30 120 11.2. Content Types . . . . . . . . . . . . . . . . . . . . . . 30 121 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31 122 13. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 32 123 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 124 14.1. Normative References . . . . . . . . . . . . . . . . . . . 34 125 14.2. Informative References . . . . . . . . . . . . . . . . . . 34 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 35 128 1. Introduction 130 The use of web services on the Internet has become ubiquitous in most 131 applications, and depends on the fundamental Representational State 132 Transfer (REST) architecture of the web. 134 The Constrained RESTful Environments (CoRE) working group aims at 135 realizing the REST architecture in a suitable form for the most 136 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 137 ROM) and networks (e.g. 6LoWPAN). Constrained networks like 6LoWPAN 138 support the expensive fragmentation of IPv6 packets into small link- 139 layer frames. One design goal of CoRE has been to keep message 140 overhead small, thus limiting the use of fragmentation. 142 One of the main goals of CoRE is to design a generic RESTful protocol 143 for the special requirements of this constrained environment, 144 especially considering energy, building automation and other M2M 145 applications. The goal of CoAP is not to blindly compress HTTP, but 146 rather to realize a subset of REST common with HTTP but optimized for 147 M2M applications. Although CoRE could be used for compressing simple 148 HTTP interfaces, it more importantly also offers features for M2M 149 such as built-in discovery, multicast support and asynchronous 150 transactions. 152 This document specifies the RESTful Constrained Application Protocol 153 (CoAP) , which easily translates to HTTP for integration with the 154 existing web while meeting specialized requirements such as multicast 155 support, very low overhead and simplicity for constrained 156 environments and M2M applications [I-D.shelby-core-coap-req]. CoAP 157 has the following main features: 159 o Constrained RESTful protocol fulfilling M2M requirements. 161 o A stateless HTTP mapping, allowing proxies to be built providing 162 access to CoAP resources via HTTP in a uniform way or for HTTP 163 simple interfaces to be realized alternatively over CoAP. 165 o UDP binding with reliable unicast and best-effort multicast 166 support. 168 o Asynchronous transaction support. 170 o Low header overhead and parsing complexity. 172 o URI and Content-type support. 174 o Built-in resource discovery. 176 o Simple proxy and caching capabilities. 178 2. Constrained Application Protocol 180 This section specifies the basic functionality and processing rules 181 of the protocol. 183 2.1. Interaction Model 185 The REST interaction model of CoAP is similar to the client/server 186 model of HTTP. However, Machine-to-machine interactions typically 187 result in a CoAP implementation acting in both client and server 188 roles (called an end-point). A CoAP REST exchange is equivalent to 189 that of HTTP, and is sent by a client to request an action (using a 190 Method Code) on a resource (identified by a URI) on a server. A 191 response is then sent with a Response Code and resource 192 representation if appropriate. 194 Unlike HTTP, CoAP deals with these REST interchanges asynchronously 195 over a UDP transport with support for both unicast and multicast 196 interactions. This is achieved using transaction messages 197 (Confirmable, Non-Confirmable, Acknowledgment, Reset) supporting 198 optional reliability (with exponential back-off) and transaction IDs 199 between end-points to carry REST requests and responses. These 200 transactions are transparent to the REST interchanges. The only 201 difference being that responses may arrive asynchronously. 203 One could think of CoAP as using a two-layer approach, a 204 transactional layer used to deal with UDP and the asynchronous nature 205 of the interactions, and the REST interactions using Method and 206 Response codes. 208 +---------------------+ 209 | Application | 210 +---------------------+ 211 +---------------------+ 212 | CoAP REST | 213 |---------------------| 214 | CoAP Transactions | 215 +---------------------+ 216 +---------------------+ 217 | UDP | 218 +---------------------+ 220 Figure 1: Abstract layering of CoAP 222 2.1.1. Synchronous response 224 The most basic interaction between the REST and Transaction layers 225 works by sending a REST request in a confirmable CoAP message and 226 waiting for an acknowledgment message that also carries the REST 227 response. E.g., two possible interactions for a basic GET are shown 228 in Figure 2. 230 Client Server Client Server 231 | | | | 232 | CON tid=47 | | CON tid=53 | 233 | GET /foo | | GET /baz | 234 +---------------->| +---------------->| 235 | | | | 236 | ACK tid=47 | | ACK tid=53 | 237 | 200 "| 283 | | 284 | ACK tid=48 | 285 |<----------------+ 286 | | 287 ... Time Passes ... 288 | | 289 | CON tid=783 | 290 | 200 http://n.. | 291 | "| 296 | | 298 Figure 3: An asynchronous GET transaction 300 When the server finally has obtained the resource representation and 301 is ready to send the response, it initiates a transaction to the 302 client. This new transaction has its own transaction ID, so there is 303 no automatic coupling of the response to the request. Instead, the 304 URI (and possibly token) is echoed back to the client in order to 305 associate the REST response to the original REST request. To ensure 306 that this message is not lost, it is again sent as a confirmable 307 message and answered by the client with an ACK, citing the new TID 308 chosen by the server. 310 As a special failure situation, a client may no longer be aware that 311 it sent a request, e.g., if it does not have stable storage and was 312 rebooted in the meantime. This can be indicated by a special "Reset" 313 message, as shown in Figure 4. 315 Client Server 316 ... Client reboots ... 317 | | 318 | CON tid=783 | 319 | 200 http://n.. | 320 | "| 325 | | 327 Figure 4: An orphaned transaction 329 2.2. Transaction messages 331 The CoAP transactions make use of four different message types, 332 described in this section. These messages are transparent to the 333 REST request/response carried over them. 335 2.2.1. Confirmable (CON) 337 Some messages require an acknowledgment, either just to know they did 338 arrive or also to deliver the reply to a request. We call these 339 messages "Confirmable". When no packets are lost, each Confirmable 340 message elicits exactly one return message of type Acknowledgment or 341 type Reset. 343 2.2.2. Non-Confirmable (NON) 345 Some other messages do not require an acknowledgment. This is 346 particularly true for messages that are repeated regularly for 347 application requirements, such as repeated readings from a sensor 348 where eventual arrival is sufficient. 350 2.2.3. Acknowledgment (ACK) 352 An Acknowledgment message acknowledges that a specific Confirmable 353 message (identified by its Transaction ID) arrived. As with all of 354 the message types itself, it may carry a payload and some options to 355 provide more details, such as the result of a request that was 356 carried in the Confirmable. 358 2.2.4. Reset (RST) 360 A Reset message indicates that a specific Confirmable message was 361 received, but some context is missing to properly process it. This 362 condition is usually caused when the receiving node has rebooted and 363 has forgotten some state that would be required to interpret the 364 message. 366 2.2.5. Transaction IDs 368 The Transaction ID is an unsigned integer kept by a CoAP end-point 369 for all of the CoAP Confirmable or Non-Confirmable messages it sends. 370 Each CoAP end-point keeps a single Transaction ID variable, which is 371 changed each time a new Confirmable or Non-Confirmable message is 372 sent regardless of the destination address or port. The Transaction 373 ID is used to match an Acknowledgment with an outstanding request, 374 for retransmission and to discard duplicate messages. The initial 375 Transaction ID should be randomized. The same Transaction ID MUST 376 NOT be re-used within the potential retransmission window, calculated 377 as RESPONSE_TIMEOUT * (2 ^ MAX_RETRANSMIT - 1). 379 2.3. Methods 381 CoAP supports the basic RESTful methods of GET, POST, PUT, DELETE, 382 which are easily mapped to HTTP. In this section each method is 383 defined along with its behavior. A unicast request with an unknown 384 or unsupported Method Code MUST generate a message with a "405 Method 385 Not Allowed" Response Code. 387 As CoAP methods manipulate resources, they have the same properties 388 of safe (only retrieval) and idempotent (you can invoke it multiple 389 times with the same effects) as HTTP Section 9.1 [RFC2616]. The GET 390 method is safe, therefore it MUST NOT take any other action on a 391 resource other than retrieval. The GET, PUT and DELETE methods MUST 392 be performed in such a way that they are idempotent. 394 2.3.1. GET 396 The GET method retrieves the information of the resource identified 397 by the request URI. Upon success a 200 (OK) response SHOULD be sent. 399 The response to a GET is cacheable if it meets the requirements in 400 Section 5. 402 2.3.2. POST 404 The POST method is used to request the server to create a new 405 resource under the requested URI. If a resource has been created on 406 the server, the response SHOULD be 201 (Created) including the URI of 407 the new resource in a Location Option with any possible status in the 408 message body. If the POST succeeds but does not result in a new 409 resource being created on the server, a 200 (OK) response code SHOULD 410 be returned. 412 Responses to this method are not cacheable. 414 2.3.3. PUT 416 The PUT method requests that the resource identified by the request 417 URI be updated with the enclosed message body. If a resource exists 418 at that URI the message body SHOULD be considered a modified version 419 of that resource, and a 200 (OK) response SHOULD be returned. If no 420 resource exists then the server MAY create a new resource with that 421 URI, resulting in a 201 (Created) response. If the resource could 422 not be created or modified, then an appropriate error response code 423 SHOULD be sent. 425 Responses to this method are not cacheable. 427 2.3.4. DELETE 429 The DELETE method requests that the resource identified by the 430 request URI be deleted. The response 200 (OK) SHOULD be sent on 431 success. 433 Responses to this method are not cacheable. 435 2.4. Response Codes 437 CoAP makes use of a subset of HTTP response codes as defined in 438 Section 11.1. 440 2.5. Options 442 CoAP makes use of compact, extensible Type-Length-Value (TLV) style 443 options. This section explains the processing of CoAP options along 444 with a summary of the main features implemented in options such as 445 URIs and Content-types. 447 2.5.1. Option Processing 449 If no options are to be included, the Option Count field is set to 0 450 below and the Payload (if any) immediately follows the Transaction 451 ID. If options are to be included, the following rules apply. The 452 number of options is placed in the Option Count field. Each option 453 is then placed in order of Type, immediately following the 454 Transaction ID with no padding. Upon reception, unknown options of 455 class "elective" MUST be silently skipped. Unknown options of class 456 "critical" in a Confirmable SHOULD cause the return of a response 457 code "400 Bad Request" (TBD) including a copy of the critical option 458 number. 460 2.5.2. URIs 462 The Universal Resource Identifier (URI) [RFC3986] is an important 463 feature of the REST architecture, where the relative part of the URI 464 indicates the resource being manipulated. CoAP supports URIs 465 similarly to HTTP, e.g. coap://[2001:DB8::101]/s/temp. As this URI 466 is used purely as a locator, CoAP only supports Universal Resource 467 Locator features of [RFC3986] although throughout the document we 468 refer to URI. 470 CoAP splits the URI up into its three parts with the Uri-Scheme, Uri- 471 Authority and Uri-Path Options. The full URI can be created by 472 concatenating those options (or their defaults if not present). Uri- 473 Scheme and Uri-Authority options are used for proxying, whereas Uri- 474 Path is used for all requests. CoAP does not support "." or ".." in 475 URIs nor does it support IRIs. A CoAP implementation SHOULD support 476 query "?" processing (see Section 6 on the use of the query string in 477 discovery), however fragment "#" processing is not supported. All 478 URI strings in CoAP MUST use the US-ASCII encoding defined in 479 [RFC3986]. When using the Uri-Path Option the leading slash MUST be 480 omitted. Thus the above example "/s/temp" is included in the Uri- 481 Path Option as "s/temp". 483 Application designers are encouraged to make use of short, but 484 descriptive URIs. For example URIs 14 or less bytes in length fit in 485 a more compact option header. In addition, very short URIs such as 486 "/1" can be assigned as an alternative short URI for a resource by 487 the application. CoAP resource descriptions includes an attribute to 488 indicate if a short alternative URI of a resource is available (see 489 Section 6). 491 The CoAP protocol scheme is identified in URIs with "coap://" 492 [IANA_TBD_SCHEME]. 494 2.5.3. Content-type encoding 496 In order to support heterogeneous uses, CoAP is transparent to the 497 use of different application payloads. In order for the application 498 process receiving a packet to properly parse a payload, its content- 499 type should be explicitly known from the header (as e.g. with HTTP). 500 The use of typical binary encodings for XML is discussed in 501 [I-D.shelby-6lowapp-encoding]. 503 String names of Internet media types (MIME types) [RFC2046] are not 504 optimal for use in the CoAP header. Instead, CoAP simply assigns 505 identifiers to a subset of common media and content transfer encoding 506 types. The content-type identifier is optionally included in the 507 Content-type Option Header of messages to indicate the type of the 508 message body. CoAP Content-type identifiers are defined in 509 Section 11.2. In the absence of the Content-type Option the MIME 510 type "text/plain" MUST BE assumed. 512 3. Message Formats 514 CoAP makes use of asynchronous transactions using a simple binary 515 header format. This base header may be followed by options in Type- 516 Length-Value (TLV) format. CoAP is bound to UDP as described in 517 Section 4. 519 Any bytes after the headers in the packet are considered the message 520 payload, if any. The length of the message payload is implied by the 521 datagram length. See Section 4 for further message length 522 requirements. 524 3.1. CoAP header 526 This section defines the CoAP header, which is shared for all CoAP 527 messages. CoAP makes use of an asynchronous transaction model. 528 These transactions are used to carry RESTful exchanges, either using 529 a Method Code (GET/PUT/POST/DELETE) to invoke interaction with a 530 resource, or a Response Code carried in an immediate or asynchronous 531 response. 533 0 1 2 3 534 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 535 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 536 |Ver| T | OC | Code | Transaction ID | 537 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 538 | Options (if any) ... 539 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 540 | Payload (if any) ... 541 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 543 Figure 5: CoAP header format 545 Header Fields: 547 Ver: Version. 2-bit unsigned integer. Indicates the version of 548 CoAP. Implementations of this specification MUST set this 549 field to 1. Other values are reserved for future versions. 551 T: 2-bit unsigned integer Transaction Type field. Indicates if 552 this message is Confirmable (0), Non-Confirmable (1), 553 Acknowledgment (2) or Reset (3). 555 OC: 4-bit unsigned integer Option Count field. Indicates if 556 there are Option Headers following the base header. If set to 557 0 the payload (if any) immediately follows the base header. If 558 greater than zero the field indicates the number of options to 559 immediately follow the header. 561 Code: 8-bit unsigned integer. This field indicates the Method or 562 Response Code of a message. The value 0 indicates no code. 563 The values 1-10 are used for Method Codes as defined in 564 Table 1. The values 11-39 are reserved for future use. The 565 values 40-255 are used for Response Codes as defined in 566 Section 11.1. 568 Transaction ID: 16-bit unsigned integer. A unique Transaction ID 569 assigned by the source and used to match responses. The 570 Transaction ID MUST be changed for each new request (regardless 571 of the end-point) and MUST NOT be changed when retransmitting a 572 request (see Section 2.2.5). 574 +--------+------+ 575 | Method | Code | 576 +--------+------+ 577 | GET | 1 | 578 | POST | 2 | 579 | PUT | 3 | 580 | DELETE | 4 | 581 +--------+------+ 583 Table 1: Method Codes 585 3.2. Header options 587 CoAP messages may also include one or more header options in TLV 588 format. Options MUST appear in order of option type (see Table 2). 589 A delta encoding is used between each option header, with the Type 590 identifier for each Option calculated as the sum of its Option Delta 591 field and the Type identifier of the preceding Option in the message, 592 if any, or zero otherwise. 594 Each option header includes a Length field which can be extended by 595 an octet for options with values longer than 14 octets. CoAP options 596 include the concept of Critical (odd value) and Elective (even value) 597 options (see Section 2.5.1). 599 Each option has the following format: 601 0 1 2 3 4 5 6 7 602 +---+---+---+---+---+---+---+---+ 603 | option delta | length | for 0..14 604 +---+---+---+---+---+---+---+---+ 605 for 15..270: 606 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 607 | option delta | 1 1 1 1 | length - 15 | 608 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 610 Figure 6: Header option format 612 Option delta: 4-bit unsigned integer. This field defines the 613 difference between the option Type of this option and the previous 614 option (or zero for the first option). In other words, the Type 615 identifier is calculated by simply summing the Option delta fields 616 of this and previous options before it. The Option Values 14, 28, 617 ... are reserved for no-op options with no value (they are 618 ignored) and are used for deltas larger than 14. Thus these can 619 be used as "fenceposts" if deltas larger than 15 would otherwise 620 be required. 622 Length: Length Field. Normally Length is a 4-bit unsigned integer 623 allowing values of 0-14 octets. When the length is 15 or more, 624 another byte is added as an 8-bit unsigned integer plus 15 625 allowing values of 15-270 octets. 627 Option Value The value in the format defined for that option in 628 Table 2 of Length octets. Options MAY use variable length values. 630 The following options are defined in this document. The Default 631 column indicates the value to be assumed in the absence of this 632 option (if any). 634 +------+-----+---------------+--------------+--------+--------------+ 635 | Type | C/E | Name | Data type | Length | Default | 636 +------+-----+---------------+--------------+--------+--------------+ 637 | 0 | - | Reserved | - | - | - | 638 | 1 | C | Content-type | 8-bit | 1 B | 0 | 639 | | | | unsigned | | (text/plain) | 640 | | | | integer | | | 641 | 2 | E | Max-age | Variable | 1-4 B | 60 seconds | 642 | | | | length | | | 643 | | | | unsigned | | | 644 | | | | integer | | | 645 | 3 | C | Uri-Scheme | String | 1-270 | "coap" | 646 | | | | | B | | 647 | 4 | E | Etag | Sequence of | 1-4 B | - | 648 | | | | bytes | | | 649 | 5 | C | Uri-Authority | String | 1-270 | "" | 650 | | | | | B | | 651 | 6 | E | Location | String | 1-270 | - | 652 | | | | | B | | 653 | 7 | - | Reserved | - | - | - | 654 | 9 | C | Uri-Path | String | 1-270 | "" | 655 | | | | | B | | 656 +------+-----+---------------+--------------+--------+--------------+ 658 Table 2: Option headers 660 3.2.1. Content-type Option 662 The Content-type Identifier Option indicates the Internet media type 663 identifier of the message-body, see Section 11.2 for the encoding and 664 identifier tables. A Content-type Identifier Option SHOULD be 665 included if there is a payload included with a CoAP message. In the 666 absence of the Content-type Option the MIME type "text/plain" (0) 667 MUST be assumed. This option MUST be supported by all end-points. 669 3.2.2. Uri-Scheme Option 671 The Uri-Scheme Option indicates the schema part of the URI without 672 any ":" or "://" glue. This option is most often used to access a 673 resource via a proxy. For example, to access an HTTP resource via a 674 proxy the option value would be "http". In the absence of this 675 option, the URI scheme is assumed to be "coap". Section 2.5.2 676 specifies the rules for URIs in CoAP. This option MUST be supported 677 by an end-point implementing proxy functionality. 679 3.2.3. Uri-Authority Option 681 The Uri-Authority Option indicates the authority (host + port) part 682 of a URI. Examples of this option include "[2001:DB8::101]", 683 "198.51.100.0:8000" and "sensor.example.com". This option is used 684 when accessing a resource via a proxy. In the absence of this 685 option, the authority is assumed to be "". Section 2.5.2 specifies 686 the rules for URIs in CoAP. This option MUST be supported by an end- 687 point implementing proxy functionality. 689 3.2.4. Uri-Path Option 691 The Uri-Path Option indicates the absolute path part of a URI. One 692 example of an absolute path in his option is "s/light". In the 693 absence of this option, the path is assumed to be "/". Section 2.5.2 694 specifies the rules for URIs in CoAP. The leading slash is assumed 695 and MUST be omitted. This option MUST be supported by all end- 696 points. 698 3.2.5. Location Option 700 The Location Option indicates the location of a resource as an 701 absolute path URI and is similar to the Uri-Path Option. The 702 Location Option MAY be included in a response to indicate the 703 Location of a new resource created with POST or together with a 30x 704 response code. The leading slash is assumed and MUST be omitted. 706 3.2.6. Max-age Option 708 The Max-age Option indicates the maximum age of the resource for use 709 in cache control in seconds. The option value is represented as a 710 variable length unsigned integer between 8 and 32 bits. A default 711 value of 60 seconds is assumed in the absence of this option. 713 When included in a request, Max-age indicates the maximum age of a 714 cached representation of that resource the client will accept. When 715 included in a response, Max-age indicates the maximum time the 716 representation may be cached before it MUST be discarded. 718 3.2.7. Etag Option 720 The Etag Option is an opaque sequence of bytes which specifies the 721 version of a resource representation. An Etag may be generated for a 722 resource in any number of ways including a version, checksum, hash or 723 time. An end-point receiving an Etag MUST treat it as opaque and 724 make no assumptions about its format. The Etag MAY be included in a 725 response to indicate to a client if a resource has changed. The Etag 726 SHOULD be included in a request used for a cache refresh to indicate 727 the client's current version of the resource (see Section 5.2). 729 4. UDP Binding 731 The CoAP protocol operates by default over UDP. CoAP could also be 732 used over other transports such as TCP or SCTP, the specification of 733 which is out of this document's scope. 735 The goal of binding CoAP to UDP is to provide the bare minimum 736 features for the protocol to operate over UDP, without trying to re- 737 create the full feature set of a transport like TCP. CoAP over UDP 738 has the following features: 740 o Simple stop-and-wait retransmission reliability with exponential 741 back-off as described in Section 4.2 for Confirmable messages. 743 o Transaction ID for response matching as described in 744 Section 2.2.5. 746 o Multicast support as described in Section 4.1. 748 The length of the Payload in a CoAP message is calculated from the 749 datagram length. While specific link layers make it beneficial to 750 keep CoAP messages small enough to fit into their link layer packets 751 (see Section 1), this is a matter of implementation quality. The 752 CoAP specification itself provides only an upper bound to the message 753 size. A CoAP message SHOULD fit within a single IP packet and MUST 754 fit within a single IP datagram. If the Path MTU is not known for a 755 destination, an MTU of 1280 octets SHOULD be assumed. 757 4.1. Multicast 759 CoAP supports the use of multicast destination addresses. Multicast 760 messages SHOULD be Non-Confirmable. If a Confirmable multicast 761 message is sent then retransmission MUST NOT be performed. 762 Furthermore, a destination end-point to a multicast Confirmable 763 message MUST only send an Acknowledgment if the response code 764 included indicates success (Code = 2XX) in order to eliminate error 765 code response floods. Other mechanisms for avoiding congestion from 766 multicast requests are being considered in 767 [I-D.eggert-core-congestion-control]. 769 4.2. Retransmission 771 A CoAP end-point keeps track of open Confirmable messages it sent 772 that are waiting for a response. Each entry includes at least the 773 destination IP address and port of the original message, the message 774 itself, a retransmission counter and a timeout. When a Confirmable 775 is sent, an entry is made for that message with a default initial 776 timeout of RESPONSE_TIMEOUT and the retransmission counter set to 0. 777 When a matching Acknowledgment is received for an entry, the entry is 778 invalidated. When a timeout is triggered for an entry and the 779 retransmission counter is less than MAX_RETRANSMIT, the original 780 message is retransmitted to the destination without modification, the 781 retransmission counter is incremented, and the timeout is doubled. 782 If the retransmission counter reaches MAX_RETRANSMIT on a timeout, 783 then the entry is removed and the application process informed of 784 delivery failure. 786 For CoAP messages sent to IP multicast addresses, retransmission MUST 787 NOT be performed. Therefore MAX_RETRANSMIT is always set to 0 when 788 the destination address is multicast. 790 4.3. Congestion Control 792 In addition to the exponential back-off mechanism in Section 4.2, 793 further congestion control optimizations are being considered and 794 tested for CoAP. These congestion control mechanism under 795 consideration are described in [I-D.eggert-core-congestion-control]. 797 4.4. Default Port 799 The CoAP default port number [IANA_TBD_PORT] MUST be supported by a 800 server for resource discovery (see Section 6) and SHOULD be supported 801 for providing access to other resources. In addition other end- 802 points may be hosted in the dynamic port space. 804 When a CoAP server is hosted by a 6LoWPAN node, it SHOULD support a 805 port in the 61616-61631 compressed UDP port space defined in 806 [RFC4944]. The specific port number in use will be communicated in a 807 URI and/or by some other discovery mechanism. 809 5. Caching 811 CoAP end-points are by definition constrained by bandwidth and 812 processing power. To optimize the performance of data transfer under 813 these constraints, we use caching features consistent with HTTP. 814 Caching includes the following concepts: 816 o Cache life of a resource is controlled via the Max-Age header 817 option 819 o Cache refresh and versioning of a resource is controlled via the 820 Etag header option 822 o Proxies between a client and end-point may participate in the 823 caching process on behalf of sleeping end-points and to avoid 824 unnecessary traffic on the constrained network 826 5.1. Cache control 828 When an end-point responds to a GET request by sending a 829 representation of the resource, it SHOULD specify the Max-Age header 830 option. The Max-Age specifies the cache life of the resource in 831 seconds. Resources which change rapidly will have a short cache 832 life, and resources which change infrequently should specify a long 833 cache life. If Max-Age is unspecified in a GET response, then it is 834 assumed to be 60 seconds. If an end-point wishes to disable caching, 835 it must explicitly specify a Max-Age of zero seconds. 837 When a client reads the response from a GET request, it should cache 838 the resource representation for the cache lifetime as specified by 839 the Max-Age header. During the cache lifetime, the client SHOULD use 840 its cached version and avoid performing additional GETs for the 841 resource. 843 In general, the origin server end-point is responsible for 844 determining cache age. However, in some cases a client may wish to 845 determine its own tolerance for cache staleness. In this case, a 846 client may specify the Max-Age header during a GET request. If the 847 client's Max-Age is of a shorter duration than the age of a cached 848 resource, then the proxy or end-point SHOULD perform a cache refresh. 849 If the client specifies a Max-Age of zero seconds, then the response 850 MUST discard the cached representation and return a fresh 851 representation. 853 5.2. Cache refresh 855 After the expiration of the cache lifetime, clients and proxies can 856 refresh their cached representation of a resource. Cache refresh is 857 accomplished using a GET request which will return a representation 858 of the resource's current state. 860 If the end-point has the capability to version the resource, then the 861 end-point should include the Etag header option in the response to a 862 GET request. The Etag is a variable length sequence of bytes which 863 captures a version identifier of the resource. The Etag is an opaque 864 identifier; clients MUST NOT infer any semantics from the Etag value. 866 If an end-point specifies the Etag header option with a response, 867 then the client SHOULD specify a matching Etag header option in their 868 GET request during cache refresh. If the end-point's version of the 869 resource is unmodified, then the server SHOULD return a 304 response 870 with no payload to avoid retransmitting the resource representation. 872 5.3. Proxying 874 A proxy is defined as a CoAP end-point which services cached requests 875 on behalf of other CoAP end-points. Any node in a CoAP network may 876 act as a proxy, although in general the node between the constrained 877 network and the Internet at large SHOULD always support proxy 878 functionality. 880 Proxies should be used under the following scenarios: 882 o Clients external to the constrained network SHOULD always make 883 requests through a proxy to limit traffic on the constrained 884 network 886 o Clients internal to the constrained network MAY use a proxy based 887 on network topology when performance warrants 889 o Clients of sleeping devices MUST use a proxy to access resources 890 while the device is sleeping 892 Proxy requests are made as normal CON requests to the proxy end- 893 point. All proxy requests MUST use the Uri-Authority header to 894 indicate the origin server's IP address using the URI format defined 895 by RFC 3986: 897 full uri = "coap://" + authority + path 898 authority = host [ ":" port ] 899 host = IP-literal / IPv4address / reg-name 900 (as defined by RFC 3986) 901 port = *DIGIT 903 The host part is case insensitive and may be an IPv4 literal, IPv6 904 literal in square brackets, or a registered name. The port number is 905 optional, if omitted or zero-length it is assumed to be the default 906 CoAP port (see Section 4.4). 908 If a request is made using the Uri-Authority header, then the 909 following steps are taken: 911 1. If the authority (host and port) is the same as the proxy end- 912 point, then the request MUST be treated as a local request and the 913 path part is used as Uri-Path 914 2. If the end-point does not support proxy functionality for the 915 given URI or Method code, then the 400 Bad Request (TBD) error 916 code MUST be returned 918 3. If the proxy does not contain a fresh cached representation of 919 the resource, then the proxy MUST attempt to refresh its cache 920 according to section 5.2. The origin server's IP address and port 921 is determined by the authority part of the full URI. The Uri-Path 922 option for the refresh request is determined by the path part of 923 the full URI. 925 4. If the proxy fails to obtain a fresh cached representation, 926 then a 502 Bad Gateway error code MUST be returned 928 5. The proxy returns the cached representation on behalf of the 929 origin server 931 All CoAP options are considered end-to-end and MUST be stored as part 932 of the cache entry and MUST be transmitted in the proxy's response. 933 The Max-Age option should be adjusted by the proxy for each response 934 using the formula: proxy-max-age = original-max-age - cache-age. For 935 example if a request is made to a proxied resource that was refreshed 936 20sec ago and had an original Max-Age of 60sec, then that resource's 937 proxied Max-Age is now 40sec. 939 6. Resource Discovery 941 The discovery of resources offered by a CoAP end-point is extremely 942 important in machine-to-machine applications where there are no 943 humans in the loop and static interfaces result in fragility. The 944 discovery of resources provided by an HTTP Web Server is typically 945 called Web Discovery. In this document we refer to the discovery of 946 resources offered by a CoAP end-point as resource discovery. CoAP 947 resource discovery enables both unicast and multicast discovery of 948 resources including filtering on attributes of resource descriptions. 949 CoAP resource discovery can also be used to discovery HTTP resources. 951 CoAP makes the assumption that all CoAP servers host an end-point on 952 the default CoAP port (see Section 4.4) hosting a well-known 953 discovery resource, or otherwise have been configured or discovered 954 using some general service discovery mechanism such as 955 [I-D.cheshire-dnsext-dns-sd]. This section assumes that such a 956 configuration or service discovery has already been performed a 957 priori, if needed. 959 Resource discovery in CoAP is accomplished through the use of well- 960 known resources which describe the links (resource descriptions) 961 offered by that CoAP server. Well-known resources use the URI form 962 "/.well-known/" as specified in [RFC5785]. CoAP discovery defines a 963 new well-known URI for discovery "/.well-known/r" 964 [IANA_TBD_WELLKNOWN]. A CoAP end-point MUST support this URI for the 965 purpose of resource discovery. It is however up to the application 966 which resources descriptions are included and how they are organized. 967 The resource representation of this resource is described in 968 Section 6.1. 970 CoAP Resource Discovery supports the following interactions: 972 o [GET /.well-known/r] returns a list of links available from a CoAP 973 server (if any). This request may be unicast or multicast. 975 o Filtering may be performed on any of the resource description 976 attributes using a query string as specified in Section 6.3. For 977 example [GET /.well-known/r?n=Temperature] would return resources 978 with the name Temperature. 980 o More capable end-points such as proxies could support a resource 981 directory by requesting the resource descriptions of other end- 982 points or accepting [POST /.well-known/r] messages from other CoAP 983 end-points. This adds the resources of other end-points to a 984 resource directory in which absolute URIs are included for the 985 links. The details of such an entity are however out of scope for 986 this document. 988 o CoAP may also be used to discovery HTTP resources or an HTTP 989 server may use the well-known resource and link-format as 990 discussed in Section 6.4. 992 End-points with a large number of resources SHOULD include resource 993 descriptions only for important collections and organize their 994 resource descriptions into a hierarchy of link resources. This is 995 done by including links in the /.well-known/r list which point to 996 other resource lists, e.g. ";n=Sensors;ct=40". 997 Such a hierarchy SHOULD be under the /.well-known/r path. 999 6.1. Link Format 1001 CoAP resource discovery makes use of the HTTP Link Header format 1002 specified in [I-D.nottingham-http-link-header] which is in Augmented 1003 Backus-Naur Form (ABNF) notation [RFC5234]. This specification 1004 allows for the use of this simple link format by other protocols, 1005 thus not limiting it to the actual HTTP Link Header. The format does 1006 not require special XML or binary parsing, and is extensible. The 1007 format is also compatible with the naming and descriptions used in 1008 [I-D.cheshire-dnsext-dns-sd]. 1010 [I-D.nottingham-http-link-header] did not request a MIME type for 1011 this link format, as it assumes that would usually be carried in an 1012 HTTP header. This specification thus requests a MIME type for this 1013 header as in Section 11.2 [IANA_TBD_LINK]. 1015 The CoAP link-format defines default attributes for CoAP resource 1016 discovery. All link parameters are optional and custom link- 1017 extensions MAY be defined. Multiple descriptions are separated by 1018 commas as in [I-D.nottingham-http-link-header]. The following ABNF 1019 specification defines the format: 1021 link-value = "<" URI-Reference ">" *( ";" link-param ) 1022 link-param = ( ( "d" "=" URI ) 1023 | ( "sh" "=" URI ) 1024 | ( "n" "=" string ) 1025 | ( "ct" "=" media-code *( "," media-code ) ) 1026 | ( "id" "=" integer ) 1027 | ( link-extension ) ) 1028 link-extension = ( parmname [ "=" ( ptoken | string ) ] ) 1029 ptoken = 1*ptokenchar 1030 ptokenchar = "!" | "#" | "$" | "%" | "&" | "'" | "(" 1031 | ")" | "*" | "+" | "-" | "." | "/" | DIGIT 1032 | ":" | "<" | "=" | ">" | "?" | "@" | ALPHA 1033 | "[" | "]" | "^" | "_" | "`" | "{" | "|" 1034 | "}" | "~" 1035 media-code = Identifier for media type in decimal ASCII, 1036 see Section 11.2 1037 URI-reference = Imported from [RFC3986] 1038 URI = Imported from [RFC3986] 1040 link-value: The link-value is the relative URI of the resource on 1041 that end-point or an absolute full URI in the case of e.g. a 1042 directory agent or HTTP resource. The key "uri=" is used to match 1043 this field in a query string. Protocol identifier, host and port 1044 parts of the URI MAY be included if they differ from the default 1045 CoAP values. 1047 d: Description. A URI that points to the definition of that resource 1048 interface, for example in WADL. 1050 sh: Short URI. Alternative short URI which can also be used to 1051 access this resource. 1053 n: Instance Name. See Section 6.2. 1055 ct: Content-type. The Internet media type this resource returns in 1056 the CoAP identifier code format as a decimal ASCII integer as per 1057 Section 11.2. For example application/xml would be indicated as 1058 "ct=41". If a resource supports multiple content-types they can 1059 be separated by a comma in this attribute. If no Content-type 1060 attribute is present then text/plain is assumed. 1062 id: Unique Identifier. The id field is a unique identifier (e.g. 1063 UUID) for this resource for use in e.g. search directories. 1065 An example of three typical CoAP link descriptions in this format 1066 follows. Multiple resource descriptions in a representation are 1067 separated by commas. Linefeeds are included in the example just for 1068 readability. 1070 ;n=Info, 1071 ;sh=/t;ct=0,41;n=Temperature, 1072 ;sh=/l;ct=41;n=Light, 1074 6.2. Naming 1076 CoAP resource naming is designed to be compatible with DNS-based 1077 Service Discovery naming. The n= attribute carries what can be 1078 considered the "Instance" part of a DNS-SD name. The "Service" and 1079 "Domain" parts of DNS naming are implied as Service is assumed to be 1080 "_coap._udp" and Domain is assumed to be .local. The Service part 1081 MAY be included as _http._tcp in the case of an HTTP resource. The 1082 Domain MAY be included if different than .local. 1084 Whereas service discovery is used to find the IP address, port and 1085 protocol of an unknown service, resource discovery is a fine-grained 1086 discovery of resource URIs within a web service. CoAP resource 1087 descriptions can be imported into DNS-SD for exposure to service 1088 discovery by using the n= attribute as the "Instance", "_coap_udp" as 1089 the Service and a default of ".local" as the Domain. The DNS TXT 1090 record can be generated by importing the resource description 1091 attributes as they share the same format as Section 6 of 1092 [I-D.cheshire-dnsext-dns-sd]. 1094 6.3. Query Filtering 1096 A CoAP end-point SHOULD support the query string /.well-known/r? with 1097 uri= or any of the resource description attributes for the purpose of 1098 filtering a discovery. Wildcard * endings SHOULD be supported. An 1099 exact match is performed on the query string, and a 200 OK response 1100 is returned with a link-style structure that contains the matching 1101 entries (if any). If resource descriptions are organized 1102 hierarchically, a query on the root resource /.well-known/r SHOULD 1103 return all matching resource descriptions from the entire hierarchy 1104 if possible. 1106 For a unicast query with no matching entries a 404 Not Found code is 1107 returned, however no response is sent in case of a multicast query as 1108 described in Section 4.1 to prevent a flood of responses. 1110 6.4. HTTP Resource Discovery 1112 This mechanism may also be used to discover HTTP resources as HTTP 1113 lacks a built-in discovery mechanism and multicast support. When 1114 HTTP resources are listed in the link-format HTTP they SHOULD be 1115 indicated by including http:// in the link-value field or the 1116 _http._tcp Service in the name attribute. 1118 An HTTP server may make use of the /.well-known/r URI scheme and 1119 link-format representation defined in this section for the purpose of 1120 discovery using HTTP. This may especially be useful for a CoAP-HTTP 1121 proxy to expose the resources available in a constrained domain to 1122 HTTP clients. 1124 7. HTTP Mapping 1126 CoAP supports a limited subset of HTTP functionality, and thus a 1127 mapping to HTTP is straightforward. There might be several reasons 1128 for mapping between CoAP and HTTP, for example when designing a REST 1129 interface for use over either protocol or when realizing a CoAP-HTTP 1130 proxy. Likewise, CoAP could equally be mapped to other protocols 1131 such as XMPP or SIP, the definition of which is out of scope. 1133 The mapping of CoAP to HTTP is a straightforward conversion of the 1134 CoAP method or response code, content-type and options to the 1135 corresponding HTTP feature. The payload is carried in an equivalent 1136 way by both protocols. The mapping of HTTP to CoAP requires checking 1137 for methods, response codes, options and content-types that are not 1138 supported by CoAP. A mapping SHOULD attempt to map options, response 1139 codes and content-types to a suitable alternative if possible. 1140 Otherwise the unsupported feature SHOULD be silently dropped if 1141 possible, or an appropriate error code generated otherwise. 1143 The caching and proxying of CoAP is specified in Section 5. In a 1144 similar manner, caching and proxying MAY be performed between CoAP 1145 and HTTP by an intermediate node. A proxy SHOULD respond with a 502 1146 (Bad Gateway) error to HTTP requests which can not be successfully 1147 mapped to CoAP. CoAP transaction messages are transparent to REST 1148 and MUST have no affect on a proxy function. 1150 8. Protocol Constants 1152 This section defines the relevant protocol constants defined in this 1153 document: 1155 RESPONSE_TIMEOUT 1 second 1157 MAX_RETRANSMIT 5 1159 9. Examples 1161 Figure 7 shows a basic request sequence. A client makes a 1162 Confirmable GET request for the resource /temperature to the server 1163 with a Transaction ID of 1234. The request includes one Uri-Path 1164 Option (delta 0 + 9 = 9) "temperature" of Len = 11. This request is 1165 a total of 16 octets long. The corresponding Acknowledgment is of 1166 Code 200 OK and includes a Payload of "22.3 C". The Transaction ID 1167 is 1234, thus the transaction is successfully completed. The 1168 response is 10 octets long and a Content-type of 0 (text/plain) is 1169 assumed as there is no Content-type Option. 1171 CLIENT SERVER 1172 | | 1173 | ----- CON + GET /temperature [TID=1234] ------> | 1174 | | 1176 0 1 2 3 1177 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 1178 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1179 | 1 | 0 | 1 | GET = 1 | TID=1234 | 1180 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1181 | 9 | 11 | "temperature" (11 Octets) ... 1182 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1184 CLIENT SERVER 1185 | | 1186 | <-------- ACK + 200 OK [TID=1234] --------- | 1187 | | 1189 0 1 2 3 1190 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 1191 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1192 | 1 | 2 | 0 | Code=80 | TID=1234 | 1193 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1194 | "22.3 C" (6 Octets) ... 1195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1197 Figure 7: Basic request/response 1199 Figure 8 shows an example of a retransmission using the previous 1200 request. The first ACK from the server is lost, and after 1201 RESPONSE_TIMEOUT seconds the client retransmits the request. 1203 CLIENT SERVER 1204 | | 1205 | ----- CON + GET /temperature [TID=1234] ------> | 1206 | | 1207 | X------------------------ | 1208 | | 1209 RESPONSE_TIMEOUT 1210 | | 1211 | ----- CON + GET /temperature [TID=1234] ------> | 1212 | | 1213 | | 1214 | <-------- ACK + 200 OK [TID=1234] --------- | 1215 Payload: 1216 22.3 C 1218 Figure 8: Basic request/response 1220 Figure 9 shows an example of resource discovery. Here a unicast GET 1221 request is made to the server for /.well-known/r, which returns a 1222 list of two resource descriptions. The client then decides to make a 1223 request for the short URI of /sensor/light (/l). Requesting 1224 /sensors/light would result in the same representation. 1226 CLIENT SERVER 1227 | | 1228 | ----- CON + GET /.well-known/r [TID=5068] ------> | 1229 | | 1230 | <----- ACK + 200 OK [TID=5068, CT=40] ------ | 1231 Payload: 1232 ;sh=/t;ct=0,41;n=Temperature, 1233 ;sh=/l;ct=41;n=Light 1235 | | 1236 | ----- CON + GET /l [TID=5069] ------> | 1237 | | 1238 | <---- ACK + 200 OK [TID=5069, CT=41] ----- | 1239 Payload: 1240 45 1242 Figure 9: Basic request/response 1244 Figure 10 shows an example of multicast resource discovery. Here a 1245 client sends a request for /.well-known/r with a query for ?n=Light 1246 (Resource name = Light) to all-nodes link-scope multicast. There are 1247 3 servers on the link: A, B and C. Servers A and B have a matching 1248 resource, therefore they send back a successful 200 OK response with 1249 the matching resource in the payload. C does not attempt to send a 1250 response. 1252 CLIENT FF02::1 1253 | | 1254 | --- CON + GET /.well-known/r?n=Light [TID=7000] ---> | 1255 | | 1256 | <----- ACK + 200 OK [TID=7000, CT=40] ------ SERVER A 1257 Payload: 1258 ;sh=/l;ct=41;n=Light 1260 | | 1261 | <----- ACK + 200 OK [TID=7000, CT=40] ------ SERVER B 1262 Payload: 1263 ;ct=41;n=Light 1265 Figure 10: Basic request/response 1267 10. Security Considerations 1269 TODO: Expand this section to a full security analysis, including how 1270 to use CoAP with various security options. 1272 Some of the features considered in this document will need further 1273 security considerations during a protocol design. For example the 1274 use of string URLs may have entail security risks due to complex 1275 processing on limited microcontroller implementations. 1277 The CoAP protocol will be designed for use with e.g. (D)TLS, IPsec 1278 or object security. A protocol design should consider how 1279 integration with these security methods will be done, how to secure 1280 the CoAP header and other implications. 1282 11. IANA Considerations 1284 [IANA_TBD_SCHEME] This document suggests the scheme coap:// to 1285 identify this protocol in a URI. The string "coap" should similarly 1286 be used in well-known port and service discovery registrations. 1288 [IANA_TBD_PORT] Apply for a well-known port number in the 0-1023 1289 space as CoAP end-points are usually executed by an operating system 1290 or root process. http://www.iana.org/assignments/port-numbers 1292 [IANA_TBD_MIME] A new registry is required for the Internet MIME type 1293 identifier space for CoAP as described in Section 11.2. 1295 [IANA_TBD_LINK] MIME type for link format, application/link-format to 1296 be requested. 1298 [IANA_TBD_WELLKNOWN] Apply for a well-known URI for the purpose of 1299 resource discovery at /.well-known/r as per [RFC5785]. 1301 11.1. Codes 1303 CoAP makes use of (a subset of) the HTTP status codes defined in 1304 [RFC2616]. The HTTP status code is encoded into an 8-bit unsigned 1305 integer code with the mapping defined in Table 3. The use of these 1306 codes is defined throughout this document using the HTTP Name. 1308 +------+----------------------------+ 1309 | Code | HTTP Name | 1310 +------+----------------------------+ 1311 | 40 | 100 Continue | 1312 | 80 | 200 OK | 1313 | 81 | 201 Created | 1314 | 124 | 304 Not Modified | 1315 | 160 | 400 Bad Request | 1316 | 164 | 404 Not Found | 1317 | 165 | 405 Method Not Allowed | 1318 | 175 | 415 Unsupported Media Type | 1319 | 200 | 500 Internal Server Error | 1320 | 202 | 502 Bad Gateway | 1321 | 204 | 504 Gateway Timeout | 1322 +------+----------------------------+ 1324 Table 3: CoAP Codes 1326 11.2. Content Types 1328 Internet media types are identified by a string in HTTP, such as 1329 "application/xml". This string is made up of a top-level type 1330 "application" and a sub-type "xml" [RFC2046]. In order to minimize 1331 the overhead of using these media types to indicate the type of 1332 message payload, CoAP defines an identifier encoding scheme for a 1333 subset of Internet media types. It is expected that this table of 1334 identifiers will be extensible and maintained by IANA for values of 1335 0-200 [IANA_TBD_MIME]. 1337 The Content-type Option is formatted as an 8-bit unsigned integer. 1339 Initial mappings from Internet media types to a suitable identifier 1340 is shown in Table 4. Composite high-level types (multipart and 1341 message) are not supported. Identifier values from 201-255 are 1342 reserved for vendor specific, application specific or experimental 1343 use and are not maintained by IANA. 1345 +-----------------------------------------+------------+ 1346 | Internet media type | Identifier | 1347 +-----------------------------------------+------------+ 1348 | text/plain (UTF-8) | 0 | 1349 | text/xml (UTF-8) | 1 | 1350 | text/csv (UTF-8) | 2 | 1351 | text/html (UTF-8) | 3 | 1352 | image/gif | 21 | 1353 | image/jpeg | 22 | 1354 | image/png | 23 | 1355 | image/tiff | 24 | 1356 | audio/raw | 25 | 1357 | video/raw | 26 | 1358 | application/link-format [IANA_TBD_LINK] | 40 | 1359 | application/xml | 41 | 1360 | application/octet-stream | 42 | 1361 | application/rdf+xml | 43 | 1362 | application/soap+xml | 44 | 1363 | application/atom+xml | 45 | 1364 | application/xmpp+xml | 46 | 1365 | application/exi | 47 | 1366 | application/x-bxml | 48 | 1367 | application/fastinfoset | 49 | 1368 | application/soap+fastinfoset | 50 | 1369 | application/json | 51 | 1370 +-----------------------------------------+------------+ 1372 Table 4: Media type identifiers 1374 12. Acknowledgments 1376 Special thanks to Carsten Bormann and Klaus Hartke for substantial 1377 contributions to the ideas and text in the document (Section 2.1.1, 1378 Section 2.1.2, Section 2.2, Section 3.2), along with countless 1379 detailed reviews and discussions. 1381 Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido 1382 Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey 1383 Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, 1384 Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed 1385 Beroset, Gilman Tolle, Robby Simpson, Peter Bigot, Colin O'Flynn and 1386 David Ryan for helpful comments and discussions that have shaped the 1387 document. 1389 13. Changelog 1391 Changes from ietf-00 to ietf-01: 1393 o New cleaner transaction message model and header (#5) 1395 o Removed subscription while being designed (#1) 1397 o Section 2 re-written (#3) 1399 o Text added about use of short URIs (#4) 1401 o Improved header option scheme (#5, #14) 1403 o Date option removed whiled being designed (#6) 1405 o New text for CoAP default port (#7) 1407 o Completed proxying section (#8) 1409 o Completed resource discovery section (#9) 1411 o Completed HTTP mapping section (#10) 1413 o Several new examples added (#11) 1415 o URI split into 3 options (#12) 1417 o MIME type defined for link-format (#13, #16) 1419 o New text on maximum message size (#15) 1421 o Location Option added 1423 Changes from shelby-01 to ietf-00: 1425 o Removed the TCP binding section, left open for the future. 1427 o Fixed a bug in the example. 1429 o Marked current Sub/Notify as (Experimental) while under WG 1430 discussion. 1432 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 1433 CoAP-CoAP proxying to work). 1435 o Temporarily removed the Magic Byte header as TCP is no longer 1436 included as a binding. 1438 o Removed the Uri-code Option as different URI encoding schemes 1439 are being discussed. 1441 o Changed the rel= field to desc= for resource discovery. 1443 o Changed the maximum message size to 1024 bytes to allow for IP/ 1444 UDP headers. 1446 o Made the URI slash optimization and method impotence MUSTs 1448 o Minor editing and bug fixing. 1450 Changes from shelby-00 to shelby-01: 1452 o Unified the message header and added a notify message type. 1454 o Renamed methods with HTTP names and removed the NOTIFY method. 1456 o Added a number of options field to the header. 1458 o Combines the Option Type and Length into an 8-bit field. 1460 o Added the magic byte header. 1462 o Added new Etag option. 1464 o Added new Date option. 1466 o Added new Subscription option. 1468 o Completed the HTTP Code - CoAP Code mapping table appendix. 1470 o Completed the Content-type Identifier appendix and tables. 1472 o Added more simplifications for URI support. 1474 o Initial subscription and discovery sections. 1476 o A Flag requirements simplified. 1478 14. References 1479 14.1. Normative References 1481 [I-D.nottingham-http-link-header] 1482 Nottingham, M., "Web Linking", 1483 draft-nottingham-http-link-header-09 (work in progress), 1484 April 2010. 1486 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1487 Extensions (MIME) Part Two: Media Types", RFC 2046, 1488 November 1996. 1490 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1491 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1492 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1494 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1495 Resource Identifier (URI): Generic Syntax", STD 66, 1496 RFC 3986, January 2005. 1498 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1499 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1501 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1502 Uniform Resource Identifiers (URIs)", RFC 5785, 1503 April 2010. 1505 14.2. Informative References 1507 [I-D.cheshire-dnsext-dns-sd] 1508 Cheshire, S. and M. Krochmal, "DNS-Based Service 1509 Discovery", draft-cheshire-dnsext-dns-sd-06 (work in 1510 progress), March 2010. 1512 [I-D.eggert-core-congestion-control] 1513 Eggert, L., "Congestion Control for the Constrained 1514 Application Protocol (CoAP)", 1515 draft-eggert-core-congestion-control-00 (work in 1516 progress), June 2010. 1518 [I-D.shelby-6lowapp-encoding] 1519 Shelby, Z., Luimula, M., and D. Peintner, "Efficient XML 1520 Encoding and 6LowApp", draft-shelby-6lowapp-encoding-00 1521 (work in progress), October 2009. 1523 [I-D.shelby-core-coap-req] 1524 Shelby, Z., Stuber, M., Sturek, D., Frank, B., and R. 1525 Kelsey, "CoAP Requirements and Features", 1526 draft-shelby-core-coap-req-01 (work in progress), 1527 April 2010. 1529 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 1530 "Transmission of IPv6 Packets over IEEE 802.15.4 1531 Networks", RFC 4944, September 2007. 1533 Authors' Addresses 1535 Zach Shelby 1536 Sensinode 1537 Kidekuja 2 1538 Vuokatti 88600 1539 FINLAND 1541 Phone: +358407796297 1542 Email: zach@sensinode.com 1544 Brian Frank 1545 SkyFoundry 1546 Richmond, VA 1547 USA 1549 Phone: 1550 Email: brian@skyfoundry.com 1552 Don Sturek 1553 Pacific Gas & Electric 1554 77 Beale Street 1555 San Francisco, CA 1556 USA 1558 Phone: +1-619-504-3615 1559 Email: d.sturek@att.net