idnits 2.17.1 draft-ietf-core-coap-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 3303 has weird spacing: '... Client ff02:...' -- The document date (March 14, 2011) is 4791 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) == Missing Reference: '0x7d34' is mentioned on line 342, but not defined == Missing Reference: '0x01a0' is mentioned on line 355, but not defined == Missing Reference: '0xbc90' is mentioned on line 395, but not defined == Missing Reference: '0xbc91' is mentioned on line 395, but not defined == Missing Reference: '0x7a10' is mentioned on line 420, but not defined == Missing Reference: '0x23bb' is mentioned on line 431, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 2879, but not defined ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4347 (Obsoleted by RFC 6347) ** Obsolete normative reference: RFC 4395 (Obsoleted by RFC 7595) ** Obsolete normative reference: RFC 4835 (Obsoleted by RFC 7321) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5389 (Obsoleted by RFC 8489) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 5996 (Obsoleted by RFC 7296) == Outdated reference: A later version (-21) exists of draft-ietf-core-block-01 == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-02 == Outdated reference: A later version (-06) exists of draft-ietf-tls-rfc4347-bis-04 == Outdated reference: A later version (-04) exists of draft-mcgrew-tls-aes-ccm-01 == Outdated reference: A later version (-08) exists of draft-mcgrew-tls-aes-ccm-ecc-01 -- Obsolete informational reference (is this intentional?): RFC 3920 (Obsoleted by RFC 6120) Summary: 10 errors (**), 0 flaws (~~), 14 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group Z. Shelby 3 Internet-Draft Sensinode 4 Intended status: Standards Track K. Hartke 5 Expires: September 15, 2011 C. Bormann 6 Universitaet Bremen TZI 7 B. Frank 8 SkyFoundry 9 March 14, 2011 11 Constrained Application Protocol (CoAP) 12 draft-ietf-core-coap-05 14 Abstract 16 This document specifies the Constrained Application Protocol (CoAP), 17 a specialized web transfer protocol for use with constrained networks 18 and nodes for machine-to-machine applications such as smart energy 19 and building automation. These constrained nodes often have 8-bit 20 microcontrollers with small amounts of ROM and RAM, while networks 21 such as 6LoWPAN often have high packet error rates and a typical 22 throughput of 10s of kbit/s. CoAP provides a method/response 23 interaction model between application end-points, supports built-in 24 resource discovery, and includes key web concepts such as URIs and 25 content-types. CoAP easily translates to HTTP for integration with 26 the web while meeting specialized requirements such as multicast 27 support, very low overhead and simplicity for constrained 28 environments. 30 Status of this Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on September 15, 2011. 47 Copyright Notice 48 Copyright (c) 2011 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 66 2. Constrained Application Protocol . . . . . . . . . . . . . . . 7 67 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 8 68 2.2. Request/Response Model . . . . . . . . . . . . . . . . . . 9 69 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . . 11 70 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . . 11 71 3. Message Syntax . . . . . . . . . . . . . . . . . . . . . . . . 12 72 3.1. Message Format . . . . . . . . . . . . . . . . . . . . . . 12 73 3.1.1. Message Size Implementation Considerations . . . . . . 13 74 3.2. Option Format . . . . . . . . . . . . . . . . . . . . . . 14 75 4. Message Semantics . . . . . . . . . . . . . . . . . . . . . . 15 76 4.1. Reliable Messages . . . . . . . . . . . . . . . . . . . . 16 77 4.2. Unreliable Messages . . . . . . . . . . . . . . . . . . . 17 78 4.3. Message Types . . . . . . . . . . . . . . . . . . . . . . 17 79 4.3.1. Confirmable (CON) . . . . . . . . . . . . . . . . . . 18 80 4.3.2. Non-Confirmable (NON) . . . . . . . . . . . . . . . . 18 81 4.3.3. Acknowledgement (ACK) . . . . . . . . . . . . . . . . 18 82 4.3.4. Reset (RST) . . . . . . . . . . . . . . . . . . . . . 18 83 4.4. Multicast . . . . . . . . . . . . . . . . . . . . . . . . 19 84 4.5. Congestion Control . . . . . . . . . . . . . . . . . . . . 19 85 5. Request/Response Semantics . . . . . . . . . . . . . . . . . . 19 86 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . . 19 87 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 20 88 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . . 21 89 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . . 21 90 5.2.3. Non-Confirmable . . . . . . . . . . . . . . . . . . . 22 91 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 22 92 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 23 93 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 23 94 5.4.2. Length . . . . . . . . . . . . . . . . . . . . . . . . 24 95 5.4.3. Default Values . . . . . . . . . . . . . . . . . . . . 24 96 5.4.4. Repeating Options . . . . . . . . . . . . . . . . . . 24 97 5.4.5. Option Numbers . . . . . . . . . . . . . . . . . . . . 24 98 5.5. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 25 99 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 25 100 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 26 101 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . . 26 102 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 27 103 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . . 28 104 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 28 105 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . . 28 106 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 29 107 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . . 29 108 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 30 109 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . . 30 110 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 31 111 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 32 112 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . . 33 113 5.10.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 33 114 5.10.2. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . . 34 115 5.10.3. Proxy-Uri . . . . . . . . . . . . . . . . . . . . . . 35 116 5.10.4. Content-Type . . . . . . . . . . . . . . . . . . . . . 35 117 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . . 35 118 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . . 36 119 5.10.7. Location-Path and Location-Query . . . . . . . . . . . 36 120 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 36 121 6.1. URI Scheme Syntax . . . . . . . . . . . . . . . . . . . . 37 122 6.2. Normalization and Comparison Rules . . . . . . . . . . . . 37 123 6.3. Parsing URIs . . . . . . . . . . . . . . . . . . . . . . . 38 124 6.4. Constructing URIs . . . . . . . . . . . . . . . . . . . . 39 125 7. Finding and Addressing CoAP End-Points . . . . . . . . . . . . 40 126 7.1. Resource Discovery . . . . . . . . . . . . . . . . . . . . 40 127 7.2. Default Port . . . . . . . . . . . . . . . . . . . . . . . 40 128 7.3. Multiplexing DTLS and CoAP . . . . . . . . . . . . . . . . 41 129 7.3.1. Future-Proofing the Multiplexing . . . . . . . . . . . 41 130 8. HTTP Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 42 131 8.1. CoAP-HTTP Mapping . . . . . . . . . . . . . . . . . . . . 43 132 8.2. HTTP-CoAP Mapping . . . . . . . . . . . . . . . . . . . . 47 133 9. Protocol Constants . . . . . . . . . . . . . . . . . . . . . . 49 134 10. Security Considerations . . . . . . . . . . . . . . . . . . . 49 135 10.1. Securing CoAP with IPsec . . . . . . . . . . . . . . . . . 50 136 10.2. Securing CoAP with DTLS . . . . . . . . . . . . . . . . . 51 137 10.2.1. SharedKey and MultiKey Modes . . . . . . . . . . . . . 52 138 10.2.2. Certificate Mode . . . . . . . . . . . . . . . . . . . 52 139 10.3. Threat analysis and protocol limitations . . . . . . . . . 53 140 10.3.1. Protocol Parsing, Processing URIs . . . . . . . . . . 53 141 10.3.2. Proxying and Caching . . . . . . . . . . . . . . . . . 53 142 10.3.3. Risk of amplification . . . . . . . . . . . . . . . . 54 143 10.3.4. Cross-Protocol Attacks . . . . . . . . . . . . . . . . 55 144 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 145 11.1. CoAP Code Registry . . . . . . . . . . . . . . . . . . . . 57 146 11.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . . 57 147 11.1.2. Response Codes . . . . . . . . . . . . . . . . . . . . 58 148 11.2. Option Number Registry . . . . . . . . . . . . . . . . . . 59 149 11.3. Media Type Registry . . . . . . . . . . . . . . . . . . . 60 150 11.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 62 151 11.5. Service Name and Port Number Registration . . . . . . . . 63 152 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 63 153 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 64 154 13.1. Normative References . . . . . . . . . . . . . . . . . . . 64 155 13.2. Informative References . . . . . . . . . . . . . . . . . . 66 156 Appendix A. Integer Option Value Format . . . . . . . . . . . . . 67 157 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 68 158 Appendix C. URI Examples . . . . . . . . . . . . . . . . . . . . 74 159 Appendix D. Changelog . . . . . . . . . . . . . . . . . . . . . . 76 160 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 80 162 1. Introduction 164 The use of web services on the Internet has become ubiquitous in most 165 applications, and depends on the fundamental Representational State 166 Transfer (REST) architecture of the web. 168 The Constrained RESTful Environments (CoRE) working group aims at 169 realizing the REST architecture in a suitable form for the most 170 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 171 ROM) and networks (e.g. 6LoWPAN). Constrained networks like 6LoWPAN 172 support the expensive fragmentation of IPv6 packets into small link- 173 layer frames. One design goal of CoAP has been to keep message 174 overhead small, thus limiting the use of fragmentation. 176 One of the main goals of CoAP is to design a generic web protocol for 177 the special requirements of this constrained environment, especially 178 considering energy, building automation and other M2M applications. 179 The goal of CoAP is not to blindly compress HTTP [RFC2616], but 180 rather to realize a subset of REST common with HTTP but optimized for 181 M2M applications. Although CoAP could be used for compressing simple 182 HTTP interfaces, it more importantly also offers features for M2M 183 such as built-in discovery, multicast support and asynchronous 184 message exchanges. 186 This document specifies the Constrained Application Protocol (CoAP), 187 which easily translates to HTTP for integration with the existing web 188 while meeting specialized requirements such as multicast support, 189 very low overhead and simplicity for constrained environments and M2M 190 applications. 192 1.1. Features 194 CoAP has the following main features: 196 o Constrained web protocol fulfilling M2M requirements. 198 o A stateless HTTP mapping, allowing proxies to be built providing 199 access to CoAP resources via HTTP in a uniform way or for HTTP 200 simple interfaces to be realized alternatively over CoAP. 202 o UDP binding with reliable unicast and best-effort multicast 203 support. 205 o Asynchronous message exchanges. 207 o Low header overhead and parsing complexity. 209 o URI and Content-type support. 211 o Simple proxy and caching capabilities. 213 o Optional resource discovery. 215 1.2. Terminology 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 219 document are to be interpreted as described in [RFC2119]. 221 This specification requires readers to be familiar with all the terms 222 and concepts that are discussed in [RFC2616]. In addition, this 223 specification defines the following terminology: 225 Piggy-backed Response 226 A Piggy-backed Response is included right in a CoAP 227 Acknowledgement (ACK) message that is sent to acknowledge receipt 228 of the Request for this Response (Section 5.2.1). 230 Separate Response 231 When a Confirmable message carrying a Request is acknowledged with 232 an empty message (e.g., because the server doesn't have the answer 233 right away), a Separate Response is sent in a separate message 234 exchange (Section 5.2.2). 236 Critical Option 237 An option that would need to be understood by the end-point 238 receiving the message in order to properly process the message 239 (Section 5.4.1). Note that the implementation of critical options 240 is, as the name "Option" implies, generally optional: unsupported 241 critical options lead to rejection of the message. 243 Elective Option 244 An option that is intended be ignored by an end-point that does 245 not understand it, which nonetheless still can correctly process 246 the message (Section 5.4.1). 248 Resource Discovery 249 The process where a CoAP client queries a server for its list of 250 hosted resources (i.e., links, Section 7.1). 252 Intermediary 253 There are two common forms of intermediary: proxy and reverse 254 proxy. In some cases, a single intermediary might act as an 255 origin server, proxy, or reverse proxy, switching behavior based 256 on the nature of each request. 258 Proxy 259 A "proxy" is an end-point selected by a client, usually via local 260 configuration rules, to perform requests on behalf of the client, 261 doing any necessary translations. Some translations are minimal, 262 such as for proxy requests for "coap" URIs, whereas other requests 263 might require translation to and from entirely different 264 application-layer protocols. 266 Reverse Proxy 267 A "reverse proxy" is an end-point that acts as a layer above some 268 other server(s) and satisfies requests on behalf of these, doing 269 any necessary translations. Unlike a proxy, a reverse proxy 270 receives requests as if it was the origin server for the target 271 resource; the requesting client will not be aware that it is 272 communicating with a reverse proxy. 274 In this specification, the term "byte" is used in its now customary 275 sense as a synonym for "octet". 277 In this specification, the operator "^" stands for exponentiation. 279 2. Constrained Application Protocol 281 The interaction model of CoAP is similar to the client/server model 282 of HTTP. However, machine-to-machine interactions typically result 283 in a CoAP implementation acting in both client and server roles 284 (called an end-point). A CoAP request is equivalent to that of HTTP, 285 and is sent by a client to request an action (using a method code) on 286 a resource (identified by a URI) on a server. The server then sends 287 a response with a response code; this response may include a resource 288 representation. 290 Unlike HTTP, CoAP deals with these interchanges asynchronously over a 291 datagram-oriented transport such as UDP. This is done using a layer 292 of messages that supports optional reliability (with exponential 293 back-off). CoAP defines four types of messages: Confirmable, Non- 294 Confirmable, Acknowledgement, Reset; method codes and response codes 295 included in some of these messages make them carry requests or 296 responses. The basic exchanges of the four types of messages are 297 transparent to the request/response interactions. 299 One could think of CoAP as using a two-layer approach, a CoAP 300 messaging layer used to deal with UDP and the asynchronous nature of 301 the interactions, and the request/response interactions using Method 302 and Response codes (see Figure 1). 304 +----------------------+ 305 | Application | 306 +----------------------+ 307 +----------------------+ 308 | Requests/Responses | 309 |----------------------| CoAP 310 | Messages | 311 +----------------------+ 312 +----------------------+ 313 | UDP | 314 +----------------------+ 316 Figure 1: Abstract layering of CoAP 318 2.1. Messaging Model 320 The CoAP messaging model is based on the exchange of messages over 321 UDP between end-points. 323 CoAP uses a short fixed-length binary header (4 bytes) that may be 324 followed by compact binary options and a payload. This message 325 format is shared by requests and responses. The CoAP message format 326 is specified in Section 3. Each message contains a Message ID used 327 to detect duplicates and for optional reliability. 329 Reliability is provided by marking a message as Confirmable (CON). A 330 Confirmable message is retransmitted using a default timeout and 331 exponential back-off between retransmissions, until the recipient 332 sends an Acknowledgement message (ACK) with the same Message ID (for 333 example, 0x7d34); see Figure 2. When a recipient is not able to 334 process a Confirmable message, it replies with a Reset message (RST) 335 instead of an Acknowledgement (ACK). 337 Client Server 338 | | 339 | CON [0x7d34] | 340 +----------------->| 341 | | 342 | ACK [0x7d34] | 343 |<-----------------+ 344 | | 346 Figure 2: Reliable message delivery 348 A message that does not require reliable delivery, for example each 349 single measurement out of a stream of sensor data, can be sent as a 350 Non-confirmable message (NON). These are not acknowledged, but still 351 have a Message ID for duplicate detection (Figure 3). 353 Client Server 354 | | 355 | NON [0x01a0] | 356 +----------------->| 357 | | 359 Figure 3: Unreliable message delivery 361 See Section 4 for details of CoAP messages. 363 As CoAP is based on UDP, it also supports the use of multicast IP 364 destination addresses, enabling multicast CoAP requests. Section 4.4 365 discusses the proper use of CoAP messages with multicast addresses 366 and precautions for avoiding response congestion. 368 Several security modes are defined for CoAP in Section 10 ranging 369 from no security to certificate based security. The use of IPsec 370 along with a binding to DTLS are specified for securing the protocol. 372 2.2. Request/Response Model 374 CoAP request and response semantics are carried in CoAP messages, 375 which include either a method code or response code, respectively. 376 Optional (or default) request and response information, such as the 377 URI and payload content-type are carried as CoAP options. A Token 378 Option is used to match responses to requests independently from the 379 underlying messages (Section 5.3). 381 A request is carried in a Confirmable (CON) or Non-confirmable (NON) 382 message, and if immediately available, the response to a request 383 carried in a Confirmable message is carried in the resulting 384 Acknowledgement (ACK) message. This is called a piggy-backed 385 response, detailed in Section 5.2.1. Two examples for a basic GET 386 request with piggy-backed response are shown in Figure 4. 388 Client Server Client Server 389 | | | | 390 | CON [0xbc90] | | CON [0xbc91] | 391 | GET /temperature | | GET /temperature | 392 | (Token 0x71) | | (Token 0x72) | 393 +----------------->| +----------------->| 394 | | | | 395 | ACK [0xbc90] | | ACK [0xbc91] | 396 | 2.05 Content | | 4.04 Not Found | 397 | (Token 0x71) | | (Token 0x72) | 398 | "22.5 C" | | "Not found" | 399 |<-----------------+ |<-----------------+ 400 | | | | 402 Figure 4: Two GET requests with piggy-backed responses, one 403 successful, one not found 405 If the server is not able to respond immediately to a request carried 406 in a Confirmable message, it simply responds with an empty 407 Acknowledgement message so that the client can stop retransmitting 408 the request. When the response is ready, the server sends it in a 409 new Confirmable message (which then in turn needs to be acknowledged 410 by the client). This is called a separate response, as illustrated 411 in Figure 5 and described in more detail in Section 5.2.2. 413 Client Server 414 | | 415 | CON [0x7a10] | 416 | GET /temperature | 417 | (Token 0x73) | 418 +----------------->| 419 | | 420 | ACK [0x7a10] | 421 |<-----------------+ 422 | | 423 ... Time Passes ... 424 | | 425 | CON [0x23bb] | 426 | 2.05 Content | 427 | (Token 0x73) | 428 | "22.5 C" | 429 |<-----------------+ 430 | | 431 | ACK [0x23bb] | 432 +----------------->| 433 | | 435 Figure 5: A GET request with a separate response 437 CoAP makes use of GET, PUT, POST and DELETE methods in a similar 438 manner to HTTP, with the semantics specified in Section 5.8. (Note 439 that the detailed semantics of CoAP methods are "almost, but not 440 entirely unlike" those of HTTP methods: Intuition taken from HTTP 441 experience generally does apply well, but there are enough 442 differences that make it worthwhile to actually read the present 443 specification.) 445 URI support in a server is simplified as the client already parses 446 the URI and splits it into host, port, path and query components, 447 making use of default values for efficiency. Response codes 448 correspond to a small subset of HTTP response codes with a few CoAP 449 specific codes added, as defined in Section 5.9. 451 2.3. Intermediaries and Caching 453 The protocol supports the caching of responses in order to 454 efficiently fulfill requests. Simple caching is enabled using 455 freshness and validity information carried with CoAP responses. A 456 cache could be located in an end-point or an intermediary. Caching 457 functionality is specified in Section 5.6. 459 Proxying is useful in constrained networks for several reasons, 460 including network traffic limiting, to improve performance, to access 461 resources of sleeping devices or for security reasons. The proxying 462 of requests on behalf of another CoAP end-point is supported in the 463 protocol. The URI of the resource to request is included in the 464 request, while the destination IP address is set to the proxy. See 465 Section 5.7 for more information on proxy functionality. 467 As CoAP was designed according to the REST architecture and thus 468 exhibits functionality similar to that of the HTTP protocol, it is 469 quite straightforward to map between HTTP-CoAP or CoAP-HTTP. Such a 470 mapping may be used to realize an HTTP REST interface using CoAP, or 471 for converting between HTTP and CoAP. This conversion can be carried 472 out by a proxy, which converts the method or response code, content- 473 type and options to the corresponding HTTP feature. Section 8 474 provides more detail about HTTP mapping. 476 2.4. Resource Discovery 478 Resource discovery is important for machine-to-machine interactions, 479 and is supported using the CoRE Link Format 480 [I-D.ietf-core-link-format] as discussed in Section 7.1. 482 3. Message Syntax 484 CoAP is based on the exchange of short messages which, by default, 485 are transported over UDP (i.e. each CoAP message occupies the data 486 section of one UDP datagram). CoAP may be used with Datagram 487 Transport Layer Security (DTLS) (see Section 10.2). It could also be 488 used over other transports such as TCP or SCTP, the specification of 489 which is out of this document's scope. 491 3.1. Message Format 493 CoAP messages are encoded in a simple binary format. A message 494 consists of a fixed-sized CoAP Header followed by options in Type- 495 Length-Value (TLV) format and a payload. The number of options is 496 determined by the header. The payload is made up of the bytes after 497 the options, if any; its length is calculated from the datagram 498 length. 500 0 1 2 3 501 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 502 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 503 |Ver| T | OC | Code | Message ID | 504 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 505 | Options (if any) ... 506 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 507 | Payload (if any) ... 508 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 510 Figure 6: Message Format 512 The fields in the header are defined as follows: 514 Version (Ver): 2-bit unsigned integer. Indicates the CoAP version 515 number. Implementations of this specification MUST set this field 516 to 1. Other values are reserved for future versions (see also 517 Section 7.3.1). 519 Type (T): 2-bit unsigned integer. Indicates if this message is of 520 type Confirmable (0), Non-Confirmable (1), Acknowledgement (2) or 521 Reset (3). See Section 4 for the semantics of these message 522 types. 524 Option Count (OC): 4-bit unsigned integer. Indicates the number of 525 options after the header. If set to 0, there are no options and 526 the payload (if any) immediately follows the header. The format 527 of options is defined below. 529 Code: 8-bit unsigned integer. Indicates if the message carries a 530 request (1-31) or a response (64-191), or is empty (0). (All 531 other code values are reserved.) In case of a request, the Code 532 field indicates the Request Method; in case of a response a 533 Response Code. Possible values are maintained in the CoAP Code 534 Registry (Section 11.1). See Section 5 for the semantics of 535 requests and responses. 537 Message ID: 16-bit unsigned integer. Used for the detection of 538 message duplication, and to match messages of type 539 Acknowledgement/Reset and messages of type Confirmable. See 540 Section 4 for Message ID generation rules and how messages are 541 matched. 543 While specific link layers make it beneficial to keep CoAP messages 544 small enough to fit into their link layer packets (see Section 1), 545 this is a matter of implementation quality. The CoAP specification 546 itself provides only an upper bound to the message size. Messages 547 larger than an IP fragment result in undesired packet fragmentation. 548 A CoAP message, appropriately encapsulated, SHOULD fit within a 549 single IP packet (i.e., avoid IP fragmentation) and MUST fit within a 550 single IP datagram. If the Path MTU is not known for a destination, 551 an IP MTU of 1280 bytes SHOULD be assumed; if nothing is known about 552 the size of the headers, good upper bounds are 1152 bytes for the 553 message size and 1024 bytes for the payload size. 555 3.1.1. Message Size Implementation Considerations 557 Note that CoAP's choice of message size parameters works well with 558 IPv6 and with most of today's IPv4 paths. (However, with IPv4, it is 559 harder to absolutely ensure that there is no IP fragmentation. If 560 IPv4 support on unusual networks is a consideration, implementations 561 may want to limit themselves to more conservative IPv4 datagram sizes 562 such as 576 bytes; worse, the absolute minimum value of the IP MTU 563 for IPv4 is as low as 68 bytes, which would leave only 40 bytes minus 564 security overhead for a UDP payload. Implementations extremely 565 focused on this problem set might also set the IPv4 DF bit and 566 perform some form of path MTU discovery; this should generally be 567 unnecessary in most realistic use cases for CoAP, however.) A more 568 important kind of fragmentation in many constrained networks is that 569 on the adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 570 bytes including various overheads); this may motivate implementations 571 to be frugal in their packet sizes and to move to block-wise 572 transfers [I-D.ietf-core-block] when approaching three-digit message 573 sizes. 575 Note that message sizes are also of considerable importance to 576 implementations on constrained nodes. Many implementations will need 577 to allocate a buffer for incoming messages. If an implementation is 578 too constrained to allow for allocating the above-mentioned upper 579 bound, it could apply the following implementation strategy: 580 Implementations receiving a datagram into a buffer that is too small 581 are usually able to determine if the trailing portion of a datagram 582 was discarded and to retrieve the initial portion. So, if not all of 583 the payload, at least the CoAP header and options are likely to fit 584 within the buffer. A server can thus fully interpret a request and 585 return a 4.13 (Request Entity Too Large) response code if the payload 586 was truncated. A client sending an idempotent request and receiving 587 a response larger than would fit in the buffer can repeat the request 588 with a suitable value for the Block Option [I-D.ietf-core-block]. 590 3.2. Option Format 592 Options MUST appear in order of their Option Number (see 593 Section 5.4.5). A delta encoding is used between options, with the 594 Option Number for each Option calculated as the sum of its Option 595 Delta field and the Option Number of the preceding Option in the 596 message, if any, or zero otherwise. Multiple options with the same 597 Option Number can be included by using an Option Delta of zero. 598 Following the Option Delta, each option has a Length field which 599 specifies the length of the Option Value, in bytes. The Length field 600 can be extended by one byte for options with values longer than 14 601 bytes. The Option Value immediately follows the Length field. 603 0 1 2 3 4 5 6 7 604 +---+---+---+---+---+---+---+---+ 605 | Option Delta | Length | for 0..14 606 +---+---+---+---+---+---+---+---+ 607 | Option Value ... 608 +---+---+---+---+---+---+---+---+ 609 for 15..270: 610 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 611 | Option Delta | 1 1 1 1 | Length - 15 | 612 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 613 | Option Value ... 614 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 616 Figure 7: Option Format 618 The fields in an option are defined as follows: 620 Option Delta: 4-bit unsigned integer. Indicates the difference 621 between the Option Number of this option and the previous option 622 (or zero for the first option). In other words, the Option Number 623 is calculated by simply summing the Option Delta fields of this 624 and previous options before it. The Option Numbers 14, 28, 42, 625 ... are reserved for no-op options when they are sent with an 626 empty value (they are ignored) and can be used as "fenceposts" if 627 deltas larger than 15 would otherwise be required. 629 Length: Indicates the length of the Option Value, in bytes. 630 Normally Length is a 4-bit unsigned integer allowing value lengths 631 of 0-14 bytes. When the Length field is set to 15, another byte 632 is added as an 8-bit unsigned integer whose value is added to the 633 15, allowing option value lengths of 15-270 bytes. 635 The length and format of the Option Value depends on the respective 636 option, which MAY define variable length values. Options defined in 637 this document make use of the following formats for option values: 639 uint: A non-negative integer which is represented in network byte 640 order using a variable number of bytes (see Appendix A). 642 string: A Unicode string which is encoded using UTF-8 [RFC3629] in 643 Net-Unicode form [RFC5198]. 645 opaque: An opaque sequence of bytes. 647 Option Numbers are maintained in the CoAP Option Number Registry 648 (Section 11.2). See Section 5.10 for the semantics of the options 649 defined in this document. 651 4. Message Semantics 653 CoAP messages are exchanged asynchronously between CoAP end-points. 654 They are used to transport CoAP requests and responses, the semantics 655 of which are defined in Section 5. 657 As CoAP is bound to non-reliable transports such as UDP, CoAP 658 messages may arrive out of order, appear duplicated, or go missing 659 without notice. For this reason, CoAP implements a lightweight 660 reliability mechanism, without trying to re-create the full feature 661 set of a transport like TCP. It has the following features: 663 o Simple stop-and-wait retransmission reliability with exponential 664 back-off for "confirmable" messages. 666 o Duplicate detection for both "confirmable" and "non-confirmable" 667 messages. 669 o Multicast support. 671 4.1. Reliable Messages 673 The reliable transmission of a message is initiated by marking the 674 message as "confirmable" in the CoAP header. A recipient MUST 675 acknowledge such a message with an acknowledgement message (or, if it 676 lacks context to process the message properly, MUST reject it with a 677 reset message). The sender retransmits the confirmable message at 678 exponentially increasing intervals, until it receives an 679 acknowledgement (or reset message), or runs out of attempts. 681 Retransmission is controlled by two things that a CoAP end-point MUST 682 keep track of for each confirmable message it sends while waiting for 683 an acknowledgement (or reset): a timeout and a retransmission 684 counter. For a new confirmable message, the initial timeout is set 685 to RESPONSE_TIMEOUT and the retransmission counter is set to 0. When 686 the timeout is triggered and the retransmission counter is less than 687 MAX_RETRANSMIT, the message is retransmitted, the retransmission 688 counter is incremented, and the timeout is doubled. If the 689 retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the 690 end-point receives a reset message, then the attempt to transmit the 691 message is cancelled and the application process informed of failure. 692 On the other hand, if the end-point receives an acknowledgement 693 message in time, transmission is considered successful. 695 An acknowledgement or reset message is related to a confirmable 696 message by means of a Message ID. The Message ID is a 16-bit 697 unsigned integer that is generated by the sender of a confirmable 698 message and included in the CoAP header. The Message ID MUST be 699 echoed in the acknowledgement or reset message by the recipient. A 700 CoAP end-point generates Message IDs by keeping a single Message ID 701 variable, which is changed each time a new confirmable message is 702 sent regardless of the destination address or port. The initial 703 variable value SHOULD be randomized. The same Message ID MUST NOT be 704 re-used within the potential retransmission window, calculated as 705 RESPONSE_TIMEOUT * (2 ^ MAX_RETRANSMIT - 1) plus the expected maximum 706 round trip time. 708 A recipient MUST be prepared to receive the same confirmable message 709 (as indicated by the Message ID) multiple times, for example, when 710 its acknowledgement went missing or didn't reach the original sender 711 before the first timeout. The recipient SHOULD acknowledge each 712 duplicate copy of a confirmable message using the same 713 acknowledgement or reset message, but SHOULD process any request or 714 response in the message only once. This rule MAY be relaxed in case 715 the confirmable message transports a request that is idempotent (see 716 Section 5.1). Examples for relaxed message deduplication: 718 o A server MAY relax the requirement to answer all retransmissions 719 of an idempotent request with the same response (Section 4.1), so 720 that it does not have to maintain state for Message IDs. For 721 example, an implementation might want to process duplicate 722 transmissions of a GET, PUT or DELETE request as separate requests 723 if the effort incurred by duplicate processing is less expensive 724 than keeping track of previous responses would be. 726 o (As an implementation consideration, a constrained server MAY even 727 want to relax this requirement for certain non-idempotent requests 728 if the application semantics make this trade-off favorable. For 729 example, if the result of a POST request is just the creation of 730 some short-lived state at the server, it may be less expensive to 731 incur this effort multiple times for a request than keeping track 732 of whether a previous transmission of the same request already was 733 processed.) 735 4.2. Unreliable Messages 737 As a more lightweight alternative, a message can be transmitted less 738 reliably by marking the message as "non-confirmable". A non- 739 confirmable message MUST NOT be acknowledged or be rejected by the 740 recipient. If a recipient lacks context to process the message 741 properly, the message MUST be silently ignored. 743 There is no way to detect if a non-confirmable message was received 744 or not at the CoAP-level. A sender MAY choose to transmit a non- 745 confirmable message multiple times which, for this purpose, specifies 746 a Message ID as well. The same rules for generating the Message ID 747 apply. 749 A recipient MUST be prepared to receive the same non-confirmable 750 message (as indicated by the Message ID) multiple times. As a 751 general rule that may be relaxed based on the specific semantics of a 752 message, the recipient SHOULD silently ignore any duplicated non- 753 confirmable message, and SHOULD process any request or response in 754 the message only once. 756 4.3. Message Types 758 The different types of messages are summarized below. The type of a 759 message is specified by the T field of the CoAP header. 761 Separate from the message type, a message may carry a request, a 762 response, or be empty. This is signalled by the Code field in the 763 CoAP header and is relevant to the request/response model. Possible 764 values for the Code field are maintained by the CoAP Code Registry 765 (Section 11.1). 767 An empty message has the Code field set to 0. The OC field SHOULD be 768 set to 0 and no bytes SHOULD be present after the Message ID field. 769 The OC field and any those bytes MUST be ignored by any recipient. 771 4.3.1. Confirmable (CON) 773 Some messages require an acknowledgement. These messages are called 774 "Confirmable". When no packets are lost, each confirmable message 775 elicits exactly one return message of type Acknowledgement or type 776 Reset. 778 A confirmable message always carries either a request or response and 779 MUST NOT be empty. 781 4.3.2. Non-Confirmable (NON) 783 Some other messages do not require an acknowledgement. This is 784 particularly true for messages that are repeated regularly for 785 application requirements, such as repeated readings from a sensor 786 where eventual arrival is sufficient. 788 A non-confirmable message always carries either a request or 789 response, as well, and MUST NOT be empty. 791 4.3.3. Acknowledgement (ACK) 793 An Acknowledgement message acknowledges that a specific confirmable 794 message (identified by its Message ID) arrived. It does not indicate 795 success or failure of any encapsulated request. 797 The acknowledgement message MUST echo the Message ID of the 798 confirmable message, and MUST carry a response or be empty (see 799 Section 5.2.1 and Section 5.2.2). 801 4.3.4. Reset (RST) 803 A Reset message indicates that a specific confirmable message was 804 received, but some context is missing to properly process it. This 805 condition is usually caused when the receiving node has rebooted and 806 has forgotten some state that would be required to interpret the 807 message. 809 A reset message MUST echo the Message ID of the confirmable message, 810 and MUST be empty. 812 4.4. Multicast 814 CoAP supports sending messages to multicast destination addresses. 815 Such multicast messages MUST be Non-Confirmable. Mechanisms for 816 avoiding congestion from multicast requests are being considered in 817 [I-D.eggert-core-congestion-control]. 819 4.5. Congestion Control 821 Basic congestion control for CoAP is provided by the exponential 822 back-off mechanism in Section 4.1. Further congestion control 823 optimizations are being considered and tested for CoAP 824 [I-D.eggert-core-congestion-control]. 826 5. Request/Response Semantics 828 CoAP operates under a similar request/response model as HTTP: a CoAP 829 end-point in the role of a "client" sends one or more CoAP requests 830 to a "server", which services the requests by sending CoAP responses. 831 Unlike HTTP, requests and responses are not sent over a previously 832 established connection, but exchanged asynchronously over CoAP 833 messages. 835 5.1. Requests 837 A CoAP request consists of the method to be applied to the resource, 838 the identifier of the resource, a payload and Internet media type (if 839 any), and optional meta-data about the request. 841 CoAP supports the basic methods of GET, POST, PUT, DELETE, which are 842 easily mapped to HTTP. They have the same properties of safe (only 843 retrieval) and idempotent (you can invoke it multiple times with the 844 same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method 845 is safe, therefore it MUST NOT take any other action on a resource 846 other than retrieval. The GET, PUT and DELETE methods MUST be 847 performed in such a way that they are idempotent. POST is not 848 idempotent, because its effect is determined by the origin server and 849 dependent on the target resource; it usually results in a new 850 resource being created or the target resource being updated. 852 A request is initiated by setting the Code field in the CoAP header 853 of a confirmable or a non-confirmable message to a Method Code and 854 including request information. 856 The methods used in requests are described in detail in Section 5.8. 858 5.2. Responses 860 After receiving and interpreting a request, a server responds with a 861 CoAP response, which can be matched to the request by means of a 862 client-generated token. 864 A response is identified by the Code field in the CoAP header being 865 set to a Response Code. Similar to the HTTP Status Code, the CoAP 866 Response Code indicates the result of the attempt to understand and 867 satisfy the request. These codes are fully defined in Section 5.9. 868 The Response Code numbers to be set in the Code field of the CoAP 869 header are maintained in the CoAP Response Code Registry 870 (Section 11.1.2). 872 0 873 0 1 2 3 4 5 6 7 874 +-+-+-+-+-+-+-+-+ 875 |class| detail | 876 +-+-+-+-+-+-+-+-+ 878 Figure 8: Structure of a Response Code 880 The upper three bits of the 8-bit Response Code number define the 881 class of response. The lower five bits do not have any 882 categorization role; they give additional detail to the overall class 883 (Figure 8). There are 3 classes: 885 2 - Success: The request was successfully received, understood, and 886 accepted. 888 4 - Client Error: The request contains bad syntax or cannot be 889 fulfilled. 891 5 - Server Error: The server failed to fulfill an apparently valid 892 request. 894 The response codes are designed to be extensible: Response Codes in 895 the Client Error and Server Error class that are unrecognized by an 896 end-point MUST be treated as being equivalent to the generic Response 897 Code of that class. However, there is no generic Response Code 898 indicating success, so a Response Code in the Success class that is 899 unrecognized by an end-point can only be used to determine that the 900 request was successful without any further details. 902 As a human readable notation for specifications and protocol 903 diagnostics, the numeric value of a response code is indicated by 904 giving the upper three bits in decimal, followed by a dot and then 905 the lower five bits in a two-digit decimal. E.g., "Not Found" is 906 written as 4.04 -- indicating a value of hexadecimal 0x84 or decimal 907 132. In other words, the dot "." functions as a short-cut for 908 "*32+". 910 The possible response codes are described in detail in Section 5.9. 912 Responses can be sent in multiple ways, which are defined below. 914 5.2.1. Piggy-backed 916 In the most basic case, the response is carried directly in the 917 acknowledgement message that acknowledges the request (which requires 918 that the request was carried in a confirmable message). This is 919 called a "Piggy-backed" Response. 921 The response is returned in the acknowledgement message independent 922 of whether the response indicates success or failure. In effect, the 923 response is piggy-backed on the acknowledgement message, so no 924 separate message is required to both acknowledge that the request was 925 received and return the response. 927 5.2.2. Separate 929 It may not be possible to return a piggy-backed response in all 930 cases. For example, a server might need longer to obtain the 931 representation of the resource requested than it can wait sending 932 back the acknowledgement message, without risking the client to 933 repeatedly retransmit the request message. 935 The server maybe initiates the attempt to obtain the resource 936 representation and times out an acknowledgement timer, or it 937 immediately sends an acknowledgement knowing in advance that there 938 will be no piggy-backed response. The acknowledgement effectively is 939 a promise that the request will be acted upon. 941 When the server finally has obtained the resource representation, it 942 sends the response. To ensure that this message is not lost, it is 943 again sent as a confirmable message and answered by the client with 944 an acknowledgement, echoing the new Message ID chosen by the server. 946 (Note that, as the underlying datagram transport may not be sequence- 947 preserving, the confirmable message carrying the response may 948 actually arrive before or after the acknowledgement message for the 949 request.) 951 For a separate exchange, both the acknowledgement to the confirmable 952 request and the acknowledgement to the confirmable response MUST be 953 an empty message, i.e. one that carries neither a request nor a 954 response. 956 5.2.3. Non-Confirmable 958 If the request message is non-confirmable, then the response SHOULD 959 be returned in a non-confirmable message as well. However, an end- 960 point MUST be prepared to receive a non-confirmable response 961 (preceded or followed an empty acknowledgement message) in reply to a 962 confirmable request, or a confirmable response in reply to a non- 963 confirmable request. 965 5.3. Request/Response Matching 967 Regardless of how a response is sent, it is matched to the request by 968 means of a token that is included by the client in the request as one 969 of the options. The token MUST be echoed by the server in any 970 resulting response without modification. 972 The exact rules for matching a response to a request are as follows: 974 1. For requests sent in a unicast message, the source of the 975 response MUST match the destination of the original request. How 976 this is determined depends on the security mode used (see 977 Section 10): With NoSec, the IP address and port number of the 978 request destination and response source must match. With other 979 security modes, in addition to the IP address and UDP port 980 matching, the request and response MUST have the same security 981 context. 983 2. In a piggy-backed response, both the Message ID of the 984 confirmable request and the acknowledgement, and the token of the 985 response and original request MUST match. In a separate 986 response, just the token of the response and original request 987 MUST match. 989 The client SHOULD generate tokens in a way that tokens currently in 990 use for a given source/destination pair are unique. (Note that a 991 client can use the same token for any request if it uses a different 992 source port number each time.) 994 An end-point receiving a token MUST treat it as opaque and make no 995 assumptions about its format. (Note that there is a default value 996 for the Token Option, so every message carries a token, even if it is 997 not explicitly expressed in a CoAP option.) 999 In case a confirmable message carrying a response is unexpected (i.e. 1000 the client is not waiting for a response with the specified address 1001 and/or token), the confirmable response SHOULD be rejected with a 1002 reset message and MUST NOT be acknowledged. 1004 5.4. Options 1006 Both requests and responses may include a list of one or more 1007 options. For example, the URI in a request is transported in several 1008 options, and meta-data that would be carried in an HTTP header in 1009 HTTP is supplied as options as well. 1011 CoAP defines a single set of options that are used in both requests 1012 and responses: 1014 o Content-Type 1016 o ETag 1018 o Location-Path 1020 o Location-Query 1022 o Max-Age 1024 o Proxy-Uri 1026 o Token 1028 o Uri-Host 1030 o Uri-Path 1032 o Uri-Port 1034 o Uri-Query 1036 The semantics of these options along with their properties are 1037 defined in detail in Section 5.10. 1039 Not all options have meaning with all methods and response codes. 1040 The possible options for methods and response codes are defined in 1041 Section 5.8 and Section 5.9 respectively. In case an option has no 1042 meaning, it SHOULD NOT be included by the sender and MUST be ignored 1043 by the recipient. 1045 5.4.1. Critical/Elective 1047 Options fall into one of two classes: "critical" or "elective". The 1048 difference between these is how an option unrecognized by an end- 1049 point is handled: 1051 o Upon reception, unrecognized options of class "elective" MUST be 1052 silently ignored. 1054 o Unrecognized options of class "critical" that occur in a 1055 confirmable request MUST cause the return of a 4.02 (Bad Option) 1056 response. This response SHOULD include a human-readable error 1057 message describing the unrecognized option(s) (see Section 5.5). 1059 o Unrecognized options of class "critical" that occur in a 1060 confirmable response SHOULD cause the response to be rejected with 1061 a reset message. 1063 o Unrecognized options of class "critical" that occur in a non- 1064 confirmable message MUST cause the message be silently ignored. 1066 Note that, whether critical or elective, an option is never 1067 "mandatory" (it is always optional): These rules are defined in order 1068 to enable implementations to reject options they do not understand or 1069 implement. 1071 5.4.2. Length 1073 Option values are defined to have a specific length, often in the 1074 form of an upper and lower bound. If the length of an option value 1075 in a request is outside the defined range, that option MUST be 1076 treated like an unrecognized option (see Section 5.4.1). 1078 5.4.3. Default Values 1080 Options may be defined to have a default value. If the value of 1081 option is intended to be this default value, the option SHOULD NOT be 1082 included in the message. If the option is not present, the default 1083 value MUST be assumed. 1085 5.4.4. Repeating Options 1087 Each definition of an option specifies whether it is defined to occur 1088 only at most once or whether it can occur multiple times. If a 1089 message includes an option with more instances than the option is 1090 defined for, the additional option instances MUST be treated like an 1091 unrecognized option (see Section 5.4.1). 1093 5.4.5. Option Numbers 1095 Options are identified by an option number. Odd numbers indicate a 1096 critical option, while even numbers indicate an elective option. 1097 (Note that this is not just a convention, it is a feature of the 1098 protocol: Whether an option is elective or critical is entirely 1099 determined by whether its option number is even or odd.) 1101 The numbers 14, 28, 42, ... are reserved for "fenceposting", as 1102 described in Section 3.2. As these option numbers are even, they 1103 stand for elective options, and unless assigned a meaning, these MUST 1104 be silently ignored. 1106 The option numbers for the options defined in this document are 1107 listed in the CoAP Option Number Registry (Section 11.2). 1109 5.5. Payload 1111 Both requests and responses may include payload, depending on the 1112 method or response code respectively. Methods with payload are PUT 1113 and POST, and the response codes with payload are 2.05 (Content) and 1114 the error codes. 1116 The payload of PUT, POST and 2.05 (Content) is typically a resource 1117 representation. Its format is specified by the Internet media type 1118 given by the Content-Type Option. A default value of "text/plain; 1119 charset=utf-8" is assumed in the absence of this option. 1121 A response with a code indicating a Client or Server Error SHOULD 1122 include a brief human-readable diagnostic message as payload, 1123 explaining the error situation. This diagnostic message MUST be 1124 encoded using UTF-8 [RFC3629], more specifically using Net-Unicode 1125 form [RFC5198]. The Content-Type Option has no meaning and SHOULD 1126 NOT be included. (Similar to what one would find as a Reason-Phrase 1127 on an HTTP status line, the message is not intended for end-users but 1128 for software engineers that during debugging need to interpret it in 1129 the context of the present, English-language specification; therefore 1130 no language tagging is foreseen.) 1132 If a method or response code is not defined to have a payload, then 1133 the sender SHOULD NOT include one, and the recipient MUST ignore it. 1135 5.6. Caching 1137 CoAP end-points MAY cache responses in order to reduce the response 1138 time and network bandwidth consumption on future, equivalent 1139 requests. 1141 The goal of caching in CoAP is to reuse a prior response message to 1142 satisfy a current request. In some cases, a stored response can be 1143 reused without the need for a network request, reducing latency and 1144 network round-trips; a "freshness" mechanism is used for this purpose 1145 (see Section 5.6.1). Even when a new request is required, it is 1146 often possible to reuse the payload of a prior response to satisfy 1147 the request, thereby reducing network bandwidth usage; a "validation" 1148 mechanism is used for this purpose (see Section 5.6.2). 1150 Unlike HTTP, the cacheability of CoAP responses does not depend on 1151 the request method, but the Response Code. The cacheability of each 1152 Response Code is defined along the Response Code definitions in 1153 Section 5.9. Response Codes that indicate success and are 1154 unrecognized by an end-point MUST NOT be cached. 1156 For a presented request, a CoAP end-point MUST NOT use a stored 1157 response, unless: 1159 o the presented request method and that used to obtain the stored 1160 response match, 1162 o all options match between those in the presented request and those 1163 of the request used to obtain the stored response (which includes 1164 the request URI), except that there is no need for a match of the 1165 Token, Max-Age, or ETag request option(s), and 1167 o the stored response is either fresh or successfully validated as 1168 defined below. 1170 5.6.1. Freshness Model 1172 When a response is "fresh" in the cache, it can be used to satisfy 1173 subsequent requests without contacting the origin server, thereby 1174 improving efficiency. 1176 The mechanism for determining freshness is for an origin server to 1177 provide an explicit expiration time in the future, using the Max-Age 1178 Option (see Section 5.10.5). The Max-Age Option indicates that the 1179 response is to be considered not fresh after its age is greater than 1180 the specified number of seconds. 1182 As the Max-Age Option defaults to a value of 60, if it is not present 1183 in a cacheable response, then the response is considered not fresh 1184 after its age is greater than 60 seconds. If an origin server wishes 1185 to prevent caching, it MUST explicitly include a Max-Age Option with 1186 a value of zero seconds. 1188 5.6.2. Validation Model 1190 When an end-point has one or more stored responses for a GET request, 1191 but cannot use any of them (e.g., because they are not fresh), it can 1192 use the ETag Option in the GET request to give the origin server an 1193 opportunity to both select a stored response to be used, and to 1194 update its freshness. This process is known as "validating" or 1195 "revalidating" the stored response. 1197 When sending such a request, the end-point SHOULD add an ETag Option 1198 specifying the entity-tag of each stored response that is applicable. 1200 A 2.03 (Valid) response indicates the stored response identified by 1201 the entity-tag given in the response's ETag Option can be reused, 1202 after updating its freshness with the value of the Max-Age Option 1203 that is included with the response (see Section 5.9.1.3). 1205 Any other response code indicates that none of the stored responses 1206 nominated in the request is suitable. Instead, the response SHOULD 1207 be used to satisfy the request and MAY replace the stored response. 1209 5.7. Proxying 1211 CoAP distinguishes between requests to an origin server and a request 1212 made through a proxy. A proxy is a CoAP end-point that can be tasked 1213 by CoAP clients to perform requests on their behalf. This may be 1214 useful, for example, when the request could otherwise not be made, or 1215 to service the response from a cache in order to reduce response time 1216 and network bandwidth or energy consumption. 1218 CoAP requests to a proxy are made as normal confirmable or non- 1219 confirmable requests to the proxy end-point, but specify the request 1220 URI in a different way: The request URI in a proxy request is 1221 specified as a string in the Proxy-Uri Option (see Section 5.10.3), 1222 while the request URI in a request to an origin server is split into 1223 the Uri-Host, Uri-Port, Uri-Path and Uri-Query Options (see 1224 Section 5.10.2). 1226 When a proxy request is made to an end-point and the end-point is 1227 unwilling or unable to act as proxy for the request URI, it MUST 1228 return a 5.05 (Proxying Not Supported) response. If the authority 1229 (host and port) is recognized as identifying the proxy end-point, 1230 then the request MUST be treated as a local request. 1232 Unless a proxy is configured to forward the proxy request to another 1233 proxy, it MUST translate the request as follows: The origin server's 1234 IP address and port are determined by the authority component of the 1235 request URI, and the request URI is decoded and split into the Uri- 1236 Host, Uri-Port, Uri-Path and Uri-Query Options. 1238 All options present in a proxy request MUST be processed at the 1239 proxy. Critical options in a request that are not recognized by the 1240 proxy MUST lead to a 4.02 (Bad Option) response being returned by the 1241 proxy. Elective options not recognized by the proxy MUST NOT be 1242 forwarded to the origin server. Similarly, critical options in a 1243 response that are not recognized by the proxy server MUST lead to a 1244 5.02 (Bad Gateway) response. Again, elective options that are not 1245 recognized MUST NOT be forwarded. 1247 If the proxy does not employ a cache, then it simply forwards the 1248 translated request to the determined destination. Otherwise, if it 1249 does employ a cache but does not have a stored response that matches 1250 the translated request and is considered fresh, then it needs to 1251 refresh its cache according to Section 5.6. 1253 If the request to the destination times out, then a 5.04 (Gateway 1254 Timeout) response MUST be returned. If the request to the 1255 destination returns an response that cannot be processed by the 1256 proxy, then a 5.02 (Bad Gateway) response MUST be returned. 1257 Otherwise, the proxy returns the response to the client. 1259 If a response is generated out of a cache, it MUST be generated with 1260 a max-age option that does not extend the max-age originally set by 1261 the server, considering the time the resource representation spent in 1262 the cache. E.g., the Max-Age option could be adjusted by the proxy 1263 for each response using the formula: proxy-max-age = original-max-age 1264 - cache-age. For example if a request is made to a proxied resource 1265 that was refreshed 20 seconds ago and had an original Max-Age of 60 1266 seconds, then that resource's proxied Max-Age is now 40 seconds. 1268 5.8. Method Definitions 1270 In this section each method is defined along with its behavior. A 1271 request with an unrecognized or unsupported Method Code MUST generate 1272 a 4.05 (Method Not Allowed) response. 1274 5.8.1. GET 1276 The GET method retrieves a representation for the information that 1277 currently corresponds to the resource identified by the request URI. 1278 If the request includes an ETag Option, the GET method requests that 1279 ETag be validated and that the representation be transferred only if 1280 validation failed. Upon success a 2.05 (Content) or 2.03 (Valid) 1281 response SHOULD be sent. 1283 The GET method is safe and idempotent. 1285 5.8.2. POST 1287 The POST method requests that the representation enclosed in the 1288 request be processed. The actual function performed by the POST 1289 method is determined by the origin server and dependent on the target 1290 resource. It usually results in a new resource being created or the 1291 target resource being updated. 1293 If a resource has been created on the server, a 2.01 (Created) 1294 response that includes the URI of the new resource in a sequence of 1295 one or more Location-Path Options and/or a Location-Query Option 1296 SHOULD be returned. If the POST succeeds but does not result in a 1297 new resource being created on the server, a 2.04 (Changed) response 1298 SHOULD be returned. If the POST succeeds and results in the target 1299 resource being deleted, a 2.02 (Deleted) response SHOULD be returned. 1301 If the request passes through a cache that has one or more stored 1302 responses for the request URI, those stored responses SHOULD be 1303 marked as stale. 1305 POST is neither safe nor idempotent. 1307 5.8.3. PUT 1309 The PUT method requests that the resource identified by the request 1310 URI be updated or created with the enclosed representation. The 1311 representation format is specified by the media type given in the 1312 Content-Type Option. 1314 If a resource exists at the request URI the enclosed representation 1315 SHOULD be considered a modified version of that resource, and a 2.04 1316 (Changed) response SHOULD be returned. If no resource exists then 1317 the server MAY create a new resource with that URI, resulting in a 1318 2.01 (Created) response. If the resource could not be created or 1319 modified, then an appropriate error response code SHOULD be sent. 1321 If the request passes through a cache that has one or more stored 1322 responses for the request URI, those stored responses SHOULD be 1323 marked as stale. 1325 PUT is not safe, but idempotent. 1327 5.8.4. DELETE 1329 The DELETE method requests that the resource identified by the 1330 request URI be deleted. A 2.02 (Deleted) response SHOULD be sent on 1331 success or in case the resource did not exist before the request. 1333 If the request passes through a cache and the request URI identifies 1334 one or more currently stored responses, those entries SHOULD be 1335 marked as stale. 1337 DELETE is not safe, but idempotent. 1339 5.9. Response Code Definitions 1341 Each response code is described below, including any options required 1342 in the response. Where appropriate, some of the codes will be 1343 specified in regards to related response codes in HTTP [RFC2616]; 1344 this does not mean that any such relationship modifies the HTTP 1345 mapping specified in Section 8. 1347 5.9.1. Success 2.xx 1349 This class of status code indicates that the clients request was 1350 successfully received, understood, and accepted. 1352 5.9.1.1. 2.01 Created 1354 Like HTTP 201 "Created", but only used in response to POST and PUT 1355 requests. 1357 If the response includes one or more Location-Path Options and/or a 1358 Location-Query Option, the values of these options specify the 1359 location at which the resource was created. Otherwise, the resource 1360 was created at the request URI. A cache SHOULD mark any stored 1361 response for the location as not fresh. 1363 This response is not cacheable. 1365 5.9.1.2. 2.02 Deleted 1367 Like HTTP 204 "No Content", but only used in response to DELETE 1368 requests. 1370 This response is not cacheable. 1372 5.9.1.3. 2.03 Valid 1374 Related to HTTP 304 "Not Modified", but only used to indicate that 1375 the response identified by the entity-tag identified by the included 1376 ETag Option is valid. Accordingly, the response MUST include an ETag 1377 Option. 1379 When a cache receives a 2.03 (Valid) response, it needs to update the 1380 stored response with the value of the Max-Age Option included in the 1381 response (see Section 5.6.2). 1383 5.9.1.4. 2.04 Changed 1385 Like HTTP 204 "No Content", but only used in response to POST and PUT 1386 requests. 1388 This response is not cacheable. 1390 5.9.1.5. 2.05 Content 1392 Like HTTP 200 "OK", but only used in response to GET requests. 1394 The payload returned with the response is a representation of the 1395 target resource. The representation format is specified by the media 1396 type given in the Content-Type Option. 1398 This response is cacheable: Caches can use the Max-Age Option to 1399 determine freshness (see Section 5.6.1) and (if present) the ETag 1400 Option for validation (see Section 5.6.2). 1402 5.9.2. Client Error 4.xx 1404 This class of response code is intended for cases in which the client 1405 seems to have erred. These response codes are applicable to any 1406 request method. 1408 The server SHOULD include a brief human-readable message as payload, 1409 as detailed in Section 5.5. 1411 Responses of this class are cacheable: Caches can use the Max-Age 1412 Option to determine freshness (see Section 5.6.1). They cannot be 1413 validated. 1415 5.9.2.1. 4.00 Bad Request 1417 Like HTTP 400 "Bad Request". 1419 5.9.2.2. 4.01 Unauthorized 1421 The client is not authorized to perform the requested action. The 1422 client SHOULD NOT repeat the request without previously improving its 1423 authentication status to the server. Which specific mechanism can be 1424 used for this is outside this document's scope; see also Section 10. 1426 5.9.2.3. 4.02 Bad Option 1428 The request could not be understood by the server due to one or more 1429 unrecognized or malformed critical options. The client SHOULD NOT 1430 repeat the request without modification. 1432 5.9.2.4. 4.03 Forbidden 1434 Like HTTP 403 "Forbidden". 1436 5.9.2.5. 4.04 Not Found 1438 Like HTTP 404 "Not Found". 1440 5.9.2.6. 4.05 Method Not Allowed 1442 Like HTTP 405 "Method Not Allowed", but with no parallel to the 1443 "Accept" header field. 1445 5.9.2.7. 4.13 Request Entity Too Large 1447 Like HTTP 413 "Request Entity Too Large". 1449 5.9.2.8. 4.15 Unsupported Media Type 1451 Like HTTP 415 "Unsupported Media Type". 1453 5.9.3. Server Error 5.xx 1455 This class of response code indicates cases in which the server is 1456 aware that it has erred or is incapable of performing the request. 1457 These response codes are applicable to any request method. 1459 The server SHOULD include a human-readable message as payload, as 1460 detailed in Section 5.5. 1462 Responses of this class are cacheable: Caches can use the Max-Age 1463 Option to determine freshness (see Section 5.6.1). They cannot be 1464 validated. 1466 5.9.3.1. 5.00 Internal Server Error 1468 Like HTTP 500 "Internal Server Error". 1470 5.9.3.2. 5.01 Not Implemented 1472 Like HTTP 501 "Not Implemented". 1474 5.9.3.3. 5.02 Bad Gateway 1476 Like HTTP 502 "Bad Gateway". 1478 5.9.3.4. 5.03 Service Unavailable 1480 Like HTTP 503 "Service Unavailable", but using the Max-Age Option in 1481 place of the "Retry-After" header field. 1483 5.9.3.5. 5.04 Gateway Timeout 1485 Like HTTP 504 "Gateway Timeout". 1487 5.9.3.6. 5.05 Proxying Not Supported 1489 The server is unable or unwilling to act as a proxy for the URI 1490 specified in the Proxy-Uri Option (see Section 5.10.3). 1492 5.10. Option Definitions 1494 The individual CoAP options are summarized in Table 1 and explained 1495 below. 1497 +-----+----------+----------------+--------+---------+-------------+ 1498 | No. | C/E | Name | Format | Length | Default | 1499 +-----+----------+----------------+--------+---------+-------------+ 1500 | 1 | Critical | Content-Type | uint | 1-2 B | 0 | 1501 | 2 | Elective | Max-Age | uint | 0-4 B | 60 | 1502 | 3 | Critical | Proxy-Uri | string | 1-270 B | (none) | 1503 | 4 | Elective | ETag | opaque | 1-8 B | (none) | 1504 | 5 | Critical | Uri-Host | string | 1-270 B | (see below) | 1505 | 6 | Elective | Location-Path | string | 1-270 B | (none) | 1506 | 7 | Critical | Uri-Port | uint | 0-2 B | (see below) | 1507 | 8 | Elective | Location-Query | string | 1-270 B | (none) | 1508 | 9 | Critical | Uri-Path | string | 1-270 B | (none) | 1509 | 11 | Critical | Token | opaque | 1-8 B | (empty) | 1510 | 15 | Critical | Uri-Query | string | 1-270 B | (none) | 1511 +-----+----------+----------------+--------+---------+-------------+ 1513 Table 1: Options 1515 5.10.1. Token 1517 The Token Option is used to match a response with a request. Every 1518 request has a client-generated token which the server MUST echo in 1519 any response. 1521 A token is intended for use as a client-local identifier for 1522 differentiating between concurrent requests. A client SHOULD 1523 generate tokens in a way that tokens currently in use for a given 1524 source/destination pair are unique. An end-point receiving a token 1525 MUST treat it as opaque and make no assumptions about its format. 1527 A default value of a zero-length token is assumed in the absence of 1528 the option. 1530 This option is "critical". It MUST NOT occur more than once. 1532 5.10.2. Uri-Host, Uri-Port, Uri-Path and Uri-Query 1534 The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to 1535 specify the target resource of a request to a CoAP origin server. 1536 The options encode the different components of the request URI in a 1537 way that no percent-encoding is visible in the option values (except 1538 for Uri-Query) and that the full URI can be reconstructed at any 1539 involved end-point. The syntax of CoAP URIs is defined in Section 6. 1541 The steps for parsing URIs into options is defined in Section 6.3. 1542 These steps result in zero or more Uri-Host, Uri-Port, Uri-Path and 1543 Uri-Query Options being included in a request, where each option 1544 holds the following values: 1546 o the Uri-Host Option specifies the Internet host of the resource 1547 being requested, 1549 o the Uri-Port Option specifies the port number of the resource, 1551 o each Uri-Path Option specifies one segment of the absolute path to 1552 the resource, and 1554 o the Uri-Query Option specifies the query. 1556 Note: Fragments ([RFC3986], Section 3.5) are not part of the request 1557 URI and thus will not be transmitted in a CoAP request. 1559 The default value of the Uri-Host Option is the IP literal 1560 representing the destination IP address of the request message. 1561 Likewise, the default value of the Uri-Port Option is the destination 1562 UDP port. 1564 The Uri-Path Option can contain any character sequence. No percent- 1565 encoding is performed. The value MUST NOT be "." or ".." (as the 1566 request URI must be resolved before parsing it into options). 1568 The steps for constructing the request URI from the options are 1569 defined in Section 6.4. Note that an implementation does not 1570 necessarily have to construct the URI; it can simply look up the 1571 target resource by looking at the individual options. 1573 Examples can be found in Appendix C. 1575 All of the options are "critical". Uri-Host, Uri-Port and Uri-Query 1576 MUST NOT occur more than once; Uri-Path MAY occur one or more times. 1578 5.10.3. Proxy-Uri 1580 The Proxy-Uri Option is used to make a request to a proxy (see 1581 Section 5.7). The proxy is requested to forward the request or 1582 service it from a valid cache, and return the response. 1584 The option value is an absolute-URI ([RFC3986], Section 4.3). In 1585 case the absolute-URI doesn't fit within a single option, the Proxy- 1586 Uri Option MAY be included multiple times in a request such that the 1587 concatenation of the values results in the single absolute-URI. 1589 All but the last instance of the Proxy-Uri Option MUST have a value 1590 with a length of 270 bytes, and the last instance MUST NOT be empty. 1592 Note that the proxy MAY forward the request on to another proxy or 1593 directly to the server specified by the absolute-URI. In order to 1594 avoid request loops, a proxy MUST be able to recognize all of its 1595 server names, including any aliases, local variations, and the 1596 numeric IP addresses. 1598 An end-point receiving a request with a Proxy-Uri Option that is 1599 unable or unwilling to act as a proxy for the request MUST cause the 1600 return of a 5.05 (Proxying Not Supported) response. 1602 This option is "critical". It MAY occur one or more times and MUST 1603 take precedence over any of the Uri-Host, Uri-Port, Uri-Path or Uri- 1604 Query options (which MUST NOT be included at the same time). 1606 5.10.4. Content-Type 1608 The Content-Type Option indicates the representation format of the 1609 message payload. The representation format is given as a numeric 1610 media type identifier that is defined in the CoAP Media Type registry 1611 (Section 11.3). A default value of 0 (meaning "text/plain; 1612 charset=utf-8") is assumed in the absence of the option. 1614 This option is "critical". It MUST NOT occur more than once. 1616 5.10.5. Max-Age 1618 The Max-Age Option indicates the maximum time a response may be 1619 cached before it MUST be considered not fresh (see Section 5.6.1). 1621 The option value is an integer number of seconds between 0 and 2^32-1 1622 inclusive (about 136.1 years). A default value of 60 seconds is 1623 assumed in the absence of the option in a response. 1625 This option is "elective". It MUST NOT occur more than once. 1627 5.10.6. ETag 1629 The ETag Option in a response provides the current value of the 1630 entity-tag for the enclosed representation of the target resource. 1632 An entity-tag is intended for use as a resource-local identifier for 1633 differentiating between representations of the same resource that 1634 vary over time. It may be generated in any number of ways including 1635 a version, checksum, hash or time. An end-point receiving an entity- 1636 tag MUST treat it as opaque and make no assumptions about its format. 1637 (End-points generating an entity-tag are encouraged to use the most 1638 compact representation possible, in particular in regards to clients 1639 and intermediaries that may want to store multiple ETag values.) 1641 An end-point that has one or more representations previously obtained 1642 from the resource can specify the ETag Option in a request for each 1643 stored response to determine if any of those representations is 1644 current (see Section 5.6.2). 1646 This option is "elective". It MUST NOT occur more than once in a 1647 response, and MAY occur one or more times in a request. 1649 5.10.7. Location-Path and Location-Query 1651 The Location-Path and Location-Query Options indicates the location 1652 of a resource as an absolute path URI. The Location-Path Option is 1653 similar to the Uri-Path Option, and the Location-Query Option similar 1654 to the Uri-Query Option. 1656 The two options MAY be included in a response to indicate the 1657 location of a new resource created with POST. 1659 If a response with a Location-Path and/or Location-Query Option 1660 passes through a cache and the implied URI identifies one or more 1661 currently stored responses, those entries SHOULD be treated as stale. 1663 Both options are "elective". Location-Path MAY occur one or more 1664 times. Location-Query MUST NOT occur more than once. 1666 6. CoAP URIs 1668 CoAP uses the "coap" URI scheme for identifying CoAP resources and 1669 providing a means of locating the resource. Resources are organized 1670 hierarchically and governed by a potential CoAP origin server 1671 listening for CoAP requests on a given UDP port. The CoAP server is 1672 identified via the generic syntax's authority component, which 1673 includes a host identifier and optional UDP port number. The 1674 remainder of the URI is considered to be identifying a resource which 1675 can be operated on by the methods defined by the CoAP protocol. CoAP 1676 URIs can thus be compared to the "http" URI scheme. 1678 6.1. URI Scheme Syntax 1680 The syntax of the "coap" URI scheme is specified below in Augmented 1681 Backus-Naur Form (ABNF) [RFC5234]. The definitions of "host", 1682 "port", "path-abempty", and "query", "segment", "IP-literal", 1683 "IPv4address" and "reg-name" are adopted from [RFC3986]. 1685 coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] 1687 If host is provided as an IP-literal or IPv4address, then the CoAP 1688 server is located at that IP address. If host is a registered name, 1689 then that name is considered an indirect identifier and the end-point 1690 might use a name resolution service, such as DNS, to find the address 1691 of that host. The host MUST NOT be empty. The port subcomponent 1692 indicates the UDP port at which the CoAP server is located. If it is 1693 empty or not given, then the default port [IANA_TBD_PORT] is assumed. 1695 The path identifies a resource within the scope of the host and port. 1696 It consists of a sequence of path segments separated by a slash ("/") 1697 character. The query serves to further parametrize the resource, 1698 often in the form of "key=value" pairs. 1700 The "coap" URI scheme supports the path prefix "/.well-known/" 1701 defined by [RFC5785] for "well-known locations" in the name-space of 1702 a host. This enables discovery of policy or other information about 1703 a host ("site-wide metadata"), such as hosted resources (see 1704 Section 7.1). 1706 Application designers are encouraged to make use of short, but 1707 descriptive URIs. As the environments that CoAP is used in are 1708 usually constrained for bandwidth and energy, the trade-off between 1709 these two qualities should lean towards the shortness, without 1710 ignoring descriptiveness. 1712 6.2. Normalization and Comparison Rules 1714 Since the "coap" scheme conforms to the URI generic syntax, URIs of 1715 this scheme are normalized and compared according to the algorithm 1716 defined in [RFC3986], Section 6. 1718 If the port is equal to the default port [IANA_TBD_PORT], the normal 1719 form is to elide the port component. Likewise, an empty path 1720 component is equivalent to an absolute path of "/", so the normal 1721 form is to provide a path of "/" instead. The scheme and host are 1722 case-insensitive and normally provided in lowercase; IP-literals are 1723 in recommended form [RFC5952]; all other components are compared in a 1724 case-sensitive manner. Characters other than those in the "reserved" 1725 set are equivalent to their percent-encoded octets (see [RFC3986], 1726 Section 2.1): the normal form is to not encode them. 1728 For example, the following three URIs are equivalent, and cause the 1729 same options and option values to appear in the CoAP messages: 1731 coap://example.com:[IANA_TBD_PORT]/~sensors/temp.xml 1733 coap://EXAMPLE.com/%7Esensors/temp.xml 1735 coap://EXAMPLE.com:/%7esensors/temp.xml 1737 6.3. Parsing URIs 1739 The steps to parse a request's options from a string /url/ are as 1740 follows. These steps either result in zero or more of the Uri-Host, 1741 Uri-Port, Uri-Path and Uri-Query Options being included in the 1742 request, or they fail. 1744 1. If the /url/ string is not an absolute URI ([RFC3986]), then fail 1745 this algorithm. 1747 2. Resolve the /url/ string using the process of reference 1748 resolution defined by [RFC3986], with the URL character encoding 1749 set to UTF-8 [RFC3629]. 1751 NOTE: It doesn't matter what it is resolved relative to, since we 1752 already know it is an absolute URL at this point. 1754 3. If /url/ does not have a component whose value, when 1755 converted to ASCII lowercase, is "coap", then fail this 1756 algorithm. 1758 4. If /url/ has a component, then fail this algorithm. 1760 5. If the component of /url/ does not represent the request's 1761 destination IP address as an IP-literal or IPv4address, include a 1762 Uri-Host Option and let that option's value be the value of the 1763 component of /url/, converted to ASCII lowercase, and then 1764 converting each percent-encoding ("%" followed by two hexadecimal 1765 digits) to the corresponding byte. 1767 NOTE: In the usual case where the request's destination IP 1768 address is derived from the host part, this ensures that Uri-Host 1769 Options are only used for host parts of the form reg-name. 1771 6. If /url/ has a component, then let /port/ be that 1772 component's value interpreted as a decimal integer; otherwise, 1773 let /port/ be the default port [IANA_TBD_PORT]. 1775 7. If /port/ does not equal the request's destination UDP port, 1776 include a Uri-Port Option and let that option's value be /port/. 1778 8. If the value of the component of /url/ is empty or 1779 consists of a single slash character (U+002F SOLIDUS "/"), then 1780 move to the next step. 1782 Otherwise, for each segment in the component, include a 1783 Uri-Path Option and let that option's value be the segment (not 1784 including the delimiting slash characters) after converting each 1785 percent-encoding ("%" followed by two hexadecimal digits) to the 1786 corresponding byte. 1788 9. If /url/ has a component, then include a Uri-Query Option 1789 and let that option's value be the value of the component 1790 (not including the delimiting question mark). (Note that, in 1791 contrast to the other components, percent-encodings stay intact 1792 in the Uri-Query option.) 1794 Note that these rules completely resolve any percent-encoding except 1795 in a reg-name and in a query. 1797 6.4. Constructing URIs 1799 The steps to construct a URI from a request's options are as follows. 1800 These steps either result in a URI, or they fail. In these steps, 1801 percent-encoding a character means replacing each of its (UTF-8 1802 encoded) bytes by a "%" character followed by two hexadecimal digits 1803 representing the byte, where the digits A-F are in upper case (as 1804 defined in [RFC3986] Section 2.1; to reduce variability, the 1805 hexadecimal notation in CoAP URIs MUST use uppercase letters). 1807 1. Let /url/ be the string "coap://". 1809 2. If the request includes a Uri-Host Option, let /host/ be that 1810 option's value, where any non-ASCII characters are replaced by 1811 their corresponding percent-encoding. If /host/ is not a valid 1812 reg-name or IP-literal or IPv4address, fail the algorithm. 1813 Otherwise, let /host/ be the IP-literal (making use of the 1814 conventions of [RFC5952]) or IPv4address representing the 1815 request's destination IP address. 1817 3. Append /host/ to /url/. 1819 4. If the request includes a Uri-Port Option, let /port/ be that 1820 option's value. Otherwise, let /port/ be the request's 1821 destination UDP port. 1823 5. If /port/ is not the default port [IANA_TBD_PORT], then append a 1824 single U+003A COLON character (:) followed by the decimal 1825 representation of /port/ to /url/. 1827 6. Let /resource name/ be the empty string. For each Uri-Path 1828 Option in the request, append a single character U+002F SOLIDUS 1829 (/) followed by the option's value to /resource name/, after 1830 converting any character that is not either in the "unreserved" 1831 set, "sub-delims" set, a U+003A COLON character (:) or U+0040 1832 COMMERCIAL AT (@), to its percent-encoded form. 1834 7. If /resource name/ is the empty string, set it to a single 1835 character U+002F SOLIDUS (/). 1837 8. Append /resource name/ to /url/. 1839 9. If the request includes a Uri-Query Option, append a single 1840 U+003F QUESTION MARK character (?) to /url/, followed by the 1841 option's value. 1843 10. Return /url/. 1845 Note that these steps have been designed to lead to a URI in normal 1846 form (see Section 6.2). 1848 7. Finding and Addressing CoAP End-Points 1850 7.1. Resource Discovery 1852 The discovery of resources offered by a CoAP end-point is extremely 1853 important in machine-to-machine applications where there are no 1854 humans in the loop and static interfaces result in fragility. A CoAP 1855 end-point SHOULD support the CoRE Link Format of discoverable 1856 resources as described in [I-D.ietf-core-link-format]. 1858 7.2. Default Port 1860 The CoAP default port number [IANA_TBD_PORT] MUST be supported by a 1861 server for resource discovery and SHOULD be supported for providing 1862 access to other resources. In addition other end-points may be 1863 hosted in the dynamic port space. 1865 When a CoAP server is hosted by a 6LoWPAN node, it SHOULD also 1866 support a port in the 61616-61631 compressed UDP port space defined 1867 in [RFC4944]. 1869 7.3. Multiplexing DTLS and CoAP 1871 The CoAP encoding has been chosen to enable demultiplexing of two 1872 kinds of packets that arrive on a single UDP port: 1874 o CoAP messages directly sent within UDP 1876 o DTLS 1.1 or 1.2 messages (which might contain CoAP messages) on 1877 UDP 1879 Possibly less importantly, a distinction can also be made between 1880 these two and: 1882 o STUN messages on UDP 1884 This demultiplexing is possible because DTLS 1.1 or 1.2 UDP payloads 1885 begin with a byte out of: 1887 enum { 1888 change_cipher_spec(20), alert(21), handshake(22), 1889 application_data(23), (255) 1890 } ContentType; 1892 Figure 9: TLS ContentType 1894 i.e. 0x14 to 0x17 hex [RFC4347]. In a CoAP message, such an initial 1895 byte would be decoded as a CoAP version 0, which is not in use. 1897 7.3.1. Future-Proofing the Multiplexing 1899 To maintain this property, future versions of CoAP will not use 1900 version number 0. Note that future versions of DTLS might 1901 theoretically start to use "ContentType" values that fall into the 1902 range of 64 to 127; CoAP implementations would then not be able to 1903 reliably multiplex these new kinds of DTLS datagrams with CoAP 1904 datagrams on the same UDP port. To maintain transparency for this 1905 case, an initial byte of 0x11 (17 decimal) is inserted on 1906 transmission and discarded upon reception; the rest of the datagram 1907 is interpreted as the DTLS message. 0x11 MUST NOT be followed by 0x14 1908 to 0x17 hex, i.e. the DTLS messages defined by DTLS 1.1 and 1.2 are 1909 always sent unescaped. Datagrams starting with 0x11 and then 0x14 to 1910 0x17 MUST be discarded. 1912 Similarly, STUN messages begin with 00mmmmmc binary (MSBs) [RFC5389] 1913 and so far happen to use an encoding for mmmmmc that also enables 1914 this initial byte to be distinguished from valid DTLS messages. 1915 Again, future versions of CoAP will need to avoid using version 1916 number 0. STUN messages are most likely to begin with 0x00 and 0x01. 1917 All other STUN messages MUST be escaped with an initial 0x10 byte (16 1918 decimal). 0x10 MUST NOT be followed by 0x00 or 0x01 hex, i.e. the 1919 more likely STUN messages are always sent unescaped. 1921 Future versions of CoAP could potentially make changes to the CoAP 1922 header structure that are not backwards compatible to the current 1923 version. In order to allow demultiplexing those packets that adhere 1924 to the present version of CoAP from those using the future version, 1925 the new version may want to increase the CoAP version number in the 1926 header (fixed at "1" in the present specification) and/or make other 1927 changes in the initial byte and/or the escaping rules. Whatever 1928 these changes may be, their objective will be to enable seamless 1929 interworking of existing and new protocol implementations to enable 1930 an orderly transition to the new version. 1932 Note that the escaping rules defined in this section are insurance 1933 for the future; they need no additional code in implementations that 1934 do not implement STUN or DTLS or implement only the versions current 1935 at the time of writing. For easy reference, Table 2 summarizes the 1936 rules upon reception. 1938 +--------------+-------------+----------------+ 1939 | initial byte | disposition | interpretation | 1940 +--------------+-------------+----------------+ 1941 | 0x00 or 0x01 | keep | STUN | 1942 | 0x10 | remove | STUN | 1943 | 0x11 | remove | DTLS | 1944 | 0x14 to 0x17 | keep | DTLS | 1945 | 0x40 to 0x7F | keep | CoAP | 1946 | all others | | (invalid) | 1947 +--------------+-------------+----------------+ 1949 Table 2: Interpretation of initial byte when multiplexing 1951 8. HTTP Mapping 1953 CoAP supports a limited subset of HTTP functionality, and thus a 1954 mapping to HTTP is straightforward. There might be several reasons 1955 for mapping between CoAP and HTTP, for example when designing a web 1956 interface for use over either protocol or when realizing a CoAP-HTTP 1957 proxy. Likewise, CoAP could equally be mapped to other protocols 1958 such as XMPP [RFC3920] or SIP [RFC3264], the definition of these 1959 mappings is out of scope of this specification. 1961 This section discusses two ways of mapping: 1963 CoAP-HTTP Mapping: Enables CoAP clients to access resources on HTTP 1964 servers through an intermediary. This is initiated by including 1965 the Proxy-Uri Option with an "http" URI in a CoAP request to a 1966 CoAP-HTTP proxy, or by sending a CoAP request to a reverse proxy 1967 that maps CoAP to HTTP. 1969 HTTP-CoAP Mapping: Enables HTTP clients to access resources on CoAP 1970 servers through an intermediary. This is initiated by specifying 1971 a "coap" URI in the Request-Line of an HTTP request to an HTTP- 1972 CoAP proxy, or by sending an HTTP request to a reverse proxy that 1973 maps HTTP to CoAP. 1975 Either way, only the Request/Response model of CoAP is mapped to 1976 HTTP. The underlying model of confirmable or non-confirmable 1977 messages, etc., is invisible and MUST have no effect on a proxy 1978 function. 1980 8.1. CoAP-HTTP Mapping 1982 The mapping of CoAP to HTTP is a relatively straightforward 1983 conversion of the CoAP method or response code, content-type and 1984 options to the corresponding HTTP feature. The payload is carried in 1985 an equivalent way by both protocols. 1987 In a similar manner to CoAP-CoAP proxying, the CoAP-HTTP proxy MAY 1988 perform caching of HTTP responses. If no caching is performed, a 1989 CoAP GET request that specifies an entity-tag in an ETag Option 1990 SHOULD be mapped to a conditional HTTP request that includes the 1991 entity-tag in the "If-None-Match" request-header field. If the 1992 entity-tag matches the entity-tag of the representation, the HTTP 1993 server responds with an HTTP 304 (Not Modified) response which SHOULD 1994 be mapped to a CoAP 2.03 (Valid) response with the ETag Option 1995 reflecting the response's "ETag" response-header field. The mapping 1996 of max-age is straightforward. 1998 HTTP entity-tags consist of characters in a subset of the US-ASCII 1999 character set, which can be carried directly in a CoAP ETag Option. 2000 Weak entity-tags are not supported by this mapping. However, an 2001 entity-tag may not fit within the CoAP ETag Option. In this case, 2002 the proxy MAY map the entity-tag to a shorter unique byte sequence 2003 and keep state, or MAY silently ignore the "ETag" response-header 2004 when mapping an HTTP response to CoAP (so the CoAP client will never 2005 send a CoAP GET request with an ETag Option). 2007 Provisional responses (HTTP Status Codes 1xx), and responses 2008 indicating that further action needs to be taken (HTTP Status Codes 2009 3xx), SHOULD cause the proxy to complete the request, e.g., by 2010 following the redirects. If the proxy is unable to complete the 2011 request, it SHOULD respond with a CoAP 5.02 (Bad Gateway) error. 2013 HTTP responses are mapped to CoAP responses as follows: 2015 +-------------------------------+---------------------------+-------+ 2016 | HTTP Status Code | CoAP Response Code | Notes | 2017 +-------------------------------+---------------------------+-------+ 2018 | 100 Continue | | 2 | 2019 | 101 Switching Protocols | | 2 | 2020 | 200 OK | | 3 | 2021 | 201 Created | 2.01 Created | | 2022 | 202 Accepted | | 4 | 2023 | 203 Non-Authoritative | | 4 | 2024 | Information | | | 2025 | 204 No Content | | 6 | 2026 | 205 Reset Content | | 4 | 2027 | 206 Partial Content | | 2 | 2028 | 300 Multiple Choices | | 2 | 2029 | 301 Moved Permanently | | 2 | 2030 | 302 Found | | 2 | 2031 | 303 See Other | | 2 | 2032 | 304 Not Modified | 2.03 Valid | 7 | 2033 | 305 Use Proxy | | 2 | 2034 | 306 (Unused) | 5.02 Bad Gateway | 1 | 2035 | 307 Temporary Redirect | | 2 | 2036 | 400 Bad Request | 4.00 Bad Request | | 2037 | 401 Unauthorized | 4.01 Unauthorized | 5 | 2038 | 402 Payment Required | 4.00 Bad Request | 1 | 2039 | 403 Forbidden | 4.03 Forbidden | | 2040 | 404 Not Found | 4.04 Not Found | | 2041 | 405 Method Not Allowed | 4.05 Method Not Allowed | 8 | 2042 | 406 Not Acceptable | 4.00 Bad Request | 1 | 2043 | 407 Proxy Authentication | 4.00 Bad Request | 1 | 2044 | Required | | | 2045 | 408 Request Timeout | 4.00 Bad Request | 1 | 2046 | 409 Conflict | 4.00 Bad Request | 1 | 2047 | 410 Gone | 4.00 Bad Request | 1 | 2048 | 411 Length Required | 4.00 Bad Request | 1 | 2049 | 412 Precondition Failed | 4.00 Bad Request | 1 | 2050 | 413 Request Entity Too Large | 4.13 Request Entity Too | | 2051 | | Large | | 2052 | 414 URI Too Long | 4.00 Bad Request | 1 | 2053 | 415 Unsupported Media Type | 4.15 Unsupported Media | | 2054 | | Type | | 2055 | 416 Requested Range Not | 4.00 Bad Request | 1 | 2056 | Satisfiable | | | 2057 | 417 Expectation Failed | 4.00 Bad Request | 1 | 2058 | 500 Internal Server Error | 5.00 Internal Server | | 2059 | | Error | | 2060 | 501 Not Implemented | 5.01 Not Implemented | | 2061 | 502 Bad Gateway | 5.02 Bad Gateway | | 2062 | 503 Service Unavailable | 5.03 Service Unavailable | 9 | 2063 | 504 Gateway Timeout | 5.04 Gateway Timeout | | 2064 | 505 HTTP Version Not | | 2 | 2065 | Supported | | | 2066 +-------------------------------+---------------------------+-------+ 2068 Table 3: CoAP-HTTP Mapping 2070 Notes: 2072 1. There is no equivalent CoAP response. 2074 2. The proxy should perform the action implied by the response code 2075 (e.g., by following redirects); i.e. this response is never 2076 forwarded to the CoAP client. If the proxy is unable or 2077 unwilling to perform this function, the CoAP response code 5.02 2078 (Bad Gateway) can be returned. 2080 3. The CoAP response code depends on the request method. For a GET 2081 request, the response code SHOULD be 2.05 (Content). For a POST, 2082 PUT or DELETE request, the mapping is only partial: response 2083 entities are ignored, and the response code depends on the method 2084 as defined in Section 5.8. 2086 4. (The mapping for these rarely-used status codes is not defined in 2087 this specification.) 2089 5. The HTTP "WWW-Authenticate" response-header field has no 2090 equivalent option in CoAP and is either processed by the proxy by 2091 performing an additional request or silently dropped. 2093 6. The CoAP response code depends on the request method. For a POST 2094 or PUT request, the response code SHOULD be 2.04 (Changed); for a 2095 DELETE request, 2.02 (Deleted). 2097 7. Since a CoAP request with ETag Option is mapped to a conditional 2098 HTTP GET request with a "If-None-Match" request-header field, any 2099 HTTP 304 (Not Modified) response will confirm that the ETag is 2100 valid. Except for the max-age directive of the Cache-Control 2101 header field, any additional headers in the HTTP Not Modified 2102 response are not carried through to the CoAP client, though. 2104 8. The HTTP "Accept" response-header field has no equivalent option 2105 in CoAP and is silently dropped. 2107 9. The HTTP "Retry-After" response-header field has no equivalent 2108 option in CoAP, although it may be used to find a value for the 2109 Max-Age Option. 2111 8.2. HTTP-CoAP Mapping 2113 The mapping of HTTP to CoAP requires checking for methods, response 2114 codes and options that are not supported by CoAP. A proxy SHOULD 2115 attempt to map options, response codes and content-types to a 2116 suitable alternative if possible. Otherwise the unsupported feature 2117 SHOULD be silently dropped if possible, or an appropriate error code 2118 generated otherwise. 2120 Mapping MAY include performing payload conversion (e.g., from EXI to 2121 XML), the definition of which is out of this document's scope. 2123 Only those Conditional HTTP requests can be mapped to CoAP requests 2124 that have method GET and include a "If-None-Match" request-header 2125 field. The "If-Match", "If-Modified-Since" and "If-Unmodified-Since" 2126 request-header fields are not supported on the CoAP side, but could 2127 be implemented locally by a caching proxy. A HTTP-CoAP proxy SHOULD 2128 map ETags generated by a CoAP server to HTTP-friendly ETags by using 2129 Base64 [RFC4648]. 2131 A proxy SHOULD respond with a HTTP 502 (Bad Gateway) error to HTTP 2132 requests which can not be successfully mapped to CoAP. 2134 A proxy SHOULD employ a cache to limit traffic on the constrained 2135 network. 2137 CoAP responses are mapped to HTTP responses as follows: 2139 +-----------------------------+-----------------------------+-------+ 2140 | CoAP Response Code | HTTP Status Code | Notes | 2141 +-----------------------------+-----------------------------+-------+ 2142 | 2.01 Created | 201 Created | | 2143 | 2.02 Deleted | 204 No Content | | 2144 | 2.03 Valid | 304 Not Modified | 1 | 2145 | 2.04 Changed | 204 No Content | | 2146 | 2.05 Content | 200 OK | | 2147 | 4.00 Bad Request | 400 Bad Request | | 2148 | 4.01 Unauthorized | 400 Bad Request | 2 | 2149 | 4.02 Bad Option | 400 Bad Request | | 2150 | 4.03 Forbidden | 403 Forbidden | | 2151 | 4.04 Not Found | 404 Not Found | | 2152 | 4.05 Method Not Allowed | 405 Method Not Allowed | 3 | 2153 | 4.13 Request Entity Too | 413 Request Entity Too | | 2154 | Large | Large | | 2155 | 4.15 Unsupported Media Type | 415 Unsupported Media Type | | 2156 | 5.00 Internal Server Error | 500 Internal Server Error | | 2157 | 5.01 Not Implemented | 501 Not Implemented | | 2158 | 5.02 Bad Gateway | 502 Bad Gateway | | 2159 | 5.03 Service Unavailable | 503 Service Unavailable | 4 | 2160 | 5.04 Gateway Timeout | 504 Gateway Timeout | | 2161 | 5.05 Proxying Not Supported | 502 Bad Gateway | | 2162 +-----------------------------+-----------------------------+-------+ 2164 Table 4: HTTP-CoAP Mapping 2166 Notes: 2168 1. A CoAP 2.03 (Valid) response only (1) confirms that the request 2169 ETag is valid and (2) provides a new Max-Age value. HTTP 304 2170 (Not Modified) also updates some header fields of a stored 2171 response. A non-caching proxy may not have enough information to 2172 fill in the required values in the HTTP 304 (Not Modified) 2173 response, so it may not be advisable to provoke the 2.03 (Valid) 2174 response by forwarding an ETag. A caching proxy will fill the 2175 information out of the cache. 2177 2. There is no equivalent HTTP status code. 2179 3. CoAP does not provide enough information to compute a value for 2180 the required "Allow" response-header field. If this violation of 2181 [RFC2616] cannot be tolerated, the proxy should instead send a 2182 4.00 (Bad Request) response. 2184 4. The value of the "Retry-After" response-header field is the value 2185 of the Max-Age Option. 2187 9. Protocol Constants 2189 This section defines the relevant protocol constants defined in this 2190 document: 2192 RESPONSE_TIMEOUT 2 seconds 2194 MAX_RETRANSMIT 4 2196 10. Security Considerations 2198 This section describes mechanisms that can be used to secure CoAP and 2199 analyzes the possible threats to the protocol and its limitations. 2200 Security bootstrapping (authenticating nodes and setting up keys) in 2201 constrained environments is considered in 2202 [I-D.oflynn-core-bootstrapping]. 2204 During the bootstrap and enrollment phases, a CoAP device is provided 2205 with the security information that it needs, including keying 2206 materials. How this is done is out of scope for this specification 2207 but a couple of ways of doing this are described in 2208 [I-D.oflynn-core-bootstrapping]. At the end of the enrollment and 2209 bootstrap, the device will be in one of four security modes with the 2210 following information for the given mode: 2212 NoSec: There is no protocol level security. 2214 SharedKey: There is one shared key between all the nodes that this 2215 CoAP node needs to communicate with. 2217 MultiKey: There is a list of shared keys and each key includes a 2218 list of which nodes it can be used to communicate with. At the 2219 extreme there may be one key for each node this CoAP node needs to 2220 communicate with. 2222 Certificate: The device has an asymmetric key pair with a X.509 2223 [RFC5280] certificate that binds it to its Authority Name and is 2224 signed by a some common trust root. The device also has a list of 2225 root trust anchors that can be used for validating a certificate. 2226 There may be an optional shared key that all the nodes that 2227 communicate have access to. 2229 The Authority Name in the certificate is the name that would be used 2230 in the Authority part of a CoAP URI. It is worth noting that this 2231 would typically not be either an IP address or DNS name but would 2232 instead be a long term unique identifier for the device such as the 2233 EUI-64 [EUI64]. The discovery process used in the system would build 2234 up the mapping between IP addresses of the given devices and the 2235 Authority Name for each device. Some devices could have more than 2236 one Authority and would need more than a single certificate. 2238 In the "NoSec" mode, the system simply sends the packets over normal 2239 UDP over IP. The system is secured only by keeping attackers from 2240 being able to send or receive packets from the network with the CoAP 2241 nodes; see Section 10.3.4 for an additional complication with this 2242 approach. The other three security modes can be achieved with IPsec 2243 or DTLS. The result is a security association that can be used to 2244 authenticate (within the limits of the security model) and, based on 2245 this authentication, authorize the communication partner. CoAP 2246 itself does not provide protocol primitives for authentication or 2247 authorization; where this is required, it can either be provided by 2248 communication security (i.e., IPsec or DTLS) or by object security 2249 (within the payload). Devices that require authorization for certain 2250 operations are expected to require one of these two forms of 2251 security. Necessarily, where an intermediary is involved, 2252 communication security only works when that intermediary is part of 2253 the trust relationships; CoAP does not provide a way to forward 2254 different levels of authorization that clients may have with an 2255 intermediary to further intermediaries or origin servers -- it 2256 therefore may be required to perform all authorization at the first 2257 intermediary. 2259 10.1. Securing CoAP with IPsec 2261 One mechanism to secure CoAP in constrained environments is the IPsec 2262 Encapsulating Security Payload (ESP) [RFC4303]. Using IPsec ESP with 2263 the appropriate configuration, it is possible for many constrained 2264 devices to support encryption with built-in link-layer encryption 2265 hardware. For example, some IEEE 802.15.4 radio chips are compatible 2266 with AES-CBC (with 128-bit keys) [RFC3602] as defined for use with 2267 IPsec in [RFC4835]. Alternatively, particularly on more common IEEE 2268 802.15.4 hardware that supports AES encryption but not decryption, 2269 and to avoid the need for padding, nodes could directly use the more 2270 widely supported AES-CCM as defined for use with IPsec in [RFC4309], 2271 if the security considerations in section 9 of that specification can 2272 be fulfilled. Necessarily for AES-CCM, but much preferably also for 2273 AES-CBC, static keying should be avoided and the initial keying 2274 material be derived into transient session keys, e.g. using a low- 2275 overhead mode of IKEv2 [RFC5996]; such a protocol for managing keys 2276 and sequence numbers is also the only way to achieve anti-replay 2277 capabilities. However, no recommendation can be made at this point 2278 on how to manage group keys (i.e., for multicast) in a constrained 2279 environment. Once any initial setup is completed, IPsec ESP adds a 2280 limited per-packet overhead of approximately 10 bytes, not including 2281 initialization vectors, integrity check values and padding required 2282 by the cipher suite. 2284 When using IPsec to secure CoAP, both authentication and 2285 confidentiality SHOULD be applied as recommended in [RFC4303]. The 2286 use of IPsec between CoAP end-points is transparent to the 2287 application layer and does not require special consideration for a 2288 CoAP implementation. 2290 IPsec may not be appropriate for all environments. For example, 2291 IPsec support is not available for many embedded IP stacks and even 2292 in full PC operating systems or on back-end web servers, application 2293 developers may not have sufficient access to configure or enable 2294 IPsec or to add a security gateway to the infrastructure. Problems 2295 with firewalls and NATs may furthermore limit the use of IPsec. 2297 10.2. Securing CoAP with DTLS 2299 Just as HTTP may be secured using Transport Layer Security (TLS) over 2300 TCP, CoAP may be secured using Datagram TLS (DTLS) [RFC4347] over 2301 UDP. This section gives a quick overview of how to secure CoAP with 2302 DTLS, along with the minimal configurations appropriate for 2303 constrained environments. DTLS is in practice TLS with added 2304 features to deal with the unreliable nature of the UDP transport. 2306 In some constrained nodes (limited flash and/or RAM) and networks 2307 (limited bandwidth or high scalability requirements), and depending 2308 on the specific cipher suites in use, DTLS may not be applicable. 2309 Some of DTLS' cipher suites can add significant implementation 2310 complexity as well as some initial handshake overhead needed when 2311 setting up the security association. Once the initial handshake is 2312 completed, DTLS adds a limited per-datagram overhead of approximately 2313 13 bytes, not including any initialization vectors (which are 2314 generally implicitly derived with DTLS), integrity check values 2315 (e.g., 8 bytes with the proposed TLS_PSK_WITH_AES_128_CCM_8 2316 [I-D.mcgrew-tls-aes-ccm]) and padding required by the cipher suite. 2317 Whether and which mode of using DTLS is applicable for a CoAP-based 2318 application should be carefully weighed considering the specific 2319 cipher suites that may be applicable, and whether the session 2320 maintenance makes it compatible with application flows and sufficient 2321 resources are available on the constrained nodes and for the added 2322 network overhead. DTLS is not applicable to group keying (multicast 2323 communication); however, it may be a component in a future group key 2324 management protocol. 2326 Devices SHOULD support the Server Name Indication (SNI) to indicate 2327 their Authority Name in the SNI HostName field as defined in Section 2328 3 of [RFC6066]. This is needed so that when a host that acts as a 2329 virtual server for multiple Authorities receives a new DTLS 2330 connection, it knows which keys to use for the DTLS session. 2332 DTLS connections with certificates are set up using mutual 2333 authentication so they can remain up and be reused for future message 2334 exchanges in either direction. Devices can close a DTLS connection 2335 when they need to recover resources but in general they should keep 2336 the connection up for as long as possible. Closing the DTLS 2337 connection after every CoAP message exchange is very inefficient. 2339 10.2.1. SharedKey and MultiKey Modes 2341 When forming a connection to a new node, the system selects an 2342 appropriate key based on which nodes it is trying to reach then forms 2343 a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. 2344 Implementations SHOULD support the mandatory to implement cipher 2345 suite TLS_PSK_WITH_AES_128_CBC_SHA as specified in [RFC4279]; once 2346 TLS_PSK_WITH_AES_128_CCM_8 as specified in [I-D.mcgrew-tls-aes-ccm] 2347 (or related cipher suites specified in [I-D.mcgrew-tls-aes-ccm-ecc]) 2348 in conjunction with [I-D.ietf-tls-rfc4347-bis] becomes available, 2349 this may be easier to implement on certain contemporary chipsets. 2351 The security considerations of [RFC4279] (Section 7) apply. In 2352 particular, applications should carefully weigh whether they need 2353 Perfect Forward Secrecy (PFS) or not and select an appropriate cipher 2354 suite (7.1). The entropy of the PSK must be sufficient to mitigate 2355 against brute-force and (where the PSK is not chosen randomly but by 2356 a human) dictionary attacks (7.2). The cleartext communication of 2357 client identities may leak data or compromise privacy (7.3). 2359 10.2.2. Certificate Mode 2361 As with IPsec, DTLS should be configured with a cipher suite 2362 compatible with any possible hardware engine on the node, for example 2363 AES-CBC in the case of IEEE 802.15.4. Implementations SHOULD support 2364 the mandatory to implement cipher suite TLS_RSA_WITH_AES_128_CBC_SHA 2365 as specified in [RFC5246]. 2367 When a new connection is formed, the certificate from the remote 2368 device needs to be verified. If the CoAP node has a source of 2369 absolute time, then the node SHOULD check the validity dates are of 2370 the certificate are within range. The certificate MUST also be 2371 signed by an appropriate chain of trust. If the certificate contains 2372 a SubjectAltName, then the Authority Name MUST match at least one of 2373 the authority names of any CoAP URI found in a URI type fields in the 2374 SubjectAltName set. If there is no SubjectAltName in the 2375 certificate, then the Authoritative Name must match the CN found in 2376 the certificate using the matching rules defined in [RFC2818] with 2377 the exception that certificates with wildcards are not allowed. 2379 If the system has a shared key in addition to the certificate, then a 2380 cipher suite that includes the shared key such as 2381 TLS_RSA_PSK_WITH_AES_128_CBC_SHA SHOULD be used. 2383 10.3. Threat analysis and protocol limitations 2385 This section is meant to inform protocol and application developers 2386 about the security limitations of CoAP as described in this document. 2387 As CoAP realizes a subset of the features in HTTP/1.1, the security 2388 considerations in Section 15 of [RFC2616] are also pertinent to CoAP. 2389 This section concentrates on describing limitations specific to CoAP. 2391 10.3.1. Protocol Parsing, Processing URIs 2393 A network-facing application can exhibit vulnerabilities in its 2394 processing logic for incoming packets. Complex parsers are well- 2395 known as a likely source of such vulnerabilities, such as the ability 2396 to remotely crash a node, or even remotely execute arbitrary code on 2397 it. CoAP attempts to narrow the opportunities for introducing such 2398 vulnerabilities by reducing parser complexity, by giving the entire 2399 range of encodable values a meaning where possible, and by 2400 aggressively reducing complexity that is often caused by unnecessary 2401 choice between multiple representations that mean the same thing. 2402 Much of the URI processing has been moved to the clients, further 2403 reducing the opportunities for introducing vulnerabilities into the 2404 servers. Even so, the URI processing code in CoAP implementations is 2405 likely to be a large source of remaining vulnerabilities and should 2406 be implemented with special care. The most complex parser remaining 2407 could be the one for the link-format, although this also has been 2408 designed with a goal of reduced implementation complexity 2409 [I-D.ietf-core-link-format]. (See also section 15.2 of [RFC2616].) 2411 10.3.2. Proxying and Caching 2413 As mentioned in 15.2 of [RFC2616], which see, proxies are by their 2414 very nature men-in-the-middle, breaking any IPsec or DTLS protection 2415 that a direct CoAP message exchange might have. They are therefore 2416 interesting targets for breaking confidentiality or integrity of CoAP 2417 message exchanges. As noted in [RFC2616], they are also interesting 2418 targets for breaking availability. 2420 The threat to confidentiality and integrity of request/response data 2421 is amplified where proxies also cache. Note that CoAP does not 2422 define any of the cache-suppressing Cache-Control options that 2423 HTTP/1.1 provides to better protect sensitive data. 2425 Finally, a proxy that fans out Separate Responses (as opposed to 2426 Piggy-backed Responses) to multiple original requesters may provide 2427 additional amplification (see below). 2429 10.3.3. Risk of amplification 2431 CoAP servers generally reply to a request packet with a response 2432 packet. This response packet may be significantly larger than the 2433 request packet. An attacker might use CoAP nodes to turn a small 2434 attack packet into a larger attack packet, an approach known as 2435 amplification. There is therefore a danger that CoAP nodes could 2436 become implicated in denial of service (DoS) attacks by using the 2437 amplifying properties of the protocol: An attacker that is attempting 2438 to overload a victim but is limited in the amount of traffic it can 2439 generate, can use amplification to generate a larger amount of 2440 traffic. 2442 This is particularly a problem in nodes that enable NoSec access and 2443 that are accessible from an attacker and can access potential victims 2444 (e.g. on the general Internet), as the UDP protocol provides no way 2445 to verify the source address given in the request packet. An 2446 attacker need only place the IP address of the victim in the source 2447 address of a suitable request packet to generate a larger packet 2448 directed at the victim. 2450 As a mitigating factor, many constrained network will only be able to 2451 generate a small amount of traffic, which may make CoAP nodes less 2452 attractive for this attack. However, the limited capacity of the 2453 constrained network makes the network itself a likely victim of an 2454 amplification attack. 2456 A CoAP server can reduce the amount of amplification it provides to 2457 an attacker by using slicing/blocking modes of CoAP 2458 [I-D.ietf-core-block] and offering large resource representations 2459 only in relatively small slices. E.g., for a 1000 byte resource, a 2460 10-byte request might result in an 80-byte response (with a 64-byte 2461 block) instead of a 1016-byte response, considerably reducing the 2462 amplification provided. 2464 CoAP also supports the use of multicast IP addresses in requests, an 2465 important requirement for M2M. Multicast CoAP requests may be the 2466 source of accidental or deliberate denial of service attacks, 2467 especially over constrained networks. This specification attempts to 2468 reduce the amplification effects of multicast requests by limiting 2469 when a response is returned. To limit the possibility of malicious 2470 use, CoAP servers SHOULD NOT accept multicast requests that can not 2471 be authenticated. If possible a CoAP server SHOULD limit the support 2472 for multicast requests to specific resources where the feature is 2473 required. 2475 On some general purpose operating systems providing a Posix-style 2476 API, it is not straightforward to find out whether a packet received 2477 was addressed to a multicast address. While many implementations 2478 will know whether they have joined a multicast group, this creates a 2479 problem for packets addressed to multicast addresses of the form 2480 FF0x::1, which are received by every IPv6 node. Implementations 2481 SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 2482 available, to make this determination. 2484 10.3.4. Cross-Protocol Attacks 2486 The ability to incite a CoAP end-point to send packets to a fake 2487 source address can be used not only for amplification, but also for 2488 cross-protocol attacks: 2490 o the attacker sends a message to a CoAP end point with a fake 2491 source address, 2493 o the CoAP end point replies with a message to the given source 2494 address, 2496 o the victim at the given source address receives a UDP packet that 2497 it interprets according to the rules of a different protocol. 2499 This may be used to circumvent firewall rules that prevent direct 2500 communication from the attacker to the victim, but happen to allow 2501 communication from the CoAP end-point (which may also host a valid 2502 role in the other protocol) to the victim. 2504 Also, CoAP end-points may be the victim of a cross-protocol attack 2505 generated through an endpoint of another UDP-based protocol such as 2506 DNS. In both cases, attacks are possible if the security properties 2507 of the end-points rely on checking IP addresses (and firewalling off 2508 direct attacks sent from outside using fake IP addresses). In 2509 general, because of their lack of context, UDP-based protocols are 2510 relatively easy targets for cross-protocol attacks. 2512 Finally, CoAP URIs transported by other means could be used to incite 2513 clients to send messages to end-points of other protocols. 2515 One mitigation against cross-protocol attacks is strict checking of 2516 the syntax of packets received, combined with sufficient difference 2517 in syntax. As an example, it might help if it were difficult to 2518 incite a DNS server to send a DNS response that would pass the checks 2519 of a CoAP endpoint. Unfortunately, the first two bytes of a DNS 2520 reply are an ID that can be chosen by the attacker, which map into 2521 the interesting part of the CoAP header, and the next two bytes are 2522 then interpreted as CoAP's Message ID (i.e., any value is 2523 acceptable). The DNS count words may be interpreted as multiple 2524 instances of a (non-existent, but elective) CoAP option 0. The 2525 echoed query finally may be manufactured by the attacker to achieve a 2526 desired effect on the CoAP endpoint; the response added by the server 2527 (if any) might then just be interpreted as added payload. 2529 1 1 1 1 1 1 2530 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2531 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2532 | ID | T, OC, code 2533 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2534 |QR| Opcode |AA|TC|RD|RA| Z | RCODE | message id 2535 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2536 | QDCOUNT | (options 0) 2537 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2538 | ANCOUNT | (options 0) 2539 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2540 | NSCOUNT | (options 0) 2541 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2542 | ARCOUNT | (options 0) 2543 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2545 Figure 10: DNS Header vs. CoAP Message 2547 In general, for any pair of protocols, one of the protocols can very 2548 well have been designed in a way that enables an attacker to cause 2549 the generation of replies that look like messages of the other 2550 protocol. It is often much harder to ensure or prove the absence of 2551 viable attacks than to generate examples that may not yet completely 2552 enable an attack but might be further developed by more creative 2553 minds. Cross-protocol attacks can therefore only be completely 2554 mitigated if end-points don't authorize actions desired by an 2555 attacker just based on trusting the source IP address of a packet. 2556 Conversely, a NoSec environment that completely relies on a firewall 2557 for CoAP security not only needs to firewall off the CoAP end-points 2558 but also all other end-points that might be incited to send UDP 2559 messages to CoAP end-points using some other UDP-based protocol. 2561 In addition to the considerations above, the security considerations 2562 for DTLS with respect to cross-protocol attacks apply. E.g., if the 2563 same DTLS security association ("connection") is used to carry data 2564 of multiple protocols, DTLS no longer provides protection against 2565 cross-protocol attacks between these protocols. 2567 11. IANA Considerations 2568 11.1. CoAP Code Registry 2570 This document defines a registry for the values of the Code field in 2571 the CoAP header. The name of the registry is "CoAP Codes". 2573 All values are assigned by sub-registries according to the following 2574 ranges: 2576 0 Indicates an empty message (see Section 4.3). 2578 1-31 Indicates a request. Values in this range are assigned by 2579 the "CoAP Method Codes" sub-registry (see Section 11.1.1). 2581 32-63 Reserved 2583 64-191 Indicates a response. Values in this range are assigned by 2584 the "CoAP Response Codes" sub-registry (see 2585 Section 11.1.2). 2587 192-255 Reserved 2589 11.1.1. Method Codes 2591 The name of the sub-registry is "CoAP Method Codes". 2593 Each entry in the sub-registry must include the Method Code in the 2594 range 1-31, the name of the method, and a reference to the method's 2595 documentation. 2597 Initial entries in this sub-registry are as follows: 2599 +------+--------+-----------+ 2600 | Code | Name | Reference | 2601 +------+--------+-----------+ 2602 | 1 | GET | [RFCXXXX] | 2603 | 2 | POST | [RFCXXXX] | 2604 | 3 | PUT | [RFCXXXX] | 2605 | 4 | DELETE | [RFCXXXX] | 2606 +------+--------+-----------+ 2608 Table 5: CoAP Method Codes 2610 All other Method Codes are Unassigned. 2612 The IANA policy for future additions to this registry is "IETF 2613 Review" as described in [RFC5226]. 2615 The documentation of a method code should specify the semantics of a 2616 request with that code, including the following properties: 2618 o The response codes the method returns in the success case. 2620 o Whether the method is idempotent, safe, or both. 2622 o Whether the request causes a cache to mark responses stored for 2623 the request URI as stale. 2625 11.1.2. Response Codes 2627 The name of the sub-registry is "CoAP Response Codes". 2629 Each entry in the sub-registry must include the Response Code in the 2630 range 64-191, a description of the Response Code, and a reference to 2631 the Response Code's documentation. 2633 Initial entries in this sub-registry are as follows: 2635 +------+-------------------------------+-----------+ 2636 | Code | Description | Reference | 2637 +------+-------------------------------+-----------+ 2638 | 65 | 2.01 Created | [RFCXXXX] | 2639 | 66 | 2.02 Deleted | [RFCXXXX] | 2640 | 67 | 2.03 Valid | [RFCXXXX] | 2641 | 68 | 2.04 Changed | [RFCXXXX] | 2642 | 69 | 2.05 Content | [RFCXXXX] | 2643 | 128 | 4.00 Bad Request | [RFCXXXX] | 2644 | 129 | 4.01 Unauthorized | [RFCXXXX] | 2645 | 130 | 4.02 Bad Option | [RFCXXXX] | 2646 | 131 | 4.03 Forbidden | [RFCXXXX] | 2647 | 132 | 4.04 Not Found | [RFCXXXX] | 2648 | 133 | 4.05 Method Not Allowed | [RFCXXXX] | 2649 | 141 | 4.13 Request Entity Too Large | [RFCXXXX] | 2650 | 143 | 4.15 Unsupported Media Type | [RFCXXXX] | 2651 | 160 | 5.00 Internal Server Error | [RFCXXXX] | 2652 | 161 | 5.01 Not Implemented | [RFCXXXX] | 2653 | 162 | 5.02 Bad Gateway | [RFCXXXX] | 2654 | 163 | 5.03 Service Unavailable | [RFCXXXX] | 2655 | 164 | 5.04 Gateway Timeout | [RFCXXXX] | 2656 | 165 | 5.05 Proxying Not Supported | [RFCXXXX] | 2657 +------+-------------------------------+-----------+ 2659 Table 6: CoAP Response Codes 2661 The Response Codes 96-127 are Reserved for future use. All other 2662 Response Codes are Unassigned. 2664 The IANA policy for future additions to this registry is "IETF 2665 Review" as described in [RFC5226]. 2667 The documentation of a response code should specify the semantics of 2668 a response with that code, including the following properties: 2670 o The methods the response code applies to. 2672 o Whether payload is required, optional or not allowed. 2674 o The semantics of the payload. For example, the payload of a 2.05 2675 (Content) response is a representation of the target resource; the 2676 payload in an error response is a human-readable diagnostic 2677 message. 2679 o The format of the payload. For example, the format in a 2.05 2680 (Content) response is indicated by the Content-Type option; the 2681 format of the payload in an error response is always Net-Unicode 2682 text. 2684 o Whether the response is cacheable according to the freshness 2685 model. 2687 o Whether the response is validatable according to the validation 2688 model. 2690 o Whether the response causes a cache to mark responses stored for 2691 the request URI as stale. 2693 11.2. Option Number Registry 2695 This document defines a registry for the option numbers used in CoAP 2696 options. The name of the registry is "CoAP Option Numbers". 2698 Each entry in the registry must include the Option Number, the name 2699 of the option and a reference to the option's documentation. 2701 Initial entries in this registry are as follows: 2703 +--------+----------------+-----------+ 2704 | Number | Name | Reference | 2705 +--------+----------------+-----------+ 2706 | 1 | Content-Type | [RFCXXXX] | 2707 | 2 | Max-Age | [RFCXXXX] | 2708 | 3 | Proxy-Uri | [RFCXXXX] | 2709 | 4 | ETag | [RFCXXXX] | 2710 | 5 | Uri-Host | [RFCXXXX] | 2711 | 6 | Location-Path | [RFCXXXX] | 2712 | 7 | Uri-Port | [RFCXXXX] | 2713 | 8 | Location-Query | [RFCXXXX] | 2714 | 9 | Uri-Path | [RFCXXXX] | 2715 | 11 | Token | [RFCXXXX] | 2716 | 15 | Uri-Query | [RFCXXXX] | 2717 +--------+----------------+-----------+ 2719 Table 7: CoAP Option Numbers 2721 The Option Number 0 is Reserved for future use. The Option Numbers 2722 14, 28, 42, ... are Reserved for "fenceposting" (see Section 3.2). 2723 All other Option Numbers are Unassigned. 2725 The IANA policy for future additions to this registry is "IETF 2726 Review" as described in [RFC5226]. 2728 The documentation of an option number should specify the semantics of 2729 an option with that number, including the following properties: 2731 o The meaning of the option in a request. 2733 o The meaning of the option in a response. 2735 o Whether the option is critical of elective, as determined by the 2736 option number. 2738 o The format and length of the option's value. 2740 o Whether the option must occur at most once or whether it can occur 2741 multiple times. 2743 o The default value, if any. 2745 11.3. Media Type Registry 2747 Media types are identified by a string, such as "application/xml" 2748 [RFC2046]. In order to minimize the overhead of using these media 2749 types to indicate the format of payloads, this document defines a 2750 registry for a subset of Internet media types to be used in CoAP and 2751 assigns each a numeric identifier. The name of the registry is "CoAP 2752 Media Types". 2754 Each entry in the registry must include the media type registered 2755 with IANA, the numeric identifier in the range 0-65535 to be used for 2756 that media type in CoAP, and a reference to a document describing 2757 what payload with that media types means semantically. 2759 Initial entries in this registry are as follows: 2761 +------------------------------+-----+-----------------------------+ 2762 | Media type | Id. | Reference | 2763 +------------------------------+-----+-----------------------------+ 2764 | text/plain; charset=utf-8 | 0 | | 2765 | text/xml; charset=utf-8 | 1 | | 2766 | text/csv; charset=utf-8 | 2 | | 2767 | text/html; charset=utf-8 | 3 | | 2768 | application/link-format | 40 | [I-D.ietf-core-link-format] | 2769 | application/xml | 41 | | 2770 | application/octet-stream | 42 | | 2771 | application/rdf+xml | 43 | | 2772 | application/soap+xml | 44 | | 2773 | application/atom+xml | 45 | | 2774 | application/xmpp+xml | 46 | | 2775 | application/exi | 47 | [EXIMIME] | 2776 | application/fastinfoset | 48 | | 2777 | application/soap+fastinfoset | 49 | | 2778 | application/json | 50 | | 2779 | application/x-obix-binary | 51 | [OBIX1.1] | 2780 +------------------------------+-----+-----------------------------+ 2782 Table 8: CoAP Media Types 2784 The identifiers between 201 and 255 inclusive are reserved for 2785 Private Use. The identifiers between 256 and 65535 inclusive are 2786 Reserved for future use. All other identifiers are Unassigned. 2788 Because the name space is so small, the IANA policy for future 2789 additions to this registry is "Expert Review" as described in 2790 [RFC5226]. 2792 In machine to machine applications, it is not expected that generic 2793 Internet media types such as text/plain, application/xml or 2794 application/octet-stream are useful for real applications. It is 2795 recommended that M2M applications making use of CoAP will request new 2796 Internet media types from IANA indicating semantic information about 2797 how to create or parse a payload. Correct examples from Table 8 2798 include application/link-format, application/atom+xml and 2799 application/x-obix-binary. For example, a Smart Energy application 2800 payload carried as XML would request a more specific type like 2801 application/se+xml or application/se+exi. 2803 11.4. URI Scheme Registration 2805 This document requests the registration of the Uniform Resource 2806 Identifier (URI) scheme "coap". The registration request complies 2807 with [RFC4395]. 2809 URI scheme name. 2810 coap 2812 Status. 2813 Permanent. 2815 URI scheme syntax. 2816 Defined in Section 6.1 of [RFCXXXX]. 2818 URI scheme semantics. 2819 The "coap" URI scheme provides a way to identify resources that 2820 are potentially accessible over the Constrained Application 2821 Protocol (CoAP). The resources can be located by contacting the 2822 governing CoAP server and operated on by sending CoAP requests to 2823 the server. This scheme can thus be compared to the "http" URI 2824 scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of 2825 operation. 2827 Encoding considerations. 2828 The scheme encoding conforms to the encoding rules established for 2829 URIs in [RFC3986], i.e. internationalized and reserved characters 2830 are expressed using UTF-8-based percent-encoding. 2832 Applications/protocols that use this URI scheme name. 2833 The scheme is used by CoAP end-points to access CoAP resources. 2835 Interoperability considerations. 2836 None. 2838 Security considerations. 2839 See Section 10.3.1 of [RFCXXXX]. 2841 Contact. 2842 IETF Chair 2844 Author/Change controller. 2845 IESG 2847 References. 2848 [RFCXXXX] 2850 11.5. Service Name and Port Number Registration 2852 One of the functions of CoAP is resource discovery: a CoAP client can 2853 ask a CoAP server about the resources offered by it (see 2854 Section 7.1). To enable resource discovery just based on the 2855 knowledge of an IP address, the CoAP port for resource discovery 2856 needs to be standardized. 2858 This document requests the assignment of the port number 5683 and the 2859 service name "coap", in accordance with [I-D.ietf-tsvwg-iana-ports]. 2861 Besides unicast, CoAP can be used with both multicast and anycast. 2863 Service Name. 2864 coap 2866 Transport Protocol. 2867 UDP 2869 Assignee. 2870 IESG 2872 Contact. 2873 IETF Chair 2875 Description. 2876 Constrained Application Protocol (CoAP) 2878 Reference. 2879 [RFCXXXX] 2881 Port Number. 2882 5683 2884 12. Acknowledgements 2886 Special thanks to Peter Bigot and Cullen Jennings for substantial 2887 contributions to the ideas and text in the document, along with 2888 countless detailed reviews and discussions. 2890 Thanks to Michael Stuber, Richard Kelsey, Guido Moritz, Peter Van Der 2891 Stok, Adriano Pezzuto, Lisa Dussealt, Alexey Melnikov, Gilbert Clark, 2892 Salvatore Loreto, Petri Mutka, Szymon Sasin, Robert Quattlebaum, 2893 Robert Cragie, Angelo Castellani, Tom Herbst, Ed Beroset, Gilman 2894 Tolle, Robby Simpson, Colin O'Flynn, Eric Rescorla, Matthieu Vial, 2895 Linyi Tian, Kerry Lynn, Dale Seed, Akbar Rahman and David Ryan for 2896 helpful comments and discussions that have shaped the document. 2898 Some of the text has been lifted from the working documents of the 2899 IETF httpbis working group. 2901 13. References 2903 13.1. Normative References 2905 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 2906 Extensions (MIME) Part Two: Media Types", RFC 2046, 2907 November 1996. 2909 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2910 Requirement Levels", BCP 14, RFC 2119, March 1997. 2912 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2913 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2914 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2916 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2918 [RFC3602] Frankel, S., Glenn, R., and S. Kelly, "The AES-CBC Cipher 2919 Algorithm and Its Use with IPsec", RFC 3602, 2920 September 2003. 2922 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2923 10646", STD 63, RFC 3629, November 2003. 2925 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2926 Resource Identifier (URI): Generic Syntax", STD 66, 2927 RFC 3986, January 2005. 2929 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 2930 for Transport Layer Security (TLS)", RFC 4279, 2931 December 2005. 2933 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 2934 RFC 4303, December 2005. 2936 [RFC4309] Housley, R., "Using Advanced Encryption Standard (AES) CCM 2937 Mode with IPsec Encapsulating Security Payload (ESP)", 2938 RFC 4309, December 2005. 2940 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2941 Security", RFC 4347, April 2006. 2943 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 2944 Registration Procedures for New URI Schemes", BCP 35, 2945 RFC 4395, February 2006. 2947 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2948 Encodings", RFC 4648, October 2006. 2950 [RFC4835] Manral, V., "Cryptographic Algorithm Implementation 2951 Requirements for Encapsulating Security Payload (ESP) and 2952 Authentication Header (AH)", RFC 4835, April 2007. 2954 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 2955 Interchange", RFC 5198, March 2008. 2957 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2958 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2959 May 2008. 2961 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2962 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2964 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2965 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2967 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2968 Housley, R., and W. Polk, "Internet X.509 Public Key 2969 Infrastructure Certificate and Certificate Revocation List 2970 (CRL) Profile", RFC 5280, May 2008. 2972 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 2973 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 2974 October 2008. 2976 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 2977 Uniform Resource Identifiers (URIs)", RFC 5785, 2978 April 2010. 2980 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 2981 Address Text Representation", RFC 5952, August 2010. 2983 [RFC5996] Kaufman, C., Hoffman, P., Nir, Y., and P. Eronen, 2984 "Internet Key Exchange Protocol Version 2 (IKEv2)", 2985 RFC 5996, September 2010. 2987 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 2988 Extension Definitions", RFC 6066, January 2011. 2990 13.2. Informative References 2992 [EUI64] "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) 2993 REGISTRATION AUTHORITY", April 2010, . 2996 [EXIMIME] "Efficient XML Interchange (EXI) Format 1.0", 2997 December 2009, . 3000 [I-D.eggert-core-congestion-control] 3001 Eggert, L., "Congestion Control for the Constrained 3002 Application Protocol (CoAP)", 3003 draft-eggert-core-congestion-control-01 (work in 3004 progress), January 2011. 3006 [I-D.ietf-core-block] 3007 Shelby, Z. and C. Bormann, "Blockwise transfers in CoAP", 3008 draft-ietf-core-block-01 (work in progress), January 2011. 3010 [I-D.ietf-core-link-format] 3011 Shelby, Z., "CoRE Link Format", 3012 draft-ietf-core-link-format-02 (work in progress), 3013 December 2010. 3015 [I-D.ietf-tls-rfc4347-bis] 3016 Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3017 Security version 1.2", draft-ietf-tls-rfc4347-bis-04 (work 3018 in progress), July 2010. 3020 [I-D.ietf-tsvwg-iana-ports] 3021 Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 3022 Cheshire, "Internet Assigned Numbers Authority (IANA) 3023 Procedures for the Management of the Service Name and 3024 Transport Protocol Port Number Registry", 3025 draft-ietf-tsvwg-iana-ports-10 (work in progress), 3026 February 2011. 3028 [I-D.mcgrew-tls-aes-ccm] 3029 McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for TLS", 3030 draft-mcgrew-tls-aes-ccm-01 (work in progress), 3031 March 2011. 3033 [I-D.mcgrew-tls-aes-ccm-ecc] 3034 McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 3035 CCM ECC Cipher Suites for TLS", 3036 draft-mcgrew-tls-aes-ccm-ecc-01 (work in progress), 3037 January 2011. 3039 [I-D.oflynn-core-bootstrapping] 3040 Sarikaya, B., Ohba, Y., Cao, Z., and R. Cragie, "Security 3041 Bootstrapping of Resource-Constrained Devices", 3042 draft-oflynn-core-bootstrapping-03 (work in progress), 3043 November 2010. 3045 [OBIX1.1] "OBIX Version 1.1", June 2010, . 3048 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 3049 with Session Description Protocol (SDP)", RFC 3264, 3050 June 2002. 3052 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 3053 "Advanced Sockets Application Program Interface (API) for 3054 IPv6", RFC 3542, May 2003. 3056 [RFC3920] Saint-Andre, P., Ed., "Extensible Messaging and Presence 3057 Protocol (XMPP): Core", RFC 3920, October 2004. 3059 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 3060 "Transmission of IPv6 Packets over IEEE 802.15.4 3061 Networks", RFC 4944, September 2007. 3063 Appendix A. Integer Option Value Format 3065 Options of type uint contain a non-negative integer that is 3066 represented in network byte order using a variable number of bytes, 3067 as shown in Figure 11. 3069 Length = 0 (implies value of 0) 3071 0 3072 0 1 2 3 4 5 6 7 3073 +-+-+-+-+-+-+-+-+ 3074 Length = 1 | 0-255 | 3075 +-+-+-+-+-+-+-+-+ 3077 0 1 3078 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 3079 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3080 Length = 2 | 0-65535 | 3081 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3083 Length = 3 is 24 bits, Length = 4 is 32 bits etc. 3085 Figure 11: Variable-length unsigned integer format 3087 Appendix B. Examples 3089 This section gives a number of short examples with message flows for 3090 GET requests. These examples demonstrate the basic operation, the 3091 operation in the presence of retransmissions, and multicast. 3093 Figure 12 shows a basic GET request causing a piggy-backed response: 3094 The client sends a Confirmable GET request for the resource 3095 coap://server/temperature to the server with a Message ID of 0x7d34. 3096 The request includes one Uri-Path Option (Delta 0 + 9 = 9, Length 11, 3097 Value "temperature"); the Token is left at its default value (empty). 3098 This request is a total of 16 bytes long. A 2.05 (Content) response 3099 is returned in the Acknowledgement message that acknowledges the 3100 Confirmable request, echoing both the Message ID 0x7d34 and the 3101 (implicitly empty) Token value. The response includes a Payload of 3102 "22.3 C" and is 10 bytes long. 3104 Client Server 3105 | | 3106 | | 3107 +----->| Header: GET (T=CON, Code=1, MID=0x7d34) 3108 | GET | Uri-Path: "temperature" 3109 | | 3110 | | 3111 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d34) 3112 | 2.05 | Payload: "22.3 C" 3113 | | 3115 0 1 2 3 3116 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 3117 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3118 | 1 | 0 | 1 | GET=1 | MID=0x7d34 | 3119 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3120 | 9 | 11 | "temperature" (11 B) ... 3121 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3123 0 1 2 3 3124 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 3125 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3126 | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | 3127 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3128 | "22.3 C" (6 B) ... 3129 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3131 Figure 12: Confirmable request; piggy-backed response 3133 Figure 13 shows a similar example, but with the inclusion of an 3134 explicit Token option (Delta 9 + 2 = 11, Length 1, Value 0x20) in the 3135 request and (Delta 11 + 0 = 11) in the response, increasing the sizes 3136 to 18 and 12 bytes, respectively. 3138 Client Server 3139 | | 3140 | | 3141 +----->| Header: GET (T=CON, Code=1, MID=0x7d35) 3142 | GET | Token: 0x20 3143 | | Uri-Path: "temperature" 3144 | | 3145 | | 3146 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d35) 3147 | 2.05 | Token: 0x20 3148 | | Payload: "22.3 C" 3149 | | 3151 0 1 2 3 3152 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 3153 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3154 | 1 | 0 | 2 | GET=1 | MID=0x7d34 | 3155 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3156 | 9 | 11 | "temperature" (11 B) ... 3157 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3158 | 2 | 1 | 0x20 | 3159 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3161 0 1 2 3 3162 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 3163 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3164 | 1 | 2 | 1 | 2.05=69 | MID=0x7d34 | 3165 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3166 | 11 | 1 | 0x20 | "22.3 C" (6 B) ... 3167 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3169 Figure 13: Confirmable request; piggy-backed response 3171 In Figure 14, the Confirmable GET request is lost. After 3172 RESPONSE_TIMEOUT seconds, the client retransmits the request, 3173 resulting in a piggy-backed response as in the previous example. 3175 Client Server 3176 | | 3177 | | 3178 +----X | Header: GET (T=CON, Code=1, MID=0x7d36) 3179 | GET | Token: 0x31 3180 | | Uri-Path: "temperature" 3181 TIMEOUT | 3182 | | 3183 +----->| Header: GET (T=CON, Code=1, MID=0x7d36) 3184 | GET | Token: 0x31 3185 | | Uri-Path: "temperature" 3186 | | 3187 | | 3188 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d36) 3189 | 2.05 | Token: 0x31 3190 | | Payload: "22.3 C" 3191 | | 3193 Figure 14: Confirmable request (retransmitted); piggy-backed response 3195 In Figure 15, the first Acknowledgement message from the server to 3196 the client is lost. After RESPONSE_TIMEOUT seconds, the client 3197 retransmits the request. 3199 Client Server 3200 | | 3201 | | 3202 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 3203 | GET | Token: 0x42 3204 | | Uri-Path: "temperature" 3205 | | 3206 | | 3207 | X----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 3208 | 2.05 | Token: 0x42 3209 | | Payload: "22.3 C" 3210 TIMEOUT | 3211 | | 3212 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 3213 | GET | Token: 0x42 3214 | | Uri-Path: "temperature" 3215 | | 3216 | | 3217 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 3218 | 2.05 | Token: 0x42 3219 | | Payload: "22.3 C" 3220 | | 3222 Figure 15: Confirmable request; piggy-backed response (retransmitted) 3223 In Figure 16, the server acknowledges the Confirmable request and 3224 sends a 2.05 (Content) response separately in a Confirmable message. 3225 Note that the Acknowledgement message and the Confirmable response do 3226 not necessarily arrive in the same order as they were sent. The 3227 client acknowledges the Confirmable response. 3229 Client Server 3230 | | 3231 | | 3232 +----->| Header: GET (T=CON, Code=1, MID=0x7d38) 3233 | GET | Token: 0x53 3234 | | Uri-Path: "temperature" 3235 | | 3236 | | 3237 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d38) 3238 | | 3239 | | 3240 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7b) 3241 | 2.05 | Token: 0x53 3242 | | Payload: "22.3 C" 3243 | | 3244 | | 3245 +- - ->| Header: (T=ACK, Code=0, MID=0xad7b) 3246 | | 3248 Figure 16: Confirmable request; separate response 3250 Figure 17 shows an example where the client loses its state (e.g., 3251 crashes and is rebooted) right after sending a Confirmable request, 3252 so the separate response arriving some time later comes unexpected. 3253 In this case, the client rejects the Confirmable response with a 3254 Reset message. Note that the unexpected ACK is silently ignored. 3256 Client Server 3257 | | 3258 | | 3259 +----->| Header: GET (T=CON, Code=1, MID=0x7d39) 3260 | GET | Token: 0x64 3261 | | Uri-Path: "temperature" 3262 CRASH | 3263 | | 3264 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d39) 3265 | | 3266 | | 3267 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7c) 3268 | 2.05 | Token: 0x64 3269 | | Payload: "22.3 C" 3270 | | 3271 | | 3272 +- - ->| Header: (T=RST, Code=0, MID=0xad7c) 3273 | | 3275 Figure 17: Confirmable request; separate response (unexpected) 3277 Figure 18 shows a basic GET request where the request and the 3278 response are non-confirmable, so both may be lost without notice. 3280 Client Server 3281 | | 3282 | | 3283 +----->| Header: GET (T=NON, Code=1, MID=0x7d40) 3284 | GET | Token: 0x75 3285 | | Uri-Path: "temperature" 3286 | | 3287 | | 3288 |<-----+ Header: 2.05 Content (T=NON, Code=69, MID=0xad7d) 3289 | 2.05 | Token: 0x75 3290 | | Payload: "22.3 C" 3291 | | 3293 Figure 18: Non-confirmable request; Non-confirmable response 3295 In Figure 19, the client sends a Non-confirmable GET request to a 3296 multicast address: all nodes in link-local scope. There are 3 3297 servers on the link: A, B and C. Servers A and B have a matching 3298 resource, therefore they send back a Non-confirmable 2.05 (Content) 3299 response. The response sent by B is lost. C does not have matching 3300 response, therefore it sends a Non-confirmable 4.04 (Not Found) 3301 response. 3303 Client ff02::1 A B C 3304 | | | | | 3305 | | | | | 3306 +------>| | | | Header: GET (T=NON, Code=1, MID=0x7d41) 3307 | GET | | | | Token: 0x86 3308 | | | | Uri-Path: "temperature" 3309 | | | | 3310 | | | | 3311 |<------------+ | | Header: 2.05 (T=NON, Code=69, MID=0x60b1) 3312 | 2.05 | | | Token: 0x86 3313 | | | | Payload: "22.3 C" 3314 | | | | 3315 | | | | 3316 | X------------+ | Header: 2.05 (T=NON, Code=69, MID=0x01a0) 3317 | 2.05 | | | Token: 0x86 3318 | | | | Payload: "20.9 C" 3319 | | | | 3320 | | | | 3321 |<------------------+ Header: 4.04 (T=NON, Code=132, MID=0x952a) 3322 | 4.04 | | | Token: 0x86 3323 | | | | 3325 Figure 19: Non-confirmable request (multicast); Non-confirmable 3326 response 3328 Appendix C. URI Examples 3330 The following examples demonstrate different sets of Uri options, and 3331 the result after constructing an URI from them. 3333 o coap://[2001:db8::2:1]/ 3335 Destination IP Address = [2001:db8::2:1] 3337 Destination UDP Port = [IANA_TBD_PORT] 3339 o coap://example.net/ 3341 Destination IP Address = [2001:db8::2:1] 3343 Destination UDP Port = [IANA_TBD_PORT] 3345 Uri-Host = "example.net" 3347 o coap://example.net/.well-known/core 3348 Destination IP Address = [2001:db8::2:1] 3350 Destination UDP Port = [IANA_TBD_PORT] 3352 Uri-Host = "example.net" 3354 Uri-Path = ".well-known" 3356 Uri-Path = "core" 3358 o coap:// 3359 xn--18j4d.example/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF 3361 Destination IP Address = [2001:db8::2:1] 3363 Destination UDP Port = [IANA_TBD_PORT] 3365 Uri-Host = "xn--18j4d.example" 3367 Uri-Path = the string composed of the Unicode characters U+3053 3368 U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as 3369 E38193E38293E381ABE381A1E381AF hexadecimal 3371 o coap://198.51.100.1:61616//%2F//?%2F%2F 3373 Destination IP Address = 198.51.100.1 3375 Destination UDP Port = 61616 3377 Uri-Path = "" 3379 Uri-Path = "/" 3381 Uri-Path = "" 3383 Uri-Path = "" 3385 Uri-Query = "%2F%2F" 3387 o coap://[2001:db8::2:1]/sensors/temp 3389 Destination IP Address = [::1] 3391 Destination UDP Port = 61616 3393 Uri-Host = "[2001:db8::2:1]" 3394 Uri-Port = [IANA_TBD_PORT] 3396 Uri-Path = "sensors" 3398 Uri-Path = "temp" 3400 Appendix D. Changelog 3402 Changed from ietf-04 to ietf-05: 3404 o Renamed Immediate into Piggy-backed and Deferred into Separate -- 3405 should finally end the confusion on what this is about. 3407 o GET requests now return a 2.05 (Content) response instead of 2.00 3408 (OK) response (#104). 3410 o Added text to allow 2.02 (Deleted) responses in reply to POST 3411 requests (#105). 3413 o Improved message deduplication rules (#106). 3415 o Section added on message size implementation considerations 3416 (#103). 3418 o Clarification made on human readable error payloads (#109). 3420 o Definition of CoAP methods improved (#108). 3422 o Max-Age removed from requests (#107). 3424 o Clarified uniqueness of tokens (#112). 3426 o Location-Query Option added (#113). 3428 o ETag length set to 1-8 bytes (#123). 3430 o Clarified relation between elective/critical and option numbers 3431 (#110). 3433 o Defined when to update Version header field (#111). 3435 o URI scheme registration improved (#102). 3437 o Added review guidelines for new CoAP codes and numbers. 3439 Changes from ietf-03 to ietf-04: 3441 o Major document reorganization (#51, #63, #71, #81). 3443 o Max-age length set to 0-4 bytes (#30). 3445 o Added variable unsigned integer definition (#31). 3447 o Clarification made on human readable error payloads (#50). 3449 o Definition of POST improved (#52). 3451 o Token length changed to 0-8 bytes (#53). 3453 o Section added on multiplexing CoAP, DTLS and STUN (#56). 3455 o Added cross-protocol attack considerations (#61). 3457 o Used new Immediate/Deferred response definitions (#73). 3459 o Improved request/response matching rules (#74). 3461 o Removed unnecessary media types and added recommendations for 3462 their use in M2M (#76). 3464 o Response codes changed to base 32 coding, new Y.XX naming (#77). 3466 o References updated as per AD review (#79). 3468 o IANA section completed (#80). 3470 o Proxy-Uri option added to diambiguate between proxy and non-proxy 3471 requests (#82). 3473 o Added text on critical options in cached states (#83). 3475 o HTTP mapping sections improved (#88). 3477 o Added text on reverse proxies (#72). 3479 o Some security text on multicast added (#54). 3481 o Trust model text added to introduction (#58, #60). 3483 o AES-CCM vs. AES-CCB text added (#55). 3485 o Text added about device capabilities (#59). 3487 o DTLS section improvements (#87). 3489 o Caching semantics aligned with RFC2616 (#78). 3491 o Uri-Path option split into multiple path segments. 3493 o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. 3495 Changes from ietf-02 to ietf-03: 3497 o Token Option and related use in asynchronous requests added (#25). 3499 o CoAP specific error codes added (#26). 3501 o Erroring out on unknown critical options changed to a MUST (#27). 3503 o Uri-Query option added. 3505 o Terminology and definitions of URIs improved. 3507 o Security section completed (#22). 3509 Changes from ietf-01 to ietf-02: 3511 o Sending an error on a critical option clarified (#18). 3513 o Clarification on behavior of PUT and idempotent operations (#19). 3515 o Use of Uri-Authority clarified along with server processing rules; 3516 Uri-Scheme option removed (#20, #23). 3518 o Resource discovery section removed to a separate CoRE Link Format 3519 draft (#21). 3521 o Initial security section outline added. 3523 Changes from ietf-00 to ietf-01: 3525 o New cleaner transaction message model and header (#5). 3527 o Removed subscription while being designed (#1). 3529 o Section 2 re-written (#3). 3531 o Text added about use of short URIs (#4). 3533 o Improved header option scheme (#5, #14). 3535 o Date option removed whiled being designed (#6). 3537 o New text for CoAP default port (#7). 3539 o Completed proxying section (#8). 3541 o Completed resource discovery section (#9). 3543 o Completed HTTP mapping section (#10). 3545 o Several new examples added (#11). 3547 o URI split into 3 options (#12). 3549 o MIME type defined for link-format (#13, #16). 3551 o New text on maximum message size (#15). 3553 o Location Option added. 3555 Changes from shelby-01 to ietf-00: 3557 o Removed the TCP binding section, left open for the future. 3559 o Fixed a bug in the example. 3561 o Marked current Sub/Notify as (Experimental) while under WG 3562 discussion. 3564 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 3565 CoAP-CoAP proxying to work). 3567 o Temporarily removed the Magic Byte header as TCP is no longer 3568 included as a binding. 3570 o Removed the Uri-code Option as different URI encoding schemes are 3571 being discussed. 3573 o Changed the rel= field to desc= for resource discovery. 3575 o Changed the maximum message size to 1024 bytes to allow for IP/UDP 3576 headers. 3578 o Made the URI slash optimization and method impotence MUSTs 3580 o Minor editing and bug fixing. 3582 Changes from shelby-00 to shelby-01: 3584 o Unified the message header and added a notify message type. 3586 o Renamed methods with HTTP names and removed the NOTIFY method. 3588 o Added a number of options field to the header. 3590 o Combines the Option Type and Length into an 8-bit field. 3592 o Added the magic byte header. 3594 o Added new ETag option. 3596 o Added new Date option. 3598 o Added new Subscription option. 3600 o Completed the HTTP Code - CoAP Code mapping table appendix. 3602 o Completed the Content-type Identifier appendix and tables. 3604 o Added more simplifications for URI support. 3606 o Initial subscription and discovery sections. 3608 o A Flag requirements simplified. 3610 Authors' Addresses 3612 Zach Shelby 3613 Sensinode 3614 Kidekuja 2 3615 Vuokatti 88600 3616 Finland 3618 Phone: +358407796297 3619 Email: zach@sensinode.com 3620 Klaus Hartke 3621 Universitaet Bremen TZI 3622 Postfach 330440 3623 Bremen D-28359 3624 Germany 3626 Phone: +49-421-218-63905 3627 Fax: +49-421-218-7000 3628 Email: hartke@tzi.org 3630 Carsten Bormann 3631 Universitaet Bremen TZI 3632 Postfach 330440 3633 Bremen D-28359 3634 Germany 3636 Phone: +49-421-218-63921 3637 Fax: +49-421-218-7000 3638 Email: cabo@tzi.org 3640 Brian Frank 3641 SkyFoundry 3642 Richmond, VA 3643 USA 3645 Phone: 3646 Email: brian@skyfoundry.com