idnits 2.17.1 draft-ietf-core-coap-11.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 4105 has weird spacing: '... Client ff02:...' == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (July 16, 2012) is 4292 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 436, but not defined == Missing Reference: '0x01a0' is mentioned on line 451, but not defined == Missing Reference: '0xbc90' is mentioned on line 492, but not defined == Missing Reference: '0xbc91' is mentioned on line 492, but not defined == Missing Reference: '0x7a10' is mentioned on line 516, but not defined == Missing Reference: '0x23bb' is mentioned on line 527, but not defined == Missing Reference: '0x7a11' is mentioned on line 540, but not defined == Missing Reference: '0x23bc' is mentioned on line 545, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 3643, but not defined == Missing Reference: 'TBD1' is mentioned on line 3654, but not defined == Missing Reference: 'TBD2' is mentioned on line 3659, but not defined == Outdated reference: A later version (-10) exists of draft-farrell-decade-ni-09 == Outdated reference: A later version (-11) exists of draft-ietf-tls-oob-pubkey-04 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** 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 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 5996 (Obsoleted by RFC 7296) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-03) exists of draft-allman-tcpm-rto-consider-01 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-20 == Outdated reference: A later version (-01) exists of draft-kivinen-ipsecme-ikev2-minimal-00 == Outdated reference: A later version (-04) exists of draft-mcgrew-tls-aes-ccm-03 == Outdated reference: A later version (-08) exists of draft-mcgrew-tls-aes-ccm-ecc-02 -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 4492 (Obsoleted by RFC 8422) -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- Obsolete informational reference (is this intentional?): RFC 5405 (Obsoleted by RFC 8085) Summary: 10 errors (**), 0 flaws (~~), 22 warnings (==), 6 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: January 17, 2013 C. Bormann 6 Universitaet Bremen TZI 7 B. Frank 8 SkyFoundry 9 July 16, 2012 11 Constrained Application Protocol (CoAP) 12 draft-ietf-core-coap-11 14 Abstract 16 The Constrained Application Protocol (CoAP) is a specialized web 17 transfer protocol for use with constrained nodes and constrained 18 (e.g., low-power, lossy) networks. The nodes often have 8-bit 19 microcontrollers with small amounts of ROM and RAM, while constrained 20 networks such as 6LoWPAN often have high packet error rates and a 21 typical throughput of 10s of kbit/s. The protocol is designed for 22 machine-to-machine (M2M) applications such as smart energy and 23 building automation. 25 CoAP provides a request/response interaction model between 26 application end-points, supports built-in discovery of services and 27 resources, and includes key concepts of the Web such as URIs and 28 Internet media types. CoAP easily interfaces with HTTP for 29 integration with the Web while meeting specialized requirements such 30 as multicast support, very low overhead and simplicity for 31 constrained environments. 33 Status of this Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on January 17, 2013. 50 Copyright Notice 52 Copyright (c) 2012 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 70 2. Constrained Application Protocol . . . . . . . . . . . . . . . 9 71 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 10 72 2.2. Request/Response Model . . . . . . . . . . . . . . . . . . 11 73 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . . 14 74 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . . 14 75 3. Message Format . . . . . . . . . . . . . . . . . . . . . . . . 14 76 3.1. Header Format . . . . . . . . . . . . . . . . . . . . . . 15 77 3.2. Option Format . . . . . . . . . . . . . . . . . . . . . . 16 78 3.3. Option Value Formats . . . . . . . . . . . . . . . . . . . 17 79 3.3.1. uint . . . . . . . . . . . . . . . . . . . . . . . . 17 80 3.3.2. string . . . . . . . . . . . . . . . . . . . . . . . 18 81 3.3.3. opaque . . . . . . . . . . . . . . . . . . . . . . . 18 82 3.3.4. empty . . . . . . . . . . . . . . . . . . . . . . . . 18 83 4. Message Transmission . . . . . . . . . . . . . . . . . . . . . 18 84 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . . 19 85 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 19 86 4.3. Messages Transmitted Without Reliability . . . . . . . . . 20 87 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 21 88 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 21 89 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . . 22 90 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . . 23 91 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 24 92 4.8.1. Changing The Parameters . . . . . . . . . . . . . . . 24 93 4.8.2. Time Values derived from Transmission Parameters . . 25 94 5. Request/Response Semantics . . . . . . . . . . . . . . . . . . 27 95 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . . 27 96 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 27 97 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 28 98 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 29 99 5.2.3. Non-Confirmable . . . . . . . . . . . . . . . . . . . 30 100 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 30 101 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 31 102 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 32 103 5.4.2. Length . . . . . . . . . . . . . . . . . . . . . . . 32 104 5.4.3. Default Values . . . . . . . . . . . . . . . . . . . 32 105 5.4.4. Repeatable Options . . . . . . . . . . . . . . . . . 33 106 5.4.5. Option Numbers . . . . . . . . . . . . . . . . . . . 33 107 5.5. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 33 108 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 33 109 5.5.2. Diagnostic Message . . . . . . . . . . . . . . . . . 33 110 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 34 111 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 35 112 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 35 113 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 35 114 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . . 37 115 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 37 116 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 37 117 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 37 118 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 38 119 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 38 120 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 38 121 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 39 122 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 41 123 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . . 41 124 5.10.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 42 125 5.10.2. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 42 126 5.10.3. Proxy-Uri . . . . . . . . . . . . . . . . . . . . . . 43 127 5.10.4. Content-Type . . . . . . . . . . . . . . . . . . . . 44 128 5.10.5. Accept . . . . . . . . . . . . . . . . . . . . . . . 44 129 5.10.6. Max-Age . . . . . . . . . . . . . . . . . . . . . . . 45 130 5.10.7. ETag . . . . . . . . . . . . . . . . . . . . . . . . 45 131 5.10.8. Location-Path and Location-Query . . . . . . . . . . 45 132 5.10.9. If-Match . . . . . . . . . . . . . . . . . . . . . . 46 133 5.10.10. If-None-Match . . . . . . . . . . . . . . . . . . . . 47 134 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 47 135 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 47 136 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . . 48 137 6.3. Normalization and Comparison Rules . . . . . . . . . . . . 48 138 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 49 139 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 50 140 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 51 141 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 51 142 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . . 52 143 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 52 144 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . . 53 145 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 53 146 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . . 53 147 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 54 148 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 54 149 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 54 150 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 56 151 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 57 152 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 57 153 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 58 154 9.2. Using CoAP with IPsec . . . . . . . . . . . . . . . . . . 60 155 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 60 156 10.1. CoAP-HTTP Mapping . . . . . . . . . . . . . . . . . . . . 61 157 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 62 158 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 62 159 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 63 160 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 63 161 10.2. HTTP-CoAP Mapping . . . . . . . . . . . . . . . . . . . . 63 162 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . . 63 163 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . . 64 164 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 64 165 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 64 166 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 65 167 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 65 168 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 65 169 11. Security Considerations . . . . . . . . . . . . . . . . . . . 65 170 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . . 65 171 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . . 66 172 11.3. Risk of amplification . . . . . . . . . . . . . . . . . . 66 173 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . . 67 174 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . . 68 175 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 70 176 12.1. CoAP Code Registry . . . . . . . . . . . . . . . . . . . . 70 177 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 70 178 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 71 179 12.2. Option Number Registry . . . . . . . . . . . . . . . . . . 73 180 12.3. Media Type Registry . . . . . . . . . . . . . . . . . . . 75 181 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 76 182 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . . 77 183 12.6. Service Name and Port Number Registration . . . . . . . . 78 184 12.7. Secure Service Name and Port Number Registration . . . . . 79 185 12.8. Multicast Address Registration . . . . . . . . . . . . . . 79 186 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 80 187 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 80 188 14.1. Normative References . . . . . . . . . . . . . . . . . . . 80 189 14.2. Informative References . . . . . . . . . . . . . . . . . . 83 190 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 84 191 Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 90 192 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . . 91 193 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 99 195 1. Introduction 197 The use of web services on the Internet has become ubiquitous in most 198 applications, and depends on the fundamental Representational State 199 Transfer [REST] architecture of the web. 201 The Constrained RESTful Environments (CoRE) work aims at realizing 202 the REST architecture in a suitable form for the most constrained 203 nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and 204 networks (e.g. 6LoWPAN, [RFC4944]). Constrained networks like 205 6LoWPAN support the expensive fragmentation of IPv6 packets into 206 small link-layer frames. One design goal of CoAP has been to keep 207 message overhead small, thus limiting the use of fragmentation. 209 One of the main goals of CoAP is to design a generic web protocol for 210 the special requirements of this constrained environment, especially 211 considering energy, building automation and other machine-to-machine 212 (M2M) applications. The goal of CoAP is not to blindly compress HTTP 213 [RFC2616], but rather to realize a subset of REST common with HTTP 214 but optimized for M2M applications. Although CoAP could be used for 215 compressing simple HTTP interfaces, it more importantly also offers 216 features for M2M such as built-in discovery, multicast support and 217 asynchronous message exchanges. 219 This document specifies the Constrained Application Protocol (CoAP), 220 which easily translates to HTTP for integration with the existing web 221 while meeting specialized requirements such as multicast support, 222 very low overhead and simplicity for constrained environments and M2M 223 applications. 225 1.1. Features 227 CoAP has the following main features: 229 o Constrained web protocol fulfilling M2M requirements. 231 o UDP binding with optional reliability supporting unicast and 232 multicast requests. 234 o Asynchronous message exchanges. 236 o Low header overhead and parsing complexity. 238 o URI and Content-type support. 240 o Simple proxy and caching capabilities. 242 o A stateless HTTP mapping, allowing proxies to be built providing 243 access to CoAP resources via HTTP in a uniform way or for HTTP 244 simple interfaces to be realized alternatively over CoAP. 246 o Security binding to Datagram Transport Layer Security (DTLS). 248 1.2. Terminology 250 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 251 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 252 document are to be interpreted as described in [RFC2119] when they 253 appear in ALL CAPS. These words may also appear in this document in 254 lower case as plain English words, absent their normative meanings. 256 This specification requires readers to be familiar with all the terms 257 and concepts that are discussed in [RFC2616]. In addition, this 258 specification defines the following terminology: 260 Endpoint 261 An entity participating in the CoAP protocol. Colloquially, an 262 endpoint lives on a "Node", although "Host" would be more 263 consistent with Internet standards usage, and is further 264 identified by transport layer multiplexing information that can 265 include a UDP port number and a security association 266 (Section 4.1). 268 Sender 269 The originating endpoint of a message. When the aspect of 270 identification of the specific sender is in focus, also "source 271 endpoint". 273 Recipient 274 The destination endpoint of a message. When the aspect of 275 identification of the specific recipient is in focus, also 276 "destination endpoint". 278 Client 279 The originating endpoint of a request; the destination endpoint of 280 a response. 282 Server 283 The destination endpoint of a request; the originating endpoint of 284 a response. 286 Origin Server 287 The server on which a given resource resides or is to be created. 289 Intermediary 290 A CoAP endpoint that acts both as a server and as a client towards 291 (possibly via further intermediaries) an origin server. There are 292 two common forms of intermediary: proxy and reverse proxy. In 293 some cases, a single endpoint might act as an origin server, 294 proxy, or reverse proxy, switching behavior based on the nature of 295 each request. 297 Proxy 298 A "proxy" is an endpoint selected by a client, usually via local 299 configuration rules, to perform requests on behalf of the client, 300 doing any necessary translations. Some translations are minimal, 301 such as for proxy requests for "coap" URIs, whereas other requests 302 might require translation to and from entirely different 303 application-layer protocols. 305 Reverse Proxy 306 A "reverse proxy" is an endpoint that acts as a layer above some 307 other server(s) and satisfies requests on behalf of these, doing 308 any necessary translations. Unlike a proxy, a reverse proxy 309 receives requests as if it was the origin server for the target 310 resource; the requesting client will not be aware that it is 311 communicating with a reverse proxy. 313 Confirmable Message 314 Some messages require an acknowledgement. These messages are 315 called "Confirmable". When no packets are lost, each confirmable 316 message elicits exactly one return message of type Acknowledgement 317 or type Reset. 319 Non-Confirmable Message 320 Some other messages do not require an acknowledgement. This is 321 particularly true for messages that are repeated regularly for 322 application requirements, such as repeated readings from a sensor 323 where eventual success is sufficient. 325 Acknowledgement Message 326 An Acknowledgement message acknowledges that a specific 327 Confirmable Message arrived. It does not indicate success or 328 failure of any encapsulated request. 330 Reset Message 331 A Reset message indicates that a specific message (confirmable or 332 non-confirmable) was received, but some context is missing to 333 properly process it. This condition is usually caused when the 334 receiving node has rebooted and has forgotten some state that 335 would be required to interpret the message. 337 Piggy-backed Response 338 A Piggy-backed Response is included right in a CoAP 339 Acknowledgement (ACK) message that is sent to acknowledge receipt 340 of the Request for this Response (Section 5.2.1). 342 Separate Response 343 When a Confirmable message carrying a Request is acknowledged with 344 an empty message (e.g., because the server doesn't have the answer 345 right away), a Separate Response is sent in a separate message 346 exchange (Section 5.2.2). 348 Critical Option 349 An option that would need to be understood by the endpoint 350 receiving the message in order to properly process the message 351 (Section 5.4.1). Note that the implementation of critical options 352 is, as the name "Option" implies, generally optional: unsupported 353 critical options lead to rejection of the message. 355 Elective Option 356 An option that is intended to be ignored by an endpoint that does 357 not understand it. Processing the message even without 358 understanding the option is acceptable (Section 5.4.1). 360 Resource Discovery 361 The process where a CoAP client queries a server for its list of 362 hosted resources (i.e., links, Section 7). 364 In this specification, the term "byte" is used in its now customary 365 sense as a synonym for "octet". 367 In this specification, the operator "^" stands for exponentiation. 369 2. Constrained Application Protocol 371 The interaction model of CoAP is similar to the client/server model 372 of HTTP. However, machine-to-machine interactions typically result 373 in a CoAP implementation acting in both client and server roles. A 374 CoAP request is equivalent to that of HTTP, and is sent by a client 375 to request an action (using a method code) on a resource (identified 376 by a URI) on a server. The server then sends a response with a 377 response code; this response may include a resource representation. 379 Unlike HTTP, CoAP deals with these interchanges asynchronously over a 380 datagram-oriented transport such as UDP. This is done logically 381 using a layer of messages that supports optional reliability (with 382 exponential back-off). CoAP defines four types of messages: 383 Confirmable, Non-Confirmable, Acknowledgement, Reset; method codes 384 and response codes included in some of these messages make them carry 385 requests or responses. The basic exchanges of the four types of 386 messages are somewhat orthogonal to the request/response 387 interactions; requests can be carried in Confirmable and Non- 388 Confirmable messages, and responses can be carried in these as well 389 as piggy-backed in acknowledgements. 391 One could think of CoAP logically as using a two-layer approach, a 392 CoAP messaging layer used to deal with UDP and the asynchronous 393 nature of the interactions, and the request/response interactions 394 using Method and Response codes (see Figure 1). CoAP is however a 395 single protocol, with messaging and request/response just features of 396 the CoAP header. 398 +----------------------+ 399 | Application | 400 +----------------------+ 401 +----------------------+ 402 | Requests/Responses | 403 |----------------------| CoAP 404 | Messages | 405 +----------------------+ 406 +----------------------+ 407 | UDP | 408 +----------------------+ 410 Figure 1: Abstract layering of CoAP 412 2.1. Messaging Model 414 The CoAP messaging model is based on the exchange of messages over 415 UDP between endpoints. 417 CoAP uses a short fixed-length binary header (4 bytes) that may be 418 followed by compact binary options and a payload. This message 419 format is shared by requests and responses. The CoAP message format 420 is specified in Section 3. Each message contains a Message ID used 421 to detect duplicates and for optional reliability. 423 Reliability is provided by marking a message as Confirmable (CON). A 424 Confirmable message is retransmitted using a default timeout and 425 exponential back-off between retransmissions, until the recipient 426 sends an Acknowledgement message (ACK) with the same Message ID (for 427 example, 0x7d34) from the corresponding endpoint; see Figure 2. When 428 a recipient is not able to process a Confirmable message, it replies 429 with a Reset message (RST) instead of an Acknowledgement (ACK). 431 Client Server 432 | | 433 | CON [0x7d34] | 434 +----------------->| 435 | | 436 | ACK [0x7d34] | 437 |<-----------------+ 438 | | 440 Figure 2: Reliable message transmission 442 A message that does not require reliable transmission, for example 443 each single measurement out of a stream of sensor data, can be sent 444 as a Non-confirmable message (NON). These are not acknowledged, but 445 still have a Message ID for duplicate detection; see Figure 3. When 446 a recipient is not able to process a Non-confirmable message, it may 447 reply with a Reset message (RST). 449 Client Server 450 | | 451 | NON [0x01a0] | 452 +----------------->| 453 | | 455 Figure 3: Unreliable message transmission 457 See Section 4 for details of CoAP messages. 459 As CoAP is based on UDP, it also supports the use of multicast IP 460 destination addresses, enabling multicast CoAP requests. Section 8 461 discusses the proper use of CoAP messages with multicast addresses 462 and precautions for avoiding response congestion. 464 Several security modes are defined for CoAP in Section 9 ranging from 465 no security to certificate-based security. The use of IPsec along 466 with a binding to DTLS are specified for securing the protocol. 468 2.2. Request/Response Model 470 CoAP request and response semantics are carried in CoAP messages, 471 which include either a method code or response code, respectively. 472 Optional (or default) request and response information, such as the 473 URI and payload content-type are carried as CoAP options. A Token 474 Option is used to match responses to requests independently from the 475 underlying messages (Section 5.3). 477 A request is carried in a Confirmable (CON) or Non-confirmable (NON) 478 message, and if immediately available, the response to a request 479 carried in a Confirmable message is carried in the resulting 480 Acknowledgement (ACK) message. This is called a piggy-backed 481 response, detailed in Section 5.2.1. Two examples for a basic GET 482 request with piggy-backed response are shown in Figure 4, one 483 successful, one resulting in a 4.04 (Not Found) response. 485 Client Server Client Server 486 | | | | 487 | CON [0xbc90] | | CON [0xbc91] | 488 | GET /temperature | | GET /temperature | 489 | (Token 0x71) | | (Token 0x72) | 490 +----------------->| +----------------->| 491 | | | | 492 | ACK [0xbc90] | | ACK [0xbc91] | 493 | 2.05 Content | | 4.04 Not Found | 494 | (Token 0x71) | | (Token 0x72) | 495 | "22.5 C" | | "Not found" | 496 |<-----------------+ |<-----------------+ 497 | | | | 499 Figure 4: Two GET requests with piggy-backed responses 501 If the server is not able to respond immediately to a request carried 502 in a Confirmable message, it simply responds with an empty 503 Acknowledgement message so that the client can stop retransmitting 504 the request. When the response is ready, the server sends it in a 505 new Confirmable message (which then in turn needs to be acknowledged 506 by the client). This is called a separate response, as illustrated 507 in Figure 5 and described in more detail in Section 5.2.2. 509 Client Server 510 | | 511 | CON [0x7a10] | 512 | GET /temperature | 513 | (Token 0x73) | 514 +----------------->| 515 | | 516 | ACK [0x7a10] | 517 |<-----------------+ 518 | | 519 ... Time Passes ... 520 | | 521 | CON [0x23bb] | 522 | 2.05 Content | 523 | (Token 0x73) | 524 | "22.5 C" | 525 |<-----------------+ 526 | | 527 | ACK [0x23bb] | 528 +----------------->| 529 | | 531 Figure 5: A GET request with a separate response 533 Likewise, if a request is sent in a Non-Confirmable message, then the 534 response is usually sent using a new Non-Confirmable message, 535 although the server may send a Confirmable message. This type of 536 exchange is illustrated in Figure 6. 538 Client Server 539 | | 540 | NON [0x7a11] | 541 | GET /temperature | 542 | (Token 0x74) | 543 +----------------->| 544 | | 545 | NON [0x23bc] | 546 | 2.05 Content | 547 | (Token 0x74) | 548 | "22.5 C" | 549 |<-----------------+ 550 | | 552 Figure 6: A NON request and response 554 CoAP makes use of GET, PUT, POST and DELETE methods in a similar 555 manner to HTTP, with the semantics specified in Section 5.8. (Note 556 that the detailed semantics of CoAP methods are "almost, but not 557 entirely unlike" those of HTTP methods: Intuition taken from HTTP 558 experience generally does apply well, but there are enough 559 differences that make it worthwhile to actually read the present 560 specification.) 562 URI support in a server is simplified as the client already parses 563 the URI and splits it into host, port, path and query components, 564 making use of default values for efficiency. Response codes 565 correspond to a small subset of HTTP response codes with a few CoAP 566 specific codes added, as defined in Section 5.9. 568 2.3. Intermediaries and Caching 570 The protocol supports the caching of responses in order to 571 efficiently fulfill requests. Simple caching is enabled using 572 freshness and validity information carried with CoAP responses. A 573 cache could be located in an endpoint or an intermediary. Caching 574 functionality is specified in Section 5.6. 576 Proxying is useful in constrained networks for several reasons, 577 including network traffic limiting, to improve performance, to access 578 resources of sleeping devices or for security reasons. The proxying 579 of requests on behalf of another CoAP endpoint is supported in the 580 protocol. When using a proxy, the URI of the resource to request is 581 included in the request, while the destination IP address is set to 582 the address of the proxy. See Section 5.7 for more information on 583 proxy functionality. 585 As CoAP was designed according to the REST architecture and thus 586 exhibits functionality similar to that of the HTTP protocol, it is 587 quite straightforward to map from CoAP to HTTP and from HTTP to CoAP. 588 Such a mapping may be used to realize an HTTP REST interface using 589 CoAP, or for converting between HTTP and CoAP. This conversion can 590 be carried out by a proxy, which converts the method or response 591 code, content-type, and options to the corresponding HTTP feature. 592 Section 10 provides more detail about HTTP mapping. 594 2.4. Resource Discovery 596 Resource discovery is important for machine-to-machine interactions, 597 and is supported using the CoRE Link Format 598 [I-D.ietf-core-link-format] as discussed in Section 7. 600 3. Message Format 602 CoAP is based on the exchange of short messages which, by default, 603 are transported over UDP (i.e. each CoAP message occupies the data 604 section of one UDP datagram). CoAP may be used with Datagram 605 Transport Layer Security (DTLS) (see Section 9.1). It could also be 606 used over other transports such as TCP or SCTP, the specification of 607 which is out of this document's scope. 609 CoAP messages are encoded in a simple binary format. A message 610 consists of a fixed-sized CoAP Header followed by options in Type- 611 Length-Value (TLV) format and a payload. The number of options is 612 determined by the header. The payload is made up of the bytes after 613 the options, if any; its length is calculated from the datagram 614 length. 616 0 1 2 3 617 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 618 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 619 |Ver| T | OC | Code | Message ID | 620 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 621 | Options (if any) ... 622 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 623 | Payload (if any) ... 624 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 626 Figure 7: Message Format 628 3.1. Header Format 630 The fields in the header are defined as follows: 632 Version (Ver): 2-bit unsigned integer. Indicates the CoAP version 633 number. Implementations of this specification MUST set this field 634 to 1. Other values are reserved for future versions. 636 Type (T): 2-bit unsigned integer. Indicates if this message is of 637 type Confirmable (0), Non-Confirmable (1), Acknowledgement (2) or 638 Reset (3). See Section 4 for the semantics of these message 639 types. 641 Option Count (OC): 4-bit unsigned integer. Indicates the number of 642 options after the header (0-14). If set to 0, there are no 643 options and the payload (if any) immediately follows the header. 644 If set to 15, then an end-of-options marker is used to indicate 645 the end of options and the start of the payload. The format of 646 options is defined below. 648 Code: 8-bit unsigned integer. Indicates if the message carries a 649 request (1-31) or a response (64-191), or is empty (0). (All 650 other code values are reserved.) In case of a request, the Code 651 field indicates the Request Method; in case of a response a 652 Response Code. Possible values are maintained in the CoAP Code 653 Registry (Section 12.1). See Section 5 for the semantics of 654 requests and responses. 656 Message ID: 16-bit unsigned integer in network byte order. Used for 657 the detection of message duplication, and to match messages of 658 type Acknowledgement/Reset and messages of type Confirmable/ 659 Non-confirmable. See Section 4 for Message ID generation rules 660 and how messages are matched. 662 3.2. Option Format 664 Options MUST appear in order of their Option Number (see 665 Section 5.4.5). A delta encoding is used between options: The Option 666 Number for each Option is calculated as the sum of its Option Delta 667 field and the Option Number of the preceding Option in the message, 668 if any. For the first Option in the message, the Option Delta 669 becomes the Option Number (i.e., an implementation can simply 670 initialize the number variable as zero). Multiple options with the 671 same Option Number can be included by using an Option Delta of zero. 672 Following the Option Delta, each option has a Length field which 673 specifies the length of the Option Value, in bytes. The Length field 674 can be extended by one byte for options with values longer than 14 675 bytes. The Option Value immediately follows the Length field. 677 0 1 2 3 4 5 6 7 678 +---+---+---+---+---+---+---+---+ 679 | Option Delta | Length | for 0..14 680 +---+---+---+---+---+---+---+---+ 681 | Option Value ... 682 +---+---+---+---+---+---+---+---+ 683 for 15..270: 684 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 685 | Option Delta | 1 1 1 1 | Length - 15 | 686 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 687 | Option Value ... 688 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 690 Figure 8: Option Format 692 The fields in an option are defined as follows: 694 Option Delta: 4-bit unsigned integer. Indicates the difference 695 between the Option Number of this option and the previous option 696 (or zero for the first option). In other words, the Option Number 697 is calculated by simply summing the Option Delta fields of this 698 and previous options before it. If a delta larger than 14 is 699 needed, the Option Numbers that are non-zero multiples of 14 700 (i.e., 14, 28, 42, ...) can be used with the Length field set to 0 701 as "fenceposts". The Option Delta 15 is reserved for the the end- 702 of-options marker (see below). 704 Length: Indicates the length of the Option Value, in bytes. 705 Normally Length is a 4-bit unsigned integer allowing value lengths 706 of 0-14 bytes. When the Length field is set to 15, another byte 707 is added as an 8-bit unsigned integer whose value is added to the 708 15, allowing option value lengths of 15-270 bytes. 710 Value: The length and format of the Option Value depends on the 711 respective option, which MAY define variable length values. See 712 Section 3.3 for the formats the options defined in this document 713 make use of; other options MAY make use of other option value 714 formats. 716 If the Option Count field in the header is 15 and the Option Delta is 717 15, the option is interpreted as the end-of-options marker instead of 718 the option with the resulting Option Number. A sender MUST NOT 719 include a value with the marker (i.e., the option length is 0) and a 720 recipient MUST ignore any value of the marker. When this marker is 721 encountered, it is immediately followed by the payload (if any). 722 (Note that, by this special meaning, the Option Delta of 15 is made 723 special, not any specific Option Number.) The sender MUST NOT 724 include the Option Delta of 15 in a message with an Option Count 725 other than 15. 727 Option Numbers are maintained in the CoAP Option Number Registry 728 (Section 12.2). See Section 5.10 for the semantics of the options 729 defined in this document. 731 3.3. Option Value Formats 733 The options defined in this document make use of the following option 734 value formats. 736 3.3.1. uint 738 A non-negative integer which is represented in network byte order 739 using the given number of bytes. An option definition may specify a 740 range of permissible numbers of bytes; if it has a choice, a sender 741 SHOULD represent the integer with as few bytes as possible, i.e., 742 without leading zeros. A recipient MUST be prepared to process 743 values with leading zeros. 745 Implementation Note: The exceptional behavior permitted above is for 746 highly constrained templated implementations (e.g. hardware 747 implementations) that use fixed size options in the templates. 749 Length = 0 (implies value of 0) 751 0 752 0 1 2 3 4 5 6 7 753 +-+-+-+-+-+-+-+-+ 754 Length = 1 | 0-255 | 755 +-+-+-+-+-+-+-+-+ 757 0 1 758 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 759 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 760 Length = 2 | 0-65535 | 761 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 763 Length = 3 is 24 bits, Length = 4 is 32 bits etc. 765 3.3.2. string 767 A Unicode string which is encoded using UTF-8 [RFC3629] in Net- 768 Unicode form [RFC5198]. Note that here and in all other places where 769 UTF-8 encoding is used in the CoAP protocol, the intention is that 770 the encoded strings can be directly used and compared as opaque byte 771 strings by CoAP protocol implementations. There is no expectation 772 and no need to perform normalization within a CoAP implementation 773 unless Unicode strings that are not known to be normalized are 774 imported from sources outside the CoAP protocol. Note also that 775 ASCII strings (that do not make use of special control characters) 776 are always valid UTF-8 Net-Unicode strings. 778 3.3.3. opaque 780 An opaque sequence of bytes. 782 3.3.4. empty 784 A zero-length sequence of bytes. 786 4. Message Transmission 788 CoAP messages are exchanged asynchronously between CoAP endpoints. 789 They are used to transport CoAP requests and responses, the semantics 790 of which are defined in Section 5. 792 As CoAP is bound to non-reliable transports such as UDP, CoAP 793 messages may arrive out of order, appear duplicated, or go missing 794 without notice. For this reason, CoAP implements a lightweight 795 reliability mechanism, without trying to re-create the full feature 796 set of a transport like TCP. It has the following features: 798 o Simple stop-and-wait retransmission reliability with exponential 799 back-off for "confirmable" messages. 801 o Duplicate detection for both "confirmable" and "non-confirmable" 802 messages. 804 4.1. Messages and Endpoints 806 A CoAP endpoint is the source or destination of a CoAP message. It 807 is identified depending on the security mode used (see Section 9): 808 With no security, the endpoint is solely identified by an IP address 809 and a UDP port number. With other security modes, the endpoint is 810 identified as defined by the security mode. 812 There are different types of messages. The type of a message is 813 specified by the T field of the CoAP header. 815 Separate from the message type, a message may carry a request, a 816 response, or be empty. This is signaled by the Code field in the 817 CoAP header and is relevant to the request/response model. Possible 818 values for the Code field are maintained by the CoAP Code Registry 819 (Section 12.1). 821 An empty message has the Code field set to 0. The OC field SHOULD be 822 set to 0 and no bytes SHOULD be present after the Message ID field. 823 The OC field and any bytes trailing the header MUST be ignored by any 824 recipient. 826 4.2. Messages Transmitted Reliably 828 The reliable transmission of a message is initiated by marking the 829 message as "confirmable" in the CoAP header. A confirmable message 830 always carries either a request or response and MUST NOT be empty. A 831 recipient MUST acknowledge such a message with an acknowledgement 832 message or, if it lacks context to process the message properly, MUST 833 reject it with a reset message. The acknowledgement message MUST 834 echo the Message ID of the confirmable message, and MUST carry a 835 response or be empty (see Section 5.2.1 and Section 5.2.2). The 836 reset message MUST echo the Message ID of the confirmable message, 837 and MUST be empty. 839 The sender retransmits the confirmable message at exponentially 840 increasing intervals, until it receives an acknowledgement (or reset 841 message), or runs out of attempts. 843 Retransmission is controlled by two things that a CoAP endpoint MUST 844 keep track of for each confirmable message it sends while waiting for 845 an acknowledgement (or reset): a timeout and a retransmission 846 counter. For a new confirmable message, the initial timeout is set 847 to a random number between ACK_TIMEOUT and (ACK_TIMEOUT * 848 ACK_RANDOM_FACTOR) (see Section 4.8), and the retransmission counter 849 is set to 0. When the timeout is triggered and the retransmission 850 counter is less than MAX_RETRANSMIT, the message is retransmitted, 851 the retransmission counter is incremented, and the timeout is 852 doubled. If the retransmission counter reaches MAX_RETRANSMIT on a 853 timeout, or if the endpoint receives a reset message, then the 854 attempt to transmit the message is canceled and the application 855 process informed of failure. On the other hand, if the endpoint 856 receives an acknowledgement message in time, transmission is 857 considered successful. 859 A CoAP endpoint that sent a confirmable message MAY give up in 860 attempting to obtain an ACK even before the MAX_RETRANSMIT counter 861 value is reached: E.g., the application has canceled the request as 862 it no longer needs a response, or there is some other indication that 863 the CON message did arrive. In particular, a CoAP request message 864 may have elicited a separate response, in which case it is clear to 865 the requester that only the ACK was lost and a retransmission of the 866 request would serve no purpose. However, a responder MUST NOT in 867 turn rely on this cross-layer behavior from a requester, i.e. it 868 SHOULD retain the state to create the ACK for the request, if needed, 869 even if a confirmable response was already acknowledged by the 870 requester. 872 4.3. Messages Transmitted Without Reliability 874 Some messages do not require an acknowledgement. This is 875 particularly true for messages that are repeated regularly for 876 application requirements, such as repeated readings from a sensor 877 where eventual success is sufficient. 879 As a more lightweight alternative, a message can be transmitted less 880 reliably by marking the message as "non-confirmable". A non- 881 confirmable message always carries either a request or response and 882 MUST NOT be empty. A non-confirmable message MUST NOT be 883 acknowledged by the recipient. If a recipient lacks context to 884 process the message properly, it MAY reject the message with a reset 885 message or otherwise MUST silently ignore it. 887 At the CoAP level, there is no way for the sender to detect if a non- 888 confirmable message was received or not. A sender MAY choose to 889 transmit a non-confirmable message multiple times, or the network may 890 duplicate the message in transit. To enable the receiver to act only 891 once on the message, non-confirmable messages specify a Message ID as 892 well. (This Message ID is drawn from the same number space as the 893 Message IDs for confirmable messages.) 895 4.4. Message Correlation 897 An acknowledgement or reset message is related to a confirmable 898 message or non-confirmable message by means of a Message ID along 899 with additional address information of the corresponding endpoint. 900 The Message ID is a 16-bit unsigned integer that is generated by the 901 sender of a confirmable or non-confirmable message and included in 902 the CoAP header. The Message ID MUST be echoed in the 903 acknowledgement or reset message by the recipient. 905 The same Message ID MUST NOT be re-used (per Message ID variable) 906 within the EXCHANGE_LIFETIME (Section 4.8.2). 908 Implementation Note: Several implementation strategies can be 909 employed for generating Message IDs. In the simplest case a CoAP 910 endpoint generates Message IDs by keeping a single Message ID 911 variable, which is changed each time a new confirmable or non- 912 confirmable message is sent regardless of the destination address 913 or port. Endpoints dealing with large numbers of transactions 914 could keep multiple Message ID variables, for example per prefix 915 or destination address. The initial variable value should be 916 randomized. 918 For an acknowledgement or reset message to match a confirmable or 919 non-confirmable message, the Message ID and source endpoint of the 920 acknowledgement or reset message MUST match the Message ID and 921 destination endpoint of the confirmable or non-confirmable message. 923 4.5. Message Deduplication 925 A recipient MUST be prepared to receive the same confirmable message 926 (as indicated by the Message ID and source endpoint) multiple times 927 within the EXCHANGE_LIFETIME (Section 4.8.2), for example, when its 928 acknowledgement went missing or didn't reach the original sender 929 before the first timeout. The recipient SHOULD acknowledge each 930 duplicate copy of a confirmable message using the same 931 acknowledgement or reset message, but SHOULD process any request or 932 response in the message only once. This rule MAY be relaxed in case 933 the confirmable message transports a request that is idempotent (see 934 Section 5.1) or can be handled in an idempotent fashion. Examples 935 for relaxed message deduplication: 937 o A server MAY relax the requirement to answer all retransmissions 938 of an idempotent request with the same response (Section 4.2), so 939 that it does not have to maintain state for Message IDs. For 940 example, an implementation might want to process duplicate 941 transmissions of a GET, PUT or DELETE request as separate requests 942 if the effort incurred by duplicate processing is less expensive 943 than keeping track of previous responses would be. 945 o A constrained server MAY even want to relax this requirement for 946 certain non-idempotent requests if the application semantics make 947 this trade-off favorable. For example, if the result of a POST 948 request is just the creation of some short-lived state at the 949 server, it may be less expensive to incur this effort multiple 950 times for a request than keeping track of whether a previous 951 transmission of the same request already was processed. 953 A recipient MUST be prepared to receive the same non-confirmable 954 message (as indicated by the Message ID and source endpoint) multiple 955 times within NON_LIFETIME (Section 4.8.2). As a general rule that 956 may be relaxed based on the specific semantics of a message, the 957 recipient SHOULD silently ignore any duplicated non-confirmable 958 message, and SHOULD process any request or response in the message 959 only once. 961 4.6. Message Size 963 While specific link layers make it beneficial to keep CoAP messages 964 small enough to fit into their link layer packets (see Section 1), 965 this is a matter of implementation quality. The CoAP specification 966 itself provides only an upper bound to the message size. Messages 967 larger than an IP fragment result in undesired packet fragmentation. 968 A CoAP message, appropriately encapsulated, SHOULD fit within a 969 single IP packet (i.e., avoid IP fragmentation) and (by fitting into 970 one UDP payload) obviously MUST fit within a single IP datagram. If 971 the Path MTU is not known for a destination, an IP MTU of 1280 bytes 972 SHOULD be assumed; if nothing is known about the size of the headers, 973 good upper bounds are 1152 bytes for the message size and 1024 bytes 974 for the payload size. 976 Implementation Note: CoAP's choice of message size parameters works 977 well with IPv6 and with most of today's IPv4 paths. (However, 978 with IPv4, it is harder to absolutely ensure that there is no IP 979 fragmentation. If IPv4 support on unusual networks is a 980 consideration, implementations may want to limit themselves to 981 more conservative IPv4 datagram sizes such as 576 bytes; worse, 982 the absolute minimum value of the IP MTU for IPv4 is as low as 68 983 bytes, which would leave only 40 bytes minus security overhead for 984 a UDP payload. Implementations extremely focused on this problem 985 set might also set the IPv4 DF bit and perform some form of path 986 MTU discovery; this should generally be unnecessary in most 987 realistic use cases for CoAP, however.) A more important kind of 988 fragmentation in many constrained networks is that on the 989 adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 990 bytes including various overheads); this may motivate 991 implementations to be frugal in their packet sizes and to move to 992 block-wise transfers [I-D.ietf-core-block] when approaching three- 993 digit message sizes. 995 Message sizes are also of considerable importance to 996 implementations on constrained nodes. Many implementations will 997 need to allocate a buffer for incoming messages. If an 998 implementation is too constrained to allow for allocating the 999 above-mentioned upper bound, it could apply the following 1000 implementation strategy: Implementations receiving a datagram into 1001 a buffer that is too small are usually able to determine if the 1002 trailing portion of a datagram was discarded and to retrieve the 1003 initial portion. So, if not all of the payload, at least the CoAP 1004 header and options are likely to fit within the buffer. A server 1005 can thus fully interpret a request and return a 4.13 (Request 1006 Entity Too Large) response code if the payload was truncated. A 1007 client sending an idempotent request and receiving a response 1008 larger than would fit in the buffer can repeat the request with a 1009 suitable value for the Block Option [I-D.ietf-core-block]. 1011 4.7. Congestion Control 1013 Basic congestion control for CoAP is provided by the exponential 1014 back-off mechanism in Section 4.2. 1016 In order not to cause congestion, Clients (including proxies) SHOULD 1017 strictly limit the number of simultaneous outstanding interactions 1018 that they maintain to a given server (including proxies). An 1019 outstanding interaction is either a CON for which an ACK has not yet 1020 been received but is still expected (message layer) or a request for 1021 which a response has not yet been received but is still expected 1022 (which may both occur at the same time, counting as one outstanding 1023 interaction). A good value for this limit is the number 1. (Note 1024 that [RFC2616], in trying to achieve a similar objective, did specify 1025 a specific number of simultaneous connections as a ceiling. While 1026 revising [RFC2616], this was found to be impractical for many 1027 applications [I-D.ietf-httpbis-p1-messaging]. For the same 1028 considerations, this specification does not mandate a particular 1029 maximum number of outstanding interactions, but instead encourages 1030 clients to be conservative when initiating interactions.) 1032 Further congestion control optimizations and considerations are 1033 expected in the future, which may for example provide automatic 1034 initialization of the CoAP transmission parameters defined in 1035 Section 4.8. 1037 4.8. Transmission Parameters 1039 Message transmission is controlled by the following parameters: 1041 +-------------------+---------------+ 1042 | name | default value | 1043 +-------------------+---------------+ 1044 | ACK_TIMEOUT | 2 seconds | 1045 | ACK_RANDOM_FACTOR | 1.5 | 1046 | MAX_RETRANSMIT | 4 | 1047 +-------------------+---------------+ 1049 4.8.1. Changing The Parameters 1051 The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, and MAX_RETRANSMIT may 1052 be configured to values specific to the application environment, 1053 however the configuration method is out of scope of this document. 1054 It is recommended that an application environment use consistent 1055 values for these parameters. 1057 The transmission parameters have been chosen to achieve a behavior in 1058 the presence of congestion that is safe in the Internet. If a 1059 configuration desires to use different values, the onus is on the 1060 configuration to ensure these congestion control properties are not 1061 violated. In particular, a decrease of ACK_TIMEOUT below 1 second 1062 would violate the guidelines of [RFC5405]. 1063 ([I-D.allman-tcpm-rto-consider] provides some additional background.) 1064 CoAP was designed to enable implementations that do not maintain 1065 round-trip-time (RTT) measurements. However, where it is desired to 1066 decrease the ACK_TIMEOUT significantly, this can only be done safely 1067 when maintaining such measurements. Configurations MUST NOT decrease 1068 ACK_TIMEOUT without using mechanisms that ensure congestion control 1069 safety, either defined in the configuration or in future standards 1070 documents. 1072 ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have 1073 a value that is sufficiently different from 1.0 to provide some 1074 protection from synchronization effects. 1076 MAX_RETRANSMIT can be freely adjusted, but a too small value will 1077 reduce the probability that a confirmable message is actually 1078 received, while a larger value will require further adjustments in 1079 the time values (see discussion below). 1081 If the choice of transmission parameters leads to an increase of 1082 derived time values (see below), the configuration mechanism MUST 1083 ensure the adjusted value is available to the corresponding end- 1084 points, too. 1086 4.8.2. Time Values derived from Transmission Parameters 1088 The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR and MAX_RETRANSMIT 1089 influences the timing of retransmissions, which in turn influences 1090 how long certain information items need to be kept by an 1091 implementation. To be able to unambiguously reference these derived 1092 time values, we give them names as follows: 1094 o MAX_TRANSMIT_SPAN is the maximum time from the first transmission 1095 of a confirmable message to its last retransmission. For the 1096 default transmission parameters, the value is (2+4+8+16)*1.5 = 45 1097 seconds, or more generally: 1099 ACK_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * ACK_RANDOM_FACTOR 1101 o MAX_TRANSMIT_WAIT is the maximum time from the first transmission 1102 of a confirmable message to the time when the sender gives up on 1103 receiving an acknowledgement or reset. For the default 1104 transmission parameters, the value is (2+4+8+16+32)*1.5 = 93 1105 seconds, or more generally: 1107 ACK_TIMEOUT * (2 ** (MAX_RETRANSMIT + 1) - 1) * 1108 ACK_RANDOM_FACTOR 1110 In addition, some assumptions need to be made on the characteristics 1111 of the network and the nodes. 1113 o MAX_LATENCY is the maximum time a datagram is expected to take 1114 from the start of its transmission to the completion of its 1115 reception. This constant is related to the MSL (Maximum Segment 1116 Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 1117 minutes" ([RFC0793] glossary, page 81). Note that this is not 1118 necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not 1119 intended to describe a situation when the protocol works well, but 1120 the worst case situation against which the protocol has to guard. 1121 We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart 1122 from being reasonably realistic for the bulk of configurations as 1123 well as close to the historic choice for TCP, this value also 1124 allows message ID lifetime timers to be represented in 8 bits 1125 (when measured in seconds). In these calculations, there is no 1126 assumption that the direction of the transmission is irrelevant 1127 (i.e. that the network is symmetric), just that the same value can 1128 reasonably be used as a maximum value for both directions. If 1129 that is not the case, the following calculations become only 1130 slightly more complex. 1132 o PROCESSING_DELAY is the time a node takes to turn around a 1133 confirmable message into an acknowledgement. We assume the node 1134 will attempt to send an ACK before having the sender time out, so 1135 as a conservative assumption we set it equal to ACK_TIMEOUT. 1137 o MAX_RTT is the maximum round-trip time, or: 1139 2 * MAX_LATENCY + PROCESSING_DELAY 1141 From these values, we can derive the following values relevant to the 1142 protocol operation: 1144 o EXCHANGE_LIFETIME is the time from starting to send a confirmable 1145 message to the time when an acknowledgement is no longer expected, 1146 i.e. message layer information about the message exchange can be 1147 purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a 1148 MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the 1149 way back. Note that there is no need to consider 1150 MAX_TRANSMIT_WAIT if the configuration is chosen such that the 1151 last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the 1152 difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is 1153 less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY 1154 is a worst case value unlikely to be met in the real world. In 1155 this case, EXCHANGE_LIFETIME simplifies to: 1157 (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * ACK_RANDOM_FACTOR) + 1158 (2 * MAX_LATENCY) + PROCESSING_DELAY 1160 or 248 seconds with the default transmission parameters. 1162 o NON_LIFETIME is the time from sending a non-confirmable message to 1163 the time its message-ID can be safely reused. If multiple 1164 transmission of a NON message is not used, its value is 1165 MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a 1166 NON message multiple times, in particular for multicast 1167 applications. While the period of re-use is not bounded by the 1168 specification, an expectation of reliable detection of duplication 1169 at the receiver is in the timescales of MAX_TRANSMIT_SPAN. 1170 Therefore, for this purpose, it is safer to use the value: 1172 MAX_TRANSMIT_SPAN + MAX_LATENCY 1174 or 145 seconds with the default transmission parameters; however, 1175 an implementation that just wants to use a single timeout value 1176 for retiring message-IDs can safely use the larger value for 1177 EXCHANGE_LIFETIME. 1179 5. Request/Response Semantics 1181 CoAP operates under a similar request/response model as HTTP: a CoAP 1182 endpoint in the role of a "client" sends one or more CoAP requests to 1183 a "server", which services the requests by sending CoAP responses. 1184 Unlike HTTP, requests and responses are not sent over a previously 1185 established connection, but exchanged asynchronously over CoAP 1186 messages. 1188 5.1. Requests 1190 A CoAP request consists of the method to be applied to the resource, 1191 the identifier of the resource, a payload and Internet media type (if 1192 any), and optional meta-data about the request. 1194 CoAP supports the basic methods of GET, POST, PUT, DELETE, which are 1195 easily mapped to HTTP. They have the same properties of safe (only 1196 retrieval) and idempotent (you can invoke it multiple times with the 1197 same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method 1198 is safe, therefore it MUST NOT take any other action on a resource 1199 other than retrieval. The GET, PUT and DELETE methods MUST be 1200 performed in such a way that they are idempotent. POST is not 1201 idempotent, because its effect is determined by the origin server and 1202 dependent on the target resource; it usually results in a new 1203 resource being created or the target resource being updated. 1205 A request is initiated by setting the Code field in the CoAP header 1206 of a confirmable or a non-confirmable message to a Method Code and 1207 including request information. 1209 The methods used in requests are described in detail in Section 5.8. 1211 5.2. Responses 1213 After receiving and interpreting a request, a server responds with a 1214 CoAP response, which is matched to the request by means of a client- 1215 generated token. 1217 A response is identified by the Code field in the CoAP header being 1218 set to a Response Code. Similar to the HTTP Status Code, the CoAP 1219 Response Code indicates the result of the attempt to understand and 1220 satisfy the request. These codes are fully defined in Section 5.9. 1221 The Response Code numbers to be set in the Code field of the CoAP 1222 header are maintained in the CoAP Response Code Registry 1223 (Section 12.1.2). 1225 0 1226 0 1 2 3 4 5 6 7 1227 +-+-+-+-+-+-+-+-+ 1228 |class| detail | 1229 +-+-+-+-+-+-+-+-+ 1231 Figure 9: Structure of a Response Code 1233 The upper three bits of the 8-bit Response Code number define the 1234 class of response. The lower five bits do not have any 1235 categorization role; they give additional detail to the overall class 1236 (Figure 9). There are 3 classes: 1238 2 - Success: The request was successfully received, understood, and 1239 accepted. 1241 4 - Client Error: The request contains bad syntax or cannot be 1242 fulfilled. 1244 5 - Server Error: The server failed to fulfill an apparently valid 1245 request. 1247 The response codes are designed to be extensible: Response Codes in 1248 the Client Error and Server Error class that are unrecognized by an 1249 endpoint MUST be treated as being equivalent to the generic Response 1250 Code of that class (4.00 and 5.00, respectively). However, there is 1251 no generic Response Code indicating success, so a Response Code in 1252 the Success class that is unrecognized by an endpoint can only be 1253 used to determine that the request was successful without any further 1254 details. 1256 As a human readable notation for specifications and protocol 1257 diagnostics, the numeric value of a response code is indicated by 1258 giving the upper three bits in decimal, followed by a dot and then 1259 the lower five bits in a two-digit decimal. E.g., "Not Found" is 1260 written as 4.04 -- indicating a value of hexadecimal 0x84 or decimal 1261 132. In other words, the dot "." functions as a short-cut for 1262 "*32+". 1264 The possible response codes are described in detail in Section 5.9. 1266 Responses can be sent in multiple ways, which are defined below. 1268 5.2.1. Piggy-backed 1270 In the most basic case, the response is carried directly in the 1271 acknowledgement message that acknowledges the request (which requires 1272 that the request was carried in a confirmable message). This is 1273 called a "Piggy-backed" Response. 1275 The response is returned in the acknowledgement message independent 1276 of whether the response indicates success or failure. In effect, the 1277 response is piggy-backed on the acknowledgement message, so no 1278 separate message is required to both acknowledge that the request was 1279 received and return the response. 1281 Implementation note: The protocol leaves the decision whether to 1282 piggy-back a response or not (i.e., send a separate response) to the 1283 server. The client MUST be prepared to receive either. On the 1284 quality of implementation level, there is a strong expectation that 1285 servers will implement code to piggy-back whenever possible -- saving 1286 resources in the network and both at the client and at the server. 1288 5.2.2. Separate 1290 It may not be possible to return a piggy-backed response in all 1291 cases. For example, a server might need longer to obtain the 1292 representation of the resource requested than it can wait sending 1293 back the acknowledgement message, without risking the client to 1294 repeatedly retransmit the request message. Responses to requests 1295 carried in a Non-Confirmable message are always sent separately (as 1296 there is no acknowledgement message). 1298 The server maybe initiates the attempt to obtain the resource 1299 representation and times out an acknowledgement timer, or it 1300 immediately sends an acknowledgement knowing in advance that there 1301 will be no piggy-backed response. The acknowledgement effectively is 1302 a promise that the request will be acted upon. 1304 When the server finally has obtained the resource representation, it 1305 sends the response. To ensure that this message is not lost, it is 1306 again sent as a confirmable message and answered by the client with 1307 an acknowledgement, echoing the new Message ID chosen by the server. 1309 (Implementation notes: Note that, as the underlying datagram 1310 transport may not be sequence-preserving, the confirmable message 1311 carrying the response may actually arrive before or after the 1312 acknowledgement message for the request. Note also that, while the 1313 CoAP protocol itself does not make any specific demands here, there 1314 is an expectation that the response will come within a time frame 1315 that is reasonable from an application point of view; as there is no 1316 underlying transport protocol that could be instructed to run a keep- 1317 alive mechanism, the requester MAY want to set up a timeout that is 1318 unrelated to CoAP's retransmission timers in case the server is 1319 destroyed or otherwise unable to send the response.) 1320 For a separate exchange, both the acknowledgement to the confirmable 1321 request and the acknowledgement to the confirmable response MUST be 1322 an empty message, i.e. one that carries neither a request nor a 1323 response. 1325 5.2.3. Non-Confirmable 1327 If the request message is non-confirmable, then the response SHOULD 1328 be returned in a non-confirmable message as well. However, an 1329 endpoint MUST be prepared to receive a non-confirmable response 1330 (preceded or followed by an empty acknowledgement message) in reply 1331 to a confirmable request, or a confirmable response in reply to a 1332 non-confirmable request. 1334 5.3. Request/Response Matching 1336 Regardless of how a response is sent, it is matched to the request by 1337 means of a token that is included by the client in the request as one 1338 of the options along with additional address information of the 1339 corresponding endpoint. The token MUST be echoed by the server in 1340 any resulting response without modification. 1342 The exact rules for matching a response to a request are as follows: 1344 1. The source endpoint of the response MUST be the same as the 1345 destination endpoint of the original request. 1347 2. In a piggy-backed response, both the Message ID of the 1348 confirmable request and the acknowledgement, and the token of the 1349 response and original request MUST match. In a separate 1350 response, just the token of the response and original request 1351 MUST match. 1353 The client SHOULD generate tokens in a way that tokens currently in 1354 use for a given source/destination pair are unique. (Note that a 1355 client can use the same token for any request if it uses a different 1356 source port number each time.) 1358 An endpoint that did not generate a token MUST treat it as opaque and 1359 make no assumptions about its format. (Note that there is a default 1360 value for the Token Option, so every message carries a token, even if 1361 it is not explicitly expressed in a CoAP option.) 1363 In case a message carrying a response is unexpected (i.e. the client 1364 is not waiting for a response with the specified address and/or 1365 token), the response SHOULD be rejected with a reset message and MUST 1366 NOT be acknowledged. 1368 5.4. Options 1370 Both requests and responses may include a list of one or more 1371 options. For example, the URI in a request is transported in several 1372 options, and meta-data that would be carried in an HTTP header in 1373 HTTP is supplied as options as well. 1375 CoAP defines a single set of options that are used in both requests 1376 and responses: 1378 o Content-Type 1380 o ETag 1382 o Location-Path 1384 o Location-Query 1386 o Max-Age 1388 o Proxy-Uri 1390 o Token 1392 o Uri-Host 1394 o Uri-Path 1396 o Uri-Port 1398 o Uri-Query 1400 o Accept 1402 o If-Match 1404 o If-None-Match 1406 The semantics of these options along with their properties are 1407 defined in detail in Section 5.10. 1409 Not all options are defined for use with all methods and response 1410 codes. The possible options for methods and response codes are 1411 defined in Section 5.8 and Section 5.9 respectively. In case an 1412 option is not defined for a method or response code, it MUST NOT be 1413 included by a sender and MUST be treated like an unrecognized option 1414 by a recipient. 1416 5.4.1. Critical/Elective 1418 Options fall into one of two classes: "critical" or "elective". The 1419 difference between these is how an option unrecognized by an endpoint 1420 is handled: 1422 o Upon reception, unrecognized options of class "elective" MUST be 1423 silently ignored. 1425 o Unrecognized options of class "critical" that occur in a 1426 confirmable request MUST cause the return of a 4.02 (Bad Option) 1427 response. This response SHOULD include a diagnostic message 1428 describing the unrecognized option(s) (see Section 5.5.2). 1430 o Unrecognized options of class "critical" that occur in a 1431 confirmable response SHOULD cause the response to be rejected with 1432 a reset message. 1434 o Unrecognized options of class "critical" that occur in a non- 1435 confirmable message MUST cause the message to be silently ignored. 1436 The response MAY be rejected with a reset message. 1438 Note that, whether critical or elective, an option is never 1439 "mandatory" (it is always optional): These rules are defined in order 1440 to enable implementations to reject options they do not understand or 1441 implement. 1443 5.4.2. Length 1445 Option values are defined to have a specific length, often in the 1446 form of an upper and lower bound. If the length of an option value 1447 in a request is outside the defined range, that option MUST be 1448 treated like an unrecognized option (see Section 5.4.1). 1450 5.4.3. Default Values 1452 Options may be defined to have a default value. If the value of 1453 option is intended to be this default value, the option SHOULD NOT be 1454 included in the message. If the option is not present, the default 1455 value MUST be assumed. 1457 Where a critical option has a default value, this is chosen in such a 1458 way that the absence of the option in a message can be processed 1459 properly both by implementations unaware of the critical option and 1460 by implementations that interpret this absence as the presence of the 1461 default value for the option. 1463 5.4.4. Repeatable Options 1465 The definition of an option MAY specify the option to be repeatable. 1466 An option that is repeatable MAY be included one or more times in a 1467 message. An option that is not repeatable MUST NOT be included more 1468 than once in a message. 1470 If a message includes an option with more occurrences than the option 1471 is defined for, the additional option occurrences MUST be treated 1472 like an unrecognized option (see Section 5.4.1). 1474 5.4.5. Option Numbers 1476 Options are identified by an option number. Odd numbers indicate a 1477 critical option, while even numbers indicate an elective option. 1478 (Note that this is not just a convention, it is a feature of the 1479 protocol: Whether an option is elective or critical is entirely 1480 determined by whether its option number is even or odd.) 1482 The numbers that are non-zero multiples of 14 are used in conjunction 1483 with "fenceposting", as described in Section 3.2. Options with these 1484 numbers MUST have a zero-length default value. 1486 The option numbers for the options defined in this document are 1487 listed in the CoAP Option Number Registry (Section 12.2). 1489 5.5. Payload 1491 Both requests and responses may include payload, depending on the 1492 method or response code respectively. If a method or response code 1493 is not defined to have a payload, then a sender MUST NOT include one, 1494 and a recipient MUST ignore it. 1496 5.5.1. Representation 1498 The payload of requests or of responses indicating success is 1499 typically a representation of a resource or the result of the 1500 requested action. Its format is specified by the Internet media type 1501 given by the Content-Type Option. In the absence of this option, no 1502 default value is assumed and the format must be inferred by the 1503 application (e.g., from the application context or by "sniffing" the 1504 payload). 1506 5.5.2. Diagnostic Message 1508 The payload of responses indicating a client or server error is a 1509 brief human-readable diagnostic message, explaining the error 1510 situation. This diagnostic message MUST be encoded using UTF-8 1512 [RFC3629], more specifically using Net-Unicode form [RFC5198]. The 1513 Content-Type Option MUST NOT be included by the sender and MUST be 1514 treated like an unrecognized option by the recipient. 1516 The message is similar to the Reason-Phrase on an HTTP status line. 1517 It is not intended for end-users but for software engineers that 1518 during debugging need to interpret it in the context of the present, 1519 English-language specification; therefore no mechanism for language 1520 tagging is needed or provided. 1522 5.6. Caching 1524 CoAP endpoints MAY cache responses in order to reduce the response 1525 time and network bandwidth consumption on future, equivalent 1526 requests. 1528 The goal of caching in CoAP is to reuse a prior response message to 1529 satisfy a current request. In some cases, a stored response can be 1530 reused without the need for a network request, reducing latency and 1531 network round-trips; a "freshness" mechanism is used for this purpose 1532 (see Section 5.6.1). Even when a new request is required, it is 1533 often possible to reuse the payload of a prior response to satisfy 1534 the request, thereby reducing network bandwidth usage; a "validation" 1535 mechanism is used for this purpose (see Section 5.6.2). 1537 Unlike HTTP, the cacheability of CoAP responses does not depend on 1538 the request method, but the Response Code. The cacheability of each 1539 Response Code is defined along the Response Code definitions in 1540 Section 5.9. Response Codes that indicate success and are 1541 unrecognized by an endpoint MUST NOT be cached. 1543 For a presented request, a CoAP endpoint MUST NOT use a stored 1544 response, unless: 1546 o the presented request method and that used to obtain the stored 1547 response match, 1549 o all options match between those in the presented request and those 1550 of the request used to obtain the stored response (which includes 1551 the request URI), except that there is no need for a match of the 1552 Token, Max-Age, or ETag request option(s), and 1554 o the stored response is either fresh or successfully validated as 1555 defined below. 1557 5.6.1. Freshness Model 1559 When a response is "fresh" in the cache, it can be used to satisfy 1560 subsequent requests without contacting the origin server, thereby 1561 improving efficiency. 1563 The mechanism for determining freshness is for an origin server to 1564 provide an explicit expiration time in the future, using the Max-Age 1565 Option (see Section 5.10.6). The Max-Age Option indicates that the 1566 response is to be considered not fresh after its age is greater than 1567 the specified number of seconds. 1569 The Max-Age Option defaults to a value of 60. Thus, if it is not 1570 present in a cacheable response, then the response is considered not 1571 fresh after its age is greater than 60 seconds. If an origin server 1572 wishes to prevent caching, it MUST explicitly include a Max-Age 1573 Option with a value of zero seconds. 1575 5.6.2. Validation Model 1577 When an endpoint has one or more stored responses for a GET request, 1578 but cannot use any of them (e.g., because they are not fresh), it can 1579 use the ETag Option (Section 5.10.7) in the GET request to give the 1580 origin server an opportunity to both select a stored response to be 1581 used, and to update its freshness. This process is known as 1582 "validating" or "revalidating" the stored response. 1584 When sending such a request, the endpoint SHOULD add an ETag Option 1585 specifying the entity-tag of each stored response that is applicable. 1587 A 2.03 (Valid) response indicates the stored response identified by 1588 the entity-tag given in the response's ETag Option can be reused, 1589 after updating its freshness with the value of the Max-Age Option 1590 that is included with the response (see Section 5.9.1.3). 1592 Any other response code indicates that none of the stored responses 1593 nominated in the request is suitable. Instead, the response SHOULD 1594 be used to satisfy the request and MAY replace the stored response. 1596 5.7. Proxying 1598 CoAP distinguishes between requests to an origin server and a request 1599 made through a proxy. A proxy is a CoAP endpoint that can be tasked 1600 by CoAP clients to perform requests on their behalf. This may be 1601 useful, for example, when the request could otherwise not be made, or 1602 to service the response from a cache in order to reduce response time 1603 and network bandwidth or energy consumption. 1605 CoAP requests to a proxy are made as normal confirmable or non- 1606 confirmable requests to the proxy endpoint, but specify the request 1607 URI in a different way: The request URI in a proxy request is 1608 specified as a string in the Proxy-Uri Option (see Section 5.10.3), 1609 while the request URI in a request to an origin server is split into 1610 the Uri-Host, Uri-Port, Uri-Path and Uri-Query Options (see 1611 Section 5.10.2). 1613 When a proxy request is made to an endpoint and the endpoint is 1614 unwilling or unable to act as proxy for the request URI, it MUST 1615 return a 5.05 (Proxying Not Supported) response. If the authority 1616 (host and port) is recognized as identifying the proxy endpoint, then 1617 the request MUST be treated as a local request. 1619 Unless a proxy is configured to forward the proxy request to another 1620 proxy, it MUST translate the request as follows: The origin server's 1621 IP address and port are determined by the authority component of the 1622 request URI, and the request URI is decoded and split into the Uri- 1623 Host, Uri-Port, Uri-Path and Uri-Query Options. 1625 All options present in a proxy request MUST be processed at the 1626 proxy. Critical options in a request that are not recognized by the 1627 proxy MUST lead to a 4.02 (Bad Option) response being returned by the 1628 proxy. Elective options not recognized by the proxy MUST NOT be 1629 forwarded to the origin server. Similarly, critical options in a 1630 response that are not recognized by the proxy server MUST lead to a 1631 5.02 (Bad Gateway) response. Again, elective options that are not 1632 recognized MUST NOT be forwarded. 1634 If the proxy does not employ a cache, then it simply forwards the 1635 translated request to the determined destination. Otherwise, if it 1636 does employ a cache but does not have a stored response that matches 1637 the translated request and is considered fresh, then it needs to 1638 refresh its cache according to Section 5.6. 1640 If the request to the destination times out, then a 5.04 (Gateway 1641 Timeout) response MUST be returned. If the request to the 1642 destination returns an response that cannot be processed by the 1643 proxy, then a 5.02 (Bad Gateway) response MUST be returned. 1644 Otherwise, the proxy returns the response to the client. 1646 If a response is generated out of a cache, it MUST be generated with 1647 a Max-Age Option that does not extend the max-age originally set by 1648 the server, considering the time the resource representation spent in 1649 the cache. E.g., the Max-Age Option could be adjusted by the proxy 1650 for each response using the formula: proxy-max-age = original-max-age 1651 - cache-age. For example if a request is made to a proxied resource 1652 that was refreshed 20 seconds ago and had an original Max-Age of 60 1653 seconds, then that resource's proxied max-age is now 40 seconds. 1655 5.8. Method Definitions 1657 In this section each method is defined along with its behavior. A 1658 request with an unrecognized or unsupported Method Code MUST generate 1659 a 4.05 (Method Not Allowed) response. 1661 5.8.1. GET 1663 The GET method retrieves a representation for the information that 1664 currently corresponds to the resource identified by the request URI. 1665 If the request includes one or more Accept Options, they indicate the 1666 preferred content-type of a response. If the request includes an 1667 ETag Option, the GET method requests that ETag be validated and that 1668 the representation be transferred only if validation failed. Upon 1669 success a 2.05 (Content) or 2.03 (Valid) response SHOULD be sent. 1671 The GET method is safe and idempotent. 1673 5.8.2. POST 1675 The POST method requests that the representation enclosed in the 1676 request be processed. The actual function performed by the POST 1677 method is determined by the origin server and dependent on the target 1678 resource. It usually results in a new resource being created or the 1679 target resource being updated. 1681 If a resource has been created on the server, the response returned 1682 by the server SHOULD have a 2.01 (Created) response code and SHOULD 1683 include the URI of the new resource in a sequence of one or more 1684 Location-Path and/or Location-Query Options (Section 5.10.8). If the 1685 POST succeeds but does not result in a new resource being created on 1686 the server, the response SHOULD have a 2.04 (Changed) response code. 1687 If the POST succeeds and results in the target resource being 1688 deleted, the response SHOULD have a 2.02 (Deleted) response code. 1690 POST is neither safe nor idempotent. 1692 5.8.3. PUT 1694 The PUT method requests that the resource identified by the request 1695 URI be updated or created with the enclosed representation. The 1696 representation format is specified by the media type given in the 1697 Content-Type Option. 1699 If a resource exists at the request URI the enclosed representation 1700 SHOULD be considered a modified version of that resource, and a 2.04 1701 (Changed) response SHOULD be returned. If no resource exists then 1702 the server MAY create a new resource with that URI, resulting in a 1703 2.01 (Created) response. If the resource could not be created or 1704 modified, then an appropriate error response code SHOULD be sent. 1706 Further restrictions to a PUT can be made by including the If-Match 1707 (see Section 5.10.9) or If-None-Match (see Section 5.10.10) options 1708 in the request. 1710 PUT is not safe, but is idempotent. 1712 5.8.4. DELETE 1714 The DELETE method requests that the resource identified by the 1715 request URI be deleted. A 2.02 (Deleted) response SHOULD be sent on 1716 success or in case the resource did not exist before the request. 1718 DELETE is not safe, but is idempotent. 1720 5.9. Response Code Definitions 1722 Each response code is described below, including any options required 1723 in the response. Where appropriate, some of the codes will be 1724 specified in regards to related response codes in HTTP [RFC2616]; 1725 this does not mean that any such relationship modifies the HTTP 1726 mapping specified in Section 10. 1728 5.9.1. Success 2.xx 1730 This class of status code indicates that the clients request was 1731 successfully received, understood, and accepted. 1733 5.9.1.1. 2.01 Created 1735 Like HTTP 201 "Created", but only used in response to POST and PUT 1736 requests. The payload returned with the response, if any, is a 1737 representation of the action result. 1739 If the response includes one or more Location-Path and/or Location- 1740 Query Options, the values of these options specify the location at 1741 which the resource was created. Otherwise, the resource was created 1742 at the request URI. A cache MUST mark any stored response for the 1743 created resource as not fresh. 1745 This response is not cacheable. 1747 5.9.1.2. 2.02 Deleted 1749 Like HTTP 204 "No Content", but only used in response to DELETE 1750 requests. The payload returned with the response, if any, is a 1751 representation of the action result. 1753 This response is not cacheable. However, a cache SHOULD mark any 1754 stored response for the deleted resource as not fresh. 1756 5.9.1.3. 2.03 Valid 1758 Related to HTTP 304 "Not Modified", but only used to indicate that 1759 the response identified by the entity-tag identified by the included 1760 ETag Option is valid. Accordingly, the response MUST include an ETag 1761 Option. 1763 When a cache receives a 2.03 (Valid) response, it MUST update the 1764 stored response with the value of the Max-Age Option included in the 1765 response (see Section 5.6.2). 1767 5.9.1.4. 2.04 Changed 1769 Like HTTP 204 "No Content", but only used in response to POST and PUT 1770 requests. The payload returned with the response, if any, is a 1771 representation of the action result. 1773 This response is not cacheable. However, a cache MUST mark any 1774 stored response for the changed resource as not fresh. 1776 5.9.1.5. 2.05 Content 1778 Like HTTP 200 "OK", but only used in response to GET requests. 1780 The payload returned with the response is a representation of the 1781 target resource. 1783 This response is cacheable: Caches can use the Max-Age Option to 1784 determine freshness (see Section 5.6.1) and (if present) the ETag 1785 Option for validation (see Section 5.6.2). 1787 5.9.2. Client Error 4.xx 1789 This class of response code is intended for cases in which the client 1790 seems to have erred. These response codes are applicable to any 1791 request method. 1793 The server SHOULD include a diagnostic message as detailed in 1794 Section 5.5.2. 1796 Responses of this class are cacheable: Caches can use the Max-Age 1797 Option to determine freshness (see Section 5.6.1). They cannot be 1798 validated. 1800 5.9.2.1. 4.00 Bad Request 1802 Like HTTP 400 "Bad Request". 1804 5.9.2.2. 4.01 Unauthorized 1806 The client is not authorized to perform the requested action. The 1807 client SHOULD NOT repeat the request without previously improving its 1808 authentication status to the server. Which specific mechanism can be 1809 used for this is outside this document's scope; see also Section 9. 1811 5.9.2.3. 4.02 Bad Option 1813 The request could not be understood by the server due to one or more 1814 unrecognized or malformed critical options. The client SHOULD NOT 1815 repeat the request without modification. 1817 5.9.2.4. 4.03 Forbidden 1819 Like HTTP 403 "Forbidden". 1821 5.9.2.5. 4.04 Not Found 1823 Like HTTP 404 "Not Found". 1825 5.9.2.6. 4.05 Method Not Allowed 1827 Like HTTP 405 "Method Not Allowed", but with no parallel to the 1828 "Allow" header field. 1830 5.9.2.7. 4.06 Not Acceptable 1832 Like HTTP 406 "Not Acceptable", but with no response entity. 1834 5.9.2.8. 4.12 Precondition Failed 1836 Like HTTP 412 "Precondition Failed". 1838 5.9.2.9. 4.13 Request Entity Too Large 1840 Like HTTP 413 "Request Entity Too Large". 1842 5.9.2.10. 4.15 Unsupported Media Type 1844 Like HTTP 415 "Unsupported Media Type". 1846 5.9.3. Server Error 5.xx 1848 This class of response code indicates cases in which the server is 1849 aware that it has erred or is incapable of performing the request. 1850 These response codes are applicable to any request method. 1852 The server SHOULD include a diagnostic message as detailed in 1853 Section 5.5.2. 1855 Responses of this class are cacheable: Caches can use the Max-Age 1856 Option to determine freshness (see Section 5.6.1). They cannot be 1857 validated. 1859 5.9.3.1. 5.00 Internal Server Error 1861 Like HTTP 500 "Internal Server Error". 1863 5.9.3.2. 5.01 Not Implemented 1865 Like HTTP 501 "Not Implemented". 1867 5.9.3.3. 5.02 Bad Gateway 1869 Like HTTP 502 "Bad Gateway". 1871 5.9.3.4. 5.03 Service Unavailable 1873 Like HTTP 503 "Service Unavailable", but using the Max-Age Option in 1874 place of the "Retry-After" header field. 1876 5.9.3.5. 5.04 Gateway Timeout 1878 Like HTTP 504 "Gateway Timeout". 1880 5.9.3.6. 5.05 Proxying Not Supported 1882 The server is unable or unwilling to act as a proxy for the URI 1883 specified in the Proxy-Uri Option (see Section 5.10.3). 1885 5.10. Option Definitions 1887 The individual CoAP options are summarized in Table 1 and explained 1888 below. 1890 +-----+---+---+----------------+--------+---------+-------------+ 1891 | No. | C | R | Name | Format | Length | Default | 1892 +-----+---+---+----------------+--------+---------+-------------+ 1893 | 1 | x | | Content-Type | uint | 0-2 B | (none) | 1894 | 2 | | | Max-Age | uint | 0-4 B | 60 | 1895 | 3 | x | x | Proxy-Uri | string | 1-270 B | (none) | 1896 | 4 | | x | ETag | opaque | 1-8 B | (none) | 1897 | 5 | x | | Uri-Host | string | 1-270 B | (see below) | 1898 | 6 | | x | Location-Path | string | 0-270 B | (none) | 1899 | 7 | x | | Uri-Port | uint | 0-2 B | (see below) | 1900 | 8 | | x | Location-Query | string | 0-270 B | (none) | 1901 | 9 | x | x | Uri-Path | string | 0-270 B | (none) | 1902 | 11 | x | | Token | opaque | 1-8 B | (empty) | 1903 | 12 | | x | Accept | uint | 0-2 B | (none) | 1904 | 13 | x | x | If-Match | opaque | 0-8 B | (none) | 1905 | 15 | x | x | Uri-Query | string | 0-270 B | (none) | 1906 | 21 | x | | If-None-Match | empty | 0 B | (none) | 1907 +-----+---+---+----------------+--------+---------+-------------+ 1909 C=Critical, R=Repeatable 1911 Table 1: Options 1913 5.10.1. Token 1915 The Token Option is used to match a response with a request. Every 1916 request has a client-generated token which the server MUST echo in 1917 any response. A default value of a zero-length token is assumed in 1918 the absence of the option. Thus when the token value is empty, the 1919 Token Option SHOULD be elided for efficiency. 1921 A token is intended for use as a client-local identifier for 1922 differentiating between concurrent requests (see Section 5.3). A 1923 client SHOULD generate tokens in a way that tokens currently in use 1924 for a given source/destination pair are unique. An empty token value 1925 is appropriate e.g. when no other tokens are in use to a destination, 1926 or when requests are made serially per destination. There are 1927 however multiple possible implementation strategies to fulfill this. 1928 An endpoint receiving a token MUST treat it as opaque and make no 1929 assumptions about its format. 1931 5.10.2. Uri-Host, Uri-Port, Uri-Path and Uri-Query 1933 The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to 1934 specify the target resource of a request to a CoAP origin server. 1935 The options encode the different components of the request URI in a 1936 way that no percent-encoding is visible in the option values and that 1937 the full URI can be reconstructed at any involved endpoint. The 1938 syntax of CoAP URIs is defined in Section 6. 1940 The steps for parsing URIs into options is defined in Section 6.4. 1941 These steps result in zero or more Uri-Host, Uri-Port, Uri-Path and 1942 Uri-Query Options being included in a request, where each option 1943 holds the following values: 1945 o the Uri-Host Option specifies the Internet host of the resource 1946 being requested, 1948 o the Uri-Port Option specifies the transport layer port number of 1949 the resource, 1951 o each Uri-Path Option specifies one segment of the absolute path to 1952 the resource, and 1954 o each Uri-Query Option specifies one argument parameterizing the 1955 resource. 1957 Note: Fragments ([RFC3986], Section 3.5) are not part of the request 1958 URI and thus will not be transmitted in a CoAP request. 1960 The default value of the Uri-Host Option is the IP literal 1961 representing the destination IP address of the request message. 1962 Likewise, the default value of the Uri-Port Option is the destination 1963 UDP port. The default values for the Uri-Host and Uri-Port Options 1964 are sufficient for requests to most servers. Explicit Uri-Host and 1965 Uri-Port Options are typically used when an endpoint hosts multiple 1966 virtual servers. 1968 The Uri-Path and Uri-Query Option can contain any character sequence. 1969 No percent-encoding is performed. The value of a Uri-Path Option 1970 MUST NOT be "." or ".." (as the request URI must be resolved before 1971 parsing it into options). 1973 The steps for constructing the request URI from the options are 1974 defined in Section 6.5. Note that an implementation does not 1975 necessarily have to construct the URI; it can simply look up the 1976 target resource by looking at the individual options. 1978 Examples can be found in Appendix B. 1980 5.10.3. Proxy-Uri 1982 The Proxy-Uri Option is used to make a request to a proxy (see 1983 Section 5.7). The proxy is requested to forward the request or 1984 service it from a valid cache, and return the response. 1986 The option value is an absolute-URI ([RFC3986], Section 4.3). In 1987 case the absolute-URI doesn't fit within a single option, the Proxy- 1988 Uri Option MAY be included multiple times in a request such that the 1989 concatenation of the values results in the single absolute-URI. 1991 All but the last instance of the Proxy-Uri Option MUST have a value 1992 with a length of 270 bytes, and the last instance MUST NOT be empty. 1994 Note that the proxy MAY forward the request on to another proxy or 1995 directly to the server specified by the absolute-URI. In order to 1996 avoid request loops, a proxy MUST be able to recognize all of its 1997 server names, including any aliases, local variations, and the 1998 numeric IP addresses. 2000 An endpoint receiving a request with a Proxy-Uri Option that is 2001 unable or unwilling to act as a proxy for the request MUST cause the 2002 return of a 5.05 (Proxying Not Supported) response. 2004 The Proxy-Uri Option MUST take precedence over any of the Uri-Host, 2005 Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included 2006 at the same time). 2008 5.10.4. Content-Type 2010 The Content-Type Option indicates the representation format of the 2011 message payload. The representation format is given as a numeric 2012 media type identifier that is defined in the CoAP Media Type registry 2013 (Section 12.3). No default value is assumed in the absence of the 2014 option. 2016 5.10.5. Accept 2018 The CoAP Accept option indicates when included one or more times in a 2019 request, one or more media types, each of which is an acceptable 2020 media type for the client, in the order of preference (most preferred 2021 first). The representation format is given as a numeric media type 2022 identifier that is defined in the CoAP Media Type registry 2023 (Section 12.3). If no Accept options are given, the client does not 2024 express a preference (thus no default value is assumed). The client 2025 prefers the representation returned by the server to be in one of the 2026 media types indicated. The server SHOULD return one of the preferred 2027 media types if available. If none of the preferred media types can 2028 be returned, then a 4.06 "Not Acceptable" SHOULD be sent as a 2029 response. 2031 Note that as a server might not support the Accept option (and thus 2032 would ignore it as it is elective), the client needs to be prepared 2033 to receive a representation in a different media type. The client 2034 can simply discard a representation it can not make use of. 2036 5.10.6. Max-Age 2038 The Max-Age Option indicates the maximum time a response may be 2039 cached before it MUST be considered not fresh (see Section 5.6.1). 2041 The option value is an integer number of seconds between 0 and 2^32-1 2042 inclusive (about 136.1 years). A default value of 60 seconds is 2043 assumed in the absence of the option in a response. 2045 5.10.7. ETag 2047 The ETag Option in a response provides the current value of the 2048 entity-tag for the enclosed representation of the target resource. 2050 An entity-tag is intended for use as a resource-local identifier for 2051 differentiating between representations of the same resource that 2052 vary over time. It may be generated in any number of ways including 2053 a version, checksum, hash or time. An endpoint receiving an entity- 2054 tag MUST treat it as opaque and make no assumptions about its format. 2055 (Endpoints generating an entity-tag are encouraged to use the most 2056 compact representation possible, in particular in regards to clients 2057 and intermediaries that may want to store multiple ETag values.) 2059 An endpoint that has one or more representations previously obtained 2060 from the resource can specify the ETag Option in a request for each 2061 stored response to determine if any of those representations is 2062 current (see Section 5.6.2). 2064 The ETag Option MUST NOT occur more than once in a response, and MAY 2065 occur one or more times in a request. 2067 5.10.8. Location-Path and Location-Query 2069 The Location-Path and Location-Query Options together indicate a 2070 relative URI that consists either of an absolute path, a query string 2071 or both. A combination of these options is included in a 2.01 2072 (Created) response to indicate the location of the a resource created 2073 as the result of a POST request (see Section 5.8.2). The location is 2074 resolved relative to the request URI. 2076 If a response with one or more Location-Path and/or Location-Query 2077 Options passes through a cache and the implied URI identifies one or 2078 more currently stored responses, those entries SHOULD be marked as 2079 not fresh. 2081 Each Location-Path Option specifies one segment of the absolute path 2082 to the resource, and each Uri-Location Option specifies one argument 2083 parameterizing the resource. The Location-Path and Location-Query 2084 Option can contain any character sequence. No percent-encoding is 2085 performed. The value of a Location-Path Option MUST NOT be "." or 2086 "..". 2088 The steps for constructing the location URI from the options are 2089 analogous to Section 6.5, except that the first five steps are 2090 skipped and the result is a relative URI-reference. 2092 More Location-* options may be defined in the future, and have been 2093 reserved option numbers 44, 46 and 48. If any of these reserved 2094 option numbers occurs in addition to Location-Path and/or Location- 2095 Query and are not supported, then a 4.02 (Bad Option) error MUST be 2096 returned. 2098 5.10.9. If-Match 2100 The If-Match Option MAY be used to make a request conditional on the 2101 current existence or value of an ETag for one or more representations 2102 of the target resource. If-Match is generally useful for resource 2103 update requests, such as PUT requests, as a means for protecting 2104 against accidental overwrites when multiple clients are acting in 2105 parallel on the same resource (i.e., the "lost update" problem). 2107 The value of an If-Match option is either an ETag or the empty 2108 string. An empty string places the precondition on the existence of 2109 any current representation for the target resource. 2111 The If-Match Option can occur multiple times. If any of the ETags 2112 given as an option value match the ETag of the current representation 2113 for the target resource, or if an If-Match Option with an empty 2114 string as option value is given and any current representation exists 2115 for the target resource, then the server MAY perform the request 2116 method as if the If-Match Option was not present. 2118 If none of the ETags match and, if an empty string is given, no 2119 current representation exists at all, the server MUST NOT perform the 2120 requested method. Instead, the server MUST respond with the 4.12 2121 (Precondition Failed) response code. 2123 If the request would, without the If-Match Options, result in 2124 anything other than a 2.xx or 4.12 response code, then any If-Match 2125 Options MUST be ignored. 2127 5.10.10. If-None-Match 2129 The If-None-Match Option MAY be used to make a request conditional on 2130 the non-existence of the target resource. If-None-Match is useful 2131 for resource creation requests, such as PUT requests, as a means for 2132 protecting against accidental overwrites when multiple clients are 2133 acting in parallel on the same resource. The If-None-Match Option 2134 carries no value. 2136 If the target resource does exist, then the server MUST NOT perform 2137 the requested method. Instead, the server MUST respond with the 4.12 2138 (Precondition Failed) response code. 2140 6. CoAP URIs 2142 CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP 2143 resources and providing a means of locating the resource. Resources 2144 are organized hierarchically and governed by a potential CoAP origin 2145 server listening for CoAP requests ("coap") or DTLS-secured CoAP 2146 requests ("coaps") on a given UDP port. The CoAP server is 2147 identified via the generic syntax's authority component, which 2148 includes a host identifier and optional UDP port number. The 2149 remainder of the URI is considered to be identifying a resource which 2150 can be operated on by the methods defined by the CoAP protocol. The 2151 "coap" and "coaps" URI schemes can thus be compared to the "http" and 2152 "https" URI schemes respectively. 2154 The syntax of the "coap" and "coaps" URI schemes is specified below 2155 in Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 2156 "host", "port", "path-abempty", "query", "segment", "IP-literal", 2157 "IPv4address" and "reg-name" are adopted from [RFC3986]. 2159 6.1. coap URI Scheme 2161 coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] 2163 If host is provided as an IP-literal or IPv4address, then the CoAP 2164 server can be reached at that IP address. If host is a registered 2165 name, then that name is considered an indirect identifier and the 2166 endpoint might use a name resolution service, such as DNS, to find 2167 the address of that host. The host MUST NOT be empty. The port 2168 subcomponent indicates the UDP port at which the CoAP server is 2169 located. If it is empty or not given, then the default port 5683 is 2170 assumed. 2172 The path identifies a resource within the scope of the host and port. 2173 It consists of a sequence of path segments separated by a slash 2174 character (U+002F SOLIDUS "/"). 2176 The query serves to further parameterize the resource. It consists 2177 of a sequence of arguments separated by an ampersand character 2178 (U+0026 AMPERSAND "&"). An argument is often in the form of a 2179 "key=value" pair. 2181 The "coap" URI scheme supports the path prefix "/.well-known/" 2182 defined by [RFC5785] for "well-known locations" in the name-space of 2183 a host. This enables discovery of policy or other information about 2184 a host ("site-wide metadata"), such as hosted resources (see 2185 Section 7). 2187 Application designers are encouraged to make use of short, but 2188 descriptive URIs. As the environments that CoAP is used in are 2189 usually constrained for bandwidth and energy, the trade-off between 2190 these two qualities should lean towards the shortness, without 2191 ignoring descriptiveness. 2193 6.2. coaps URI Scheme 2195 coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty 2196 [ "?" query ] 2198 All of the requirements listed above for the "coap" scheme are also 2199 requirements for the "coaps" scheme, except that a default UDP port 2200 of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or 2201 not given, and the UDP datagrams MUST be secured for privacy through 2202 the use of DTLS as described in Section 9.1. 2204 Unlike the "coap" scheme, responses to "coaps" identified requests 2205 are never "public" and thus MUST NOT be reused for shared caching. 2206 They can, however, be reused in a private cache if the message is 2207 cacheable by default in CoAP. 2209 Resources made available via the "coaps" scheme have no shared 2210 identity with the "coap" scheme even if their resource identifiers 2211 indicate the same authority (the same host listening to the same UDP 2212 port). They are distinct name spaces and are considered to be 2213 distinct origin servers. 2215 6.3. Normalization and Comparison Rules 2217 Since the "coap" and "coaps" schemes conform to the URI generic 2218 syntax, such URIs are normalized and compared according to the 2219 algorithm defined in [RFC3986], Section 6, using the defaults 2220 described above for each scheme. 2222 If the port is equal to the default port for a scheme, the normal 2223 form is to elide the port subcomponent. Likewise, an empty path 2224 component is equivalent to an absolute path of "/", so the normal 2225 form is to provide a path of "/" instead. The scheme and host are 2226 case-insensitive and normally provided in lowercase; IP-literals are 2227 in recommended form [RFC5952]; all other components are compared in a 2228 case-sensitive manner. Characters other than those in the "reserved" 2229 set are equivalent to their percent-encoded octets (see [RFC3986], 2230 Section 2.1): the normal form is to not encode them. 2232 For example, the following three URIs are equivalent, and cause the 2233 same options and option values to appear in the CoAP messages: 2235 coap://example.com:5683/~sensors/temp.xml 2236 coap://EXAMPLE.com/%7Esensors/temp.xml 2237 coap://EXAMPLE.com:/%7esensors/temp.xml 2239 6.4. Decomposing URIs into Options 2241 The steps to parse a request's options from a string /url/ are as 2242 follows. These steps either result in zero or more of the Uri-Host, 2243 Uri-Port, Uri-Path and Uri-Query Options being included in the 2244 request, or they fail. 2246 1. If the /url/ string is not an absolute URI ([RFC3986]), then fail 2247 this algorithm. 2249 2. Resolve the /url/ string using the process of reference 2250 resolution defined by [RFC3986], with the URL character encoding 2251 set to UTF-8 [RFC3629]. 2253 NOTE: It doesn't matter what it is resolved relative to, since we 2254 already know it is an absolute URL at this point. 2256 3. If /url/ does not have a component whose value, when 2257 converted to ASCII lowercase, is "coap" or "coaps", then fail 2258 this algorithm. 2260 4. If /url/ has a component, then fail this algorithm. 2262 5. If the component of /url/ does not represent the request's 2263 destination IP address as an IP-literal or IPv4address, include a 2264 Uri-Host Option and let that option's value be the value of the 2265 component of /url/, converted to ASCII lowercase, and then 2266 converting all percent-encodings ("%" followed by two hexadecimal 2267 digits) to the corresponding characters. 2269 NOTE: In the usual case where the request's destination IP 2270 address is derived from the host part, this ensures that Uri-Host 2271 Options are only used for host parts of the form reg-name. 2273 6. If /url/ has a component, then let /port/ be that 2274 component's value interpreted as a decimal integer; otherwise, 2275 let /port/ be the default port for the scheme. 2277 7. If /port/ does not equal the request's destination UDP port, 2278 include a Uri-Port Option and let that option's value be /port/. 2280 8. If the value of the component of /url/ is empty or 2281 consists of a single slash character (U+002F SOLIDUS "/"), then 2282 move to the next step. 2284 Otherwise, for each segment in the component, include a 2285 Uri-Path Option and let that option's value be the segment (not 2286 including the delimiting slash characters) after converting all 2287 percent-encodings ("%" followed by two hexadecimal digits) to the 2288 corresponding characters. 2290 9. If /url/ has a component, then, for each argument in the 2291 component, include a Uri-Query Option and let that 2292 option's value be the argument (not including the question mark 2293 and the delimiting ampersand characters) after converting all 2294 percent-encodings to the corresponding characters. 2296 Note that these rules completely resolve any percent-encoding. 2298 6.5. Composing URIs from Options 2300 The steps to construct a URI from a request's options are as follows. 2301 These steps either result in a URI, or they fail. In these steps, 2302 percent-encoding a character means replacing each of its (UTF-8 2303 encoded) bytes by a "%" character followed by two hexadecimal digits 2304 representing the byte, where the digits A-F are in upper case (as 2305 defined in [RFC3986] Section 2.1; to reduce variability, the 2306 hexadecimal notation for percent-encoding in CoAP URIs MUST use 2307 uppercase letters). The definitions of "unreserved" and "sub-delims" 2308 are adopted from [RFC3986]. 2310 1. If the request is secured using DTLS, let /url/ be the string 2311 "coaps://". Otherwise, let /url/ be the string "coap://". 2313 2. If the request includes a Uri-Host Option, let /host/ be that 2314 option's value, where any non-ASCII characters are replaced by 2315 their corresponding percent-encoding. If /host/ is not a valid 2316 reg-name or IP-literal or IPv4address, fail the algorithm. 2317 Otherwise, let /host/ be the IP-literal (making use of the 2318 conventions of [RFC5952]) or IPv4address representing the 2319 request's destination IP address. 2321 3. Append /host/ to /url/. 2323 4. If the request includes a Uri-Port Option, let /port/ be that 2324 option's value. Otherwise, let /port/ be the request's 2325 destination UDP port. 2327 5. If /port/ is not the default port for the scheme, then append a 2328 single U+003A COLON character (:) followed by the decimal 2329 representation of /port/ to /url/. 2331 6. Let /resource name/ be the empty string. For each Uri-Path 2332 Option in the request, append a single character U+002F SOLIDUS 2333 (/) followed by the option's value to /resource name/, after 2334 converting any character that is not either in the "unreserved" 2335 set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL 2336 AT (@) character, to its percent-encoded form. 2338 7. If /resource name/ is the empty string, set it to a single 2339 character U+002F SOLIDUS (/). 2341 8. For each Uri-Query Option in the request, append a single 2342 character U+003F QUESTION MARK (?) (first option) or U+0026 2343 AMPERSAND (&) (subsequent options) followed by the option's 2344 value to /resource name/, after converting any character that is 2345 not either in the "unreserved" set, "sub-delims" set (except 2346 U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT 2347 (@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, 2348 to its percent-encoded form. 2350 9. Append /resource name/ to /url/. 2352 10. Return /url/. 2354 Note that these steps have been designed to lead to a URI in normal 2355 form (see Section 6.3). 2357 7. Discovery 2359 7.1. Service Discovery 2361 A server is discovered by a client by the client knowing or learning 2362 a URI that references a resource in the namespace of the server. 2363 Alternatively, clients can use Multicast CoAP (see Section 8) and the 2364 "All CoAP Nodes" multicast address to find CoAP servers. 2366 Unless the port subcomponent in a "coap" or "coaps" URI indicates the 2367 UDP port at which the CoAP server is located, the server is assumed 2368 to be reachable at the default port. 2370 The CoAP default port number 5683 MUST be supported by a server for 2371 resource discovery (see Section 7.2 below) and SHOULD be supported 2372 for providing access to other resources. The default port number 2373 [IANA_TBD_PORT] for DTLS-secured CoAP MAY be supported by a server 2374 for resource discovery and for providing access to other resources. 2375 In addition other endpoints may be hosted in the dynamic port space. 2377 When a CoAP server is hosted by a 6LoWPAN node, it SHOULD also 2378 support a port number in the 61616-61631 compressed UDP port space 2379 defined in [RFC4944] (note that, as its UDP port differs from the 2380 default port, it is a different endpoint from the server at the 2381 default port). So if the default port number does not work and a 2382 client knows that the CoAP server is hosted by a 6LoWPAN node, the 2383 client MAY try to contact the CoAP server at a port number in the 2384 61616-61631 space. 2386 7.2. Resource Discovery 2388 The discovery of resources offered by a CoAP endpoint is extremely 2389 important in machine-to-machine applications where there are no 2390 humans in the loop and static interfaces result in fragility. A CoAP 2391 endpoint SHOULD support the CoRE Link Format of discoverable 2392 resources as described in [I-D.ietf-core-link-format]. It is up to 2393 the server which resources are made discoverable (if any). 2395 7.2.1. 'ct' Attribute 2397 This section defines a new Web Linking [RFC5988] attribute for use 2398 with [I-D.ietf-core-link-format]. The Content-type code "ct" 2399 attribute provides a hint about the Internet media type(s) this 2400 resource returns. Note that this is only a hint, and does not 2401 override the Content-type Option of a CoAP response obtained by 2402 actually following the link. The value is in the CoAP identifier 2403 code format as a decimal ASCII integer and MUST be in the range of 2404 0-65535 (16-bit unsigned integer). For example application/xml would 2405 be indicated as "ct=41". If no Content-type code attribute is 2406 present then nothing about the type can be assumed. The Content-type 2407 code attribute MAY appear more than once in a link, indicating that 2408 multiple content-types are available. 2410 link-extension = 2411 link-extension = ( "ct" "=" cardinal ) ; Range of 0-65535 2412 cardinal = "0" / %x31-39 *DIGIT 2414 8. Multicast CoAP 2416 CoAP supports making requests to a IP multicast group. This is 2417 defined by a series of deltas to Unicast CoAP. 2419 8.1. Messaging Layer 2421 A multicast request is characterized by being transported in a CoAP 2422 message that is addressed to an IP multicast address instead of a 2423 CoAP end-point. Such multicast requests MUST be Non-Confirmable. 2425 Some mechanisms for avoiding congestion from multicast requests have 2426 been considered in [I-D.eggert-core-congestion-control]. 2428 A server SHOULD be aware that a request arrived via multicast, e.g. 2429 by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 2430 available. 2432 When a server is aware that a request arrived via multicast, it MUST 2433 NOT return a RST in reply to NON. If it is not aware, it MAY return 2434 a RST in reply to NON as usual. 2436 8.2. Request/Response Layer 2438 When a server is aware that a request arrived via multicast, the 2439 server MAY always pretend it did not receive the request, in 2440 particular if it doesn't have anything useful to respond (e.g., if it 2441 only has an empty payload or an error response). The decision for 2442 this may depend on the application. (For example, in 2443 [I-D.ietf-core-link-format] query filtering, a server should not 2444 respond to a multicast request if the filter does not match.) 2446 If a server does decide to respond to a multicast request, it should 2447 not respond immediately. Instead, it should pick a duration for the 2448 period of time during which it intends to respond. For purposes of 2449 this exposition, we call the length of this period the Leisure. The 2450 specific value of this Leisure may depend on the application, or MAY 2451 be derived as described below. The server SHOULD then pick a random 2452 point of time within the chosen Leisure period to send back the 2453 unicast response to the multicast request. 2455 To compute a value for Leisure, the server should have a group size 2456 estimate G, a target rate R (which both should be chosen 2457 conservatively) and an estimated response size S; a rough lower bound 2458 for Leisure can then be computed as 2459 lb_Leisure = S * G / R 2461 E.g., for a multicast request with link-local scope on an 2.4 GHz 2462 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 2463 conservatively) set to 100, S to 100 bytes, and the target rate to a 2464 conservative 8 kbit/s = 1 kB/s. The resulting lower bound for the 2465 Leisure is 10 seconds. 2467 When matching a response to a multicast request, only the token MUST 2468 match; the source endpoint of the response does not need to (and will 2469 not) be the same as the destination endpoint of the original request. 2471 8.2.1. Caching 2473 When a client makes a multicast request, it always makes a new 2474 request to the multicast group (since there may be new group members 2475 that joined meanwhile or ones that did not get the previous request). 2476 It MAY update the cache with the received responses. Then it uses 2477 both cached-still-fresh and 'new' responses as the result of the 2478 request. 2480 A response received in reply to a GET request to a multicast group 2481 MAY be used to satisfy a subsequent request on the related unicast 2482 request URI. The unicast request URI is obtained by replacing the 2483 authority part of the request URI with the transport layer source 2484 address of the response message. 2486 A cache MAY revalidate a response by making a GET request on the 2487 related unicast request URI. 2489 A GET request to a multicast group MUST NOT contain an ETag option. 2490 A mechanism to suppress responses the client already has is left for 2491 further study. 2493 8.2.2. Proxying 2495 When a forward proxy receives a request with a Proxy-Uri that 2496 indicates a multicast address, the proxy obtains a set of responses 2497 as described above and sends all responses (both cached-still-fresh 2498 and new) back to the original client. 2500 9. Securing CoAP 2502 This section defines the DTLS binding for CoAP, and the alternative 2503 use of IPsec. 2505 During the provisioning phase, a CoAP device is provided with the 2506 security information that it needs, including keying materials and 2507 access control lists. This specification defines provisioning for 2508 the RawPublicKey mode in Section 9.1.3.2.1. At the end of the 2509 provisioning phase, the device will be in one of four security modes 2510 with the following information for the given mode. The NoSec and 2511 RawPublicKey modes are mandatory to implement for this specification. 2513 NoSec: There is no protocol level security (DTLS is disabled). 2514 Alternative techniques to provide lower layer security SHOULD be 2515 used when appropriate. The use of IPsec is discussed in 2516 Section 9.2. 2518 PreSharedKey: DTLS is enabled and there is a list of pre-shared keys 2519 [RFC4279] and each key includes a list of which nodes it can be 2520 used to communicate with as described in Section 9.1.3.1. At the 2521 extreme there may be one key for each node this CoAP node needs to 2522 communicate with (1:1 node/key ratio). 2524 RawPublicKey: DTLS is enabled and the device has a raw public key 2525 certificate that is validated using an out-of-band mechanism 2526 [I-D.ietf-tls-oob-pubkey] as described in Section 9.1.3.2. The 2527 device also has an identity calculated from the public key and a 2528 list of identities of the nodes it can communicate with. 2530 Certificate: DTLS is enabled and the device has an asymmetric key 2531 pair with an X.509 certificate [RFC5280] that binds it to its 2532 Authority Name and is signed by some common trust root as 2533 described in Section 9.1.3.3. The device also has a list of root 2534 trust anchors that can be used for validating a certificate. 2536 In the "NoSec" mode, the system simply sends the packets over normal 2537 UDP over IP and is indicated by the "coap" scheme and the CoAP 2538 default port. The system is secured only by keeping attackers from 2539 being able to send or receive packets from the network with the CoAP 2540 nodes; see Section 11.5 for an additional complication with this 2541 approach. 2543 The other three security modes are achieved using DTLS and are 2544 indicated by the "coaps" scheme and DTLS-secured CoAP default port. 2545 The result is a security association that can be used to authenticate 2546 (within the limits of the security model) and, based on this 2547 authentication, authorize the communication partner. CoAP itself 2548 does not provide protocol primitives for authentication or 2549 authorization; where this is required, it can either be provided by 2550 communication security (i.e., IPsec or DTLS) or by object security 2551 (within the payload). Devices that require authorization for certain 2552 operations are expected to require one of these two forms of 2553 security. Necessarily, where an intermediary is involved, 2554 communication security only works when that intermediary is part of 2555 the trust relationships; CoAP does not provide a way to forward 2556 different levels of authorization that clients may have with an 2557 intermediary to further intermediaries or origin servers -- it 2558 therefore may be required to perform all authorization at the first 2559 intermediary. 2561 9.1. DTLS-secured CoAP 2563 Just as HTTP is secured using Transport Layer Security (TLS) over 2564 TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP 2565 (see Figure 10). This section defines the CoAP binding to DTLS, 2566 along with the minimal mandatory-to-implement configurations 2567 appropriate for constrained environments. The binding is defined by 2568 a series of deltas to Unicast CoAP. DTLS is in practice TLS with 2569 added features to deal with the unreliable nature of the UDP 2570 transport. 2572 +----------------------+ 2573 | Application | 2574 +----------------------+ 2575 +----------------------+ 2576 | Requests/Responses | 2577 |----------------------| CoAP 2578 | Messages | 2579 +----------------------+ 2580 +----------------------+ 2581 | DTLS | 2582 +----------------------+ 2583 +----------------------+ 2584 | UDP | 2585 +----------------------+ 2587 Figure 10: Abstract layering of DTLS-secured CoAP 2589 In some constrained nodes (limited flash and/or RAM) and networks 2590 (limited bandwidth or high scalability requirements), and depending 2591 on the specific cipher suites in use, DTLS may not be applicable. 2592 Some of DTLS' cipher suites can add significant implementation 2593 complexity as well as some initial handshake overhead needed when 2594 setting up the security association. Once the initial handshake is 2595 completed, DTLS adds a limited per-datagram overhead of approximately 2596 13 bytes, not including any initialization vectors/nonces (e.g., 8 2597 bytes with TLS_PSK_WITH_AES_128_CCM_8 [I-D.mcgrew-tls-aes-ccm]), 2598 integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 2599 [I-D.mcgrew-tls-aes-ccm]) and padding required by the cipher suite. 2600 Whether and which mode of using DTLS is applicable for a CoAP-based 2601 application should be carefully weighed considering the specific 2602 cipher suites that may be applicable, and whether the session 2603 maintenance makes it compatible with application flows and sufficient 2604 resources are available on the constrained nodes and for the added 2605 network overhead. DTLS is not applicable to group keying (multicast 2606 communication); however, it may be a component in a future group key 2607 management protocol. 2609 9.1.1. Messaging Layer 2611 The endpoint acting as the CoAP client should also act as the DTLS 2612 client. It should initiate a session to the server on the 2613 appropriate port. When the DTLS handshake has finished, the client 2614 may initiate the first CoAP request. All CoAP messages MUST be sent 2615 as DTLS "application data". 2617 The following rules are added for matching an ACK or RST to a CON 2618 message or a RST to a NON message are as follows: The DTLS session 2619 MUST be the same and the epoch MUST be the same. 2621 A message is the same when it is sent within the same DTLS session 2622 and same epoch and has the same Message ID. 2624 Note: When a confirmable message is retransmitted, a new DTLS 2625 sequence_number is used for each attempt, even though the CoAP 2626 Message ID stays the same. So a recipient still has to perform 2627 deduplication as described in Section 4.5. Retransmissions MUST NOT 2628 be performed across epochs. 2630 DTLS connections in RawPublicKey and Certificate mode are set up 2631 using mutual authentication so they can remain up and be reused for 2632 future message exchanges in either direction. Devices can close a 2633 DTLS connection when they need to recover resources but in general 2634 they should keep the connection up for as long as possible. Closing 2635 the DTLS connection after every CoAP message exchange is very 2636 inefficient. 2638 9.1.2. Request/Response Layer 2640 The following rules are added for matching a response to a request: 2641 The DTLS session MUST be the same and the epoch MUST be the same. 2643 9.1.2.1. Caching 2645 The following rules are added for using a response that was obtained 2646 using DTLS-secured CoAP: For a presented request, a CoAP endpoint 2647 MUST NOT use a stored response, unless the identity is the same. 2649 9.1.2.2. Proxying 2651 Responses to "coaps" identified requests are never "public" and thus 2652 MUST NOT be reused for shared caching. They can, however, be reused 2653 in a private cache if the message is cacheable by default in CoAP. 2655 9.1.3. Endpoint Identity 2657 Devices SHOULD support the Server Name Indication (SNI) to indicate 2658 their Authority Name in the SNI HostName field as defined in Section 2659 3 of [RFC6066]. This is needed so that when a host that acts as a 2660 virtual server for multiple Authorities receives a new DTLS 2661 connection, it knows which keys to use for the DTLS session. 2663 9.1.3.1. Pre-Shared Keys 2665 When forming a connection to a new node, the system selects an 2666 appropriate key based on which nodes it is trying to reach and then 2667 forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. 2668 Implementations in these modes MUST support the mandatory to 2669 implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in 2670 [I-D.mcgrew-tls-aes-ccm]. 2672 The security considerations of [RFC4279] (Section 7) apply. In 2673 particular, applications should carefully weigh whether they need 2674 Perfect Forward Secrecy (PFS) or not and select an appropriate cipher 2675 suite (7.1). The entropy of the PSK must be sufficient to mitigate 2676 against brute-force and (where the PSK is not chosen randomly but by 2677 a human) dictionary attacks (7.2). The cleartext communication of 2678 client identities may leak data or compromise privacy (7.3). 2680 9.1.3.2. Raw Public Key Certificates 2682 In this mode the device has an asymmetric key pair but without an 2683 X.509 certificate (called a raw public key). A device MAY be 2684 configured with multiple raw public keys. The type and length of the 2685 raw public key depends on the cipher suite used. Implementations in 2686 RawPublicKey mode MUST support the mandatory to implement cipher 2687 suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in 2688 [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. The mechanism 2689 for using raw public keys with TLS is specified in 2690 [I-D.ietf-tls-oob-pubkey]. 2692 9.1.3.2.1. Provisioning 2694 The RawPublicKey mode was designed to be easily provisioned in M2M 2695 deployments. It is assumed that each device has an appropriate 2696 asymmetric public key pair installed. An identifier is calculated 2697 from the public key as described in Section 2 of 2698 [I-D.farrell-decade-ni]. All implementations that support checking 2699 RawPublicKey identities MUST support at least the sha-256-120 mode 2700 (SHA-256 truncated to 120 bits). Implementations SHOULD support also 2701 longer length identifiers and MAY support shorter lengths. Note that 2702 the shorter lengths provide less security against attacks and their 2703 use is NOT RECOMMENDED. 2705 Depending on how identifiers are given to the system that verifies 2706 them, support for URI, binary, and/or human-speakable format 2707 [I-D.farrell-decade-ni] needs to be implemented. All implementations 2708 SHOULD support the binary mode and implementations that have a user 2709 interface SHOULD also support the human-speakable format. 2711 During provisioning, the identifier of each node is collected, for 2712 example by reading a barcode on the outside of the device or by 2713 obtaining a pre-compiled list of the identifiers. These identifiers 2714 are then installed in the corresponding endpoint, for example an M2M 2715 data collection server. The identifier is used for two purposes, to 2716 associate the endpoint with further device information and to perform 2717 access control. During provisioning, an access control list of 2718 identifiers the device may start DTLS sessions with SHOULD also be 2719 installed. 2721 9.1.3.3. X.509 Certificates 2723 Implementations in Certificate Mode MUST support the mandatory to 2724 implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as 2725 specified in [RFC5246]. 2727 The Authority Name in the certificate is the name that would be used 2728 in the Authority part of a CoAP URI. It is worth noting that this 2729 would typically not be either an IP address or DNS name but would 2730 instead be a long term unique identifier for the device such as the 2731 EUI-64 [EUI64]. The discovery process used in the system would build 2732 up the mapping between IP addresses of the given devices and the 2733 Authority Name for each device. Some devices could have more than 2734 one Authority and would need more than a single certificate. 2736 When a new connection is formed, the certificate from the remote 2737 device needs to be verified. If the CoAP node has a source of 2738 absolute time, then the node SHOULD check the validity dates are of 2739 the certificate are within range. The certificate MUST also be 2740 signed by an appropriate chain of trust. If the certificate contains 2741 a SubjectAltName, then the Authority Name MUST match at least one of 2742 the authority names of any CoAP URI found in a URI type fields in the 2743 SubjectAltName set. If there is no SubjectAltName in the 2744 certificate, then the Authoritative Name must match the CN found in 2745 the certificate using the matching rules defined in [RFC2818] with 2746 the exception that certificates with wildcards are not allowed. 2748 If the system has a shared key in addition to the certificate, then a 2749 cipher suite that includes the shared key such as 2750 TLS_RSA_PSK_WITH_AES_128_CBC_SHA [RFC4279] SHOULD be used. 2752 9.2. Using CoAP with IPsec 2754 One mechanism to secure CoAP in constrained environments is the IPsec 2755 Encapsulating Security Payload (ESP) [RFC4303] when CoAP is used 2756 without DTLS in NoSec Mode. Using IPsec ESP with the appropriate 2757 configuration, it is possible for many constrained devices to support 2758 encryption with built-in link-layer encryption hardware. For 2759 example, some IEEE 802.15.4 radio chips are compatible with AES-CBC 2760 (with 128-bit keys) [RFC3602] as defined for use with IPsec in 2761 [RFC4835]. Alternatively, particularly on more common IEEE 802.15.4 2762 hardware that supports AES encryption but not decryption, and to 2763 avoid the need for padding, nodes could directly use the more widely 2764 supported AES-CCM as defined for use with IPsec in [RFC4309], if the 2765 security considerations in Section 9 of that specification can be 2766 fulfilled. 2768 Necessarily for AES-CCM, but much preferably also for AES-CBC, static 2769 keying should be avoided and the initial keying material be derived 2770 into transient session keys, e.g. using a low-overhead mode of IKEv2 2771 [RFC5996] as described in [I-D.kivinen-ipsecme-ikev2-minimal]; such a 2772 protocol for managing keys and sequence numbers is also the only way 2773 to achieve anti-replay capabilities. However, no recommendation can 2774 be made at this point on how to manage group keys (i.e., for 2775 multicast) in a constrained environment. Once any initial setup is 2776 completed, IPsec ESP adds a limited overhead of approximately 10 2777 bytes per packet, not including initialization vectors, integrity 2778 check values and padding required by the cipher suite. 2780 When using IPsec to secure CoAP, both authentication and 2781 confidentiality SHOULD be applied as recommended in [RFC4303]. The 2782 use of IPsec between CoAP endpoints is transparent to the application 2783 layer and does not require special consideration for a CoAP 2784 implementation. 2786 IPsec may not be appropriate for all environments. For example, 2787 IPsec support is not available for many embedded IP stacks and even 2788 in full PC operating systems or on back-end web servers, application 2789 developers may not have sufficient access to configure or enable 2790 IPsec or to add a security gateway to the infrastructure. Problems 2791 with firewalls and NATs may furthermore limit the use of IPsec. 2793 10. Cross-Protocol Proxying between CoAP and HTTP 2795 CoAP supports a limited subset of HTTP functionality, and thus cross- 2796 protocol proxying to HTTP is straightforward. There might be several 2797 reasons for proxying between CoAP and HTTP, for example when 2798 designing a web interface for use over either protocol or when 2799 realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied 2800 to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the 2801 definition of these mechanisms is out of scope of this specification. 2803 There are two possible directions to access a resource via a forward 2804 proxy: 2806 CoAP-HTTP Proxying: Enables CoAP clients to access resources on HTTP 2807 servers through an intermediary. This is initiated by including 2808 the Proxy-Uri Option with an "http" or "https" URI in a CoAP 2809 request to a CoAP-HTTP proxy. 2811 HTTP-CoAP Proxying: Enables HTTP clients to access resources on CoAP 2812 servers through an intermediary. This is initiated by specifying 2813 a "coap" or "coaps" URI in the Request-Line of an HTTP request to 2814 an HTTP-CoAP proxy. 2816 Either way, only the Request/Response model of CoAP is mapped to 2817 HTTP. The underlying model of confirmable or non-confirmable 2818 messages, etc., is invisible and MUST have no effect on a proxy 2819 function. The following sections describe the handling of requests 2820 to a forward proxy. Reverse proxies are not specified as the proxy 2821 function is transparent to the client with the proxy acting as if it 2822 was the origin server. 2824 10.1. CoAP-HTTP Mapping 2826 If a request contains a Proxy-URI Option with an 'http' or 'https' 2827 URI [RFC2616], then the receiving CoAP endpoint (called "the proxy" 2828 henceforth) is requested to perform the operation specified by the 2829 request method on the indicated HTTP resource and return the result 2830 to the client. 2832 This section specifies for any CoAP request the CoAP response that 2833 the proxy should return to the client. How the proxy actually 2834 satisfies the request is an implementation detail, although the 2835 typical case is expected to be the proxy translating and forwarding 2836 the request to an HTTP origin server. 2838 Since HTTP and CoAP share the basic set of request methods, 2839 performing a CoAP request on an HTTP resource is not so different 2840 from performing it on a CoAP resource. The meanings of the 2841 individual CoAP methods when performed on HTTP resources are 2842 explained below. 2844 If the proxy is unable or unwilling to service a request with an HTTP 2845 URI, a 5.05 (Proxying Not Supported) response SHOULD be returned to 2846 the client. If the proxy services the request by interacting with a 2847 third party (such as the HTTP origin server) and is unable to obtain 2848 a result within a reasonable time frame, a 5.04 (Gateway Timeout) 2849 response SHOULD be returned; if a result can be obtained but is not 2850 understood, a 5.02 (Bad Gateway) response SHOULD be returned. 2852 10.1.1. GET 2854 The GET method requests the proxy to return a representation of the 2855 HTTP resource identified by the request URI. 2857 Upon success, a 2.05 (Content) response SHOULD be returned. The 2858 payload of the response MUST be a representation of the target HTTP 2859 resource, and the Content-Type Option be set accordingly. The 2860 response MUST indicate a Max-Age value that is no greater than the 2861 remaining time the representation can be considered fresh. If the 2862 HTTP entity has an entity tag, the proxy SHOULD include an ETag 2863 Option in the response and process ETag Options in requests as 2864 described below. 2866 A client can influence the processing of a GET request by including 2867 the following option: 2869 Accept: The request MAY include one or more Accept Options, 2870 identifying the preferred response content-type. 2872 ETag: The request MAY include one or more ETag Options, identifying 2873 responses that the client has stored. This requests the proxy to 2874 send a 2.03 (Valid) response whenever it would send a 2.05 2875 (Content) response with an entity tag in the requested set 2876 otherwise. 2878 10.1.2. PUT 2880 The PUT method requests the proxy to update or create the HTTP 2881 resource identified by the request URI with the enclosed 2882 representation. 2884 If a new resource is created at the request URI, a 2.01 (Created) 2885 response MUST be returned to the client. If an existing resource is 2886 modified, a 2.04 (Changed) response MUST be returned to indicate 2887 successful completion of the request. 2889 10.1.3. DELETE 2891 The DELETE method requests the proxy to delete the HTTP resource 2892 identified by the request URI at the HTTP origin server. 2894 A 2.02 (Deleted) response MUST be returned to client upon success or 2895 if the resource does not exist at the time of the request. 2897 10.1.4. POST 2899 The POST method requests the proxy to have the representation 2900 enclosed in the request be processed by the HTTP origin server. The 2901 actual function performed by the POST method is determined by the 2902 origin server and dependent on the resource identified by the request 2903 URI. 2905 If the action performed by the POST method does not result in a 2906 resource that can be identified by a URI, a 2.04 (Changed) response 2907 MUST be returned to the client. If a resource has been created on 2908 the origin server, a 2.01 (Created) response MUST be returned. 2910 10.2. HTTP-CoAP Mapping 2912 If an HTTP request contains a Request-URI with a 'coap' or 'coaps' 2913 URI, then the receiving HTTP endpoint (called "the proxy" henceforth) 2914 is requested to perform the operation specified by the request method 2915 on the indicated CoAP resource and return the result to the client. 2917 This section specifies for any HTTP request the HTTP response that 2918 the proxy should return to the client. How the proxy actually 2919 satisfies the request is an implementation detail, although the 2920 typical case is expected to be the proxy translating and forwarding 2921 the request to a CoAP origin server. The meanings of the individual 2922 HTTP methods when performed on CoAP resources are explained below. 2924 If the proxy is unable or unwilling to service a request with a CoAP 2925 URI, a 501 (Not Implemented) response SHOULD be returned to the 2926 client. If the proxy services the request by interacting with a 2927 third party (such as the CoAP origin server) and is unable to obtain 2928 a result within a reasonable time frame, a 504 (Gateway Timeout) 2929 response SHOULD be returned; if a result can be obtained but is not 2930 understood, a 502 (Bad Gateway) response SHOULD be returned. 2932 10.2.1. OPTIONS and TRACE 2934 As the OPTIONS and TRACE methods are not supported in CoAP a 501 (Not 2935 Implemented) error MUST be returned to the client. 2937 10.2.2. GET 2939 The GET method requests the proxy to return a representation of the 2940 CoAP resource identified by the Request-URI. 2942 Upon success, a 200 (OK) response SHOULD be returned. The payload of 2943 the response MUST be a representation of the target CoAP resource, 2944 and the Content-Type Option be set accordingly. The response MUST 2945 indicate a Max-Age value that is no greater than the remaining time 2946 the representation can be considered fresh. If the CoAP entity has 2947 an entity tag, the proxy SHOULD include an ETag Option in the 2948 response. 2950 A client can influence the processing of a GET request by including 2951 the following option: 2953 Accept: Each individual Media-type of the HTTP Accept header in a 2954 request is mapped to a CoAP Accept option. HTTP Accept Media-type 2955 ranges, parameters and extensions are not supported by the CoAP 2956 Accept option. If the proxy cannot send a response which is 2957 acceptable according to the combined Accept field value, then the 2958 proxy SHOULD send a 406 (not acceptable) response. 2960 Conditional GETs: Conditional HTTP GET requests that include an "If- 2961 Match" or "If-None-Match" request-header field can be mapped to a 2962 corresponding CoAP request. The "If-Modified-Since" and "If- 2963 Unmodified-Since" request-header fields are not directly supported 2964 by CoAP, but SHOULD be implemented locally by a caching proxy. 2966 10.2.3. HEAD 2968 The HEAD method is identical to GET except that the server MUST NOT 2969 return a message-body in the response. 2971 Although there is no direct equivalent of HTTP's HEAD method in CoAP, 2972 an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and 2973 the HTTP headers are returned without a message-body. 2975 10.2.4. POST 2977 The POST method requests the proxy to have the representation 2978 enclosed in the request be processed by the CoAP origin server. The 2979 actual function performed by the POST method is determined by the 2980 origin server and dependent on the resource identified by the request 2981 URI. 2983 If the action performed by the POST method does not result in a 2984 resource that can be identified by a URI, a 200 (OK) or 204 (No 2985 Content) response MUST be returned to the client. If a resource has 2986 been created on the origin server, a 201 (Created) response MUST be 2987 returned. 2989 10.2.5. PUT 2991 The PUT method requests the proxy to update or create the CoAP 2992 resource identified by the Request-URI with the enclosed 2993 representation. 2995 If a new resource is created at the Request-URI, a 201 (Created) 2996 response MUST be returned to the client. If an existing resource is 2997 modified, either the 200 (OK) or 204 (No Content) response codes 2998 SHOULD be sent to indicate successful completion of the request. 3000 10.2.6. DELETE 3002 The DELETE method requests the proxy to delete the CoAP resource 3003 identified by the Request-URI at the CoAP origin server. 3005 A successful response SHOULD be 200 (OK) if the response includes an 3006 entity describing the status or 204 (No Content) if the action has 3007 been enacted but the response does not include an entity. 3009 10.2.7. CONNECT 3011 This method can not currently be satisfied by an HTTP-CoAP proxy 3012 function as TLS to DTLS tunneling has not been specified. It is 3013 however expected that such a tunneling mapping will be defined in the 3014 future. A 501 (Not Implemented) error SHOULD be returned to the 3015 client. 3017 11. Security Considerations 3019 This section analyzes the possible threats to the protocol. It is 3020 meant to inform protocol and application developers about the 3021 security limitations of CoAP as described in this document. As CoAP 3022 realizes a subset of the features in HTTP/1.1, the security 3023 considerations in Section 15 of [RFC2616] are also pertinent to CoAP. 3024 This section concentrates on describing limitations specific to CoAP. 3026 11.1. Protocol Parsing, Processing URIs 3028 A network-facing application can exhibit vulnerabilities in its 3029 processing logic for incoming packets. Complex parsers are well- 3030 known as a likely source of such vulnerabilities, such as the ability 3031 to remotely crash a node, or even remotely execute arbitrary code on 3032 it. CoAP attempts to narrow the opportunities for introducing such 3033 vulnerabilities by reducing parser complexity, by giving the entire 3034 range of encodable values a meaning where possible, and by 3035 aggressively reducing complexity that is often caused by unnecessary 3036 choice between multiple representations that mean the same thing. 3037 Much of the URI processing has been moved to the clients, further 3038 reducing the opportunities for introducing vulnerabilities into the 3039 servers. Even so, the URI processing code in CoAP implementations is 3040 likely to be a large source of remaining vulnerabilities and should 3041 be implemented with special care. The most complex parser remaining 3042 could be the one for the link-format, although this also has been 3043 designed with a goal of reduced implementation complexity 3044 [I-D.ietf-core-link-format]. (See also section 15.2 of [RFC2616].) 3046 11.2. Proxying and Caching 3048 As mentioned in 15.7 of [RFC2616], proxies are by their very nature 3049 men-in-the-middle, breaking any IPsec or DTLS protection that a 3050 direct CoAP message exchange might have. They are therefore 3051 interesting targets for breaking confidentiality or integrity of CoAP 3052 message exchanges. As noted in [RFC2616], they are also interesting 3053 targets for breaking availability. 3055 The threat to confidentiality and integrity of request/response data 3056 is amplified where proxies also cache. Note that CoAP does not 3057 define any of the cache-suppressing Cache-Control options that 3058 HTTP/1.1 provides to better protect sensitive data. 3060 Finally, a proxy that fans out Separate Responses (as opposed to 3061 Piggy-backed Responses) to multiple original requesters may provide 3062 additional amplification (see below). 3064 11.3. Risk of amplification 3066 CoAP servers generally reply to a request packet with a response 3067 packet. This response packet may be significantly larger than the 3068 request packet. An attacker might use CoAP nodes to turn a small 3069 attack packet into a larger attack packet, an approach known as 3070 amplification. There is therefore a danger that CoAP nodes could 3071 become implicated in denial of service (DoS) attacks by using the 3072 amplifying properties of the protocol: An attacker that is attempting 3073 to overload a victim but is limited in the amount of traffic it can 3074 generate, can use amplification to generate a larger amount of 3075 traffic. 3077 This is particularly a problem in nodes that enable NoSec access, 3078 that are accessible from an attacker and can access potential victims 3079 (e.g. on the general Internet), as the UDP protocol provides no way 3080 to verify the source address given in the request packet. An 3081 attacker need only place the IP address of the victim in the source 3082 address of a suitable request packet to generate a larger packet 3083 directed at the victim. 3085 As a mitigating factor, many constrained networks will only be able 3086 to generate a small amount of traffic, which may make CoAP nodes less 3087 attractive for this attack. However, the limited capacity of the 3088 constrained network makes the network itself a likely victim of an 3089 amplification attack. 3091 A CoAP server can reduce the amount of amplification it provides to 3092 an attacker by using slicing/blocking modes of CoAP 3093 [I-D.ietf-core-block] and offering large resource representations 3094 only in relatively small slices. E.g., for a 1000 byte resource, a 3095 10-byte request might result in an 80-byte response (with a 64-byte 3096 block) instead of a 1016-byte response, considerably reducing the 3097 amplification provided. 3099 CoAP also supports the use of multicast IP addresses in requests, an 3100 important requirement for M2M. Multicast CoAP requests may be the 3101 source of accidental or deliberate denial of service attacks, 3102 especially over constrained networks. This specification attempts to 3103 reduce the amplification effects of multicast requests by limiting 3104 when a response is returned. To limit the possibility of malicious 3105 use, CoAP servers SHOULD NOT accept multicast requests that can not 3106 be authenticated. If possible a CoAP server SHOULD limit the support 3107 for multicast requests to specific resources where the feature is 3108 required. 3110 On some general purpose operating systems providing a Posix-style 3111 API, it is not straightforward to find out whether a packet received 3112 was addressed to a multicast address. While many implementations 3113 will know whether they have joined a multicast group, this creates a 3114 problem for packets addressed to multicast addresses of the form 3115 FF0x::1, which are received by every IPv6 node. Implementations 3116 SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 3117 available, to make this determination. 3119 11.4. IP Address Spoofing Attacks 3121 Due to the lack of a handshake in UDP, a rogue endpoint which is free 3122 to read and write messages carried by the constrained network (i.e. 3123 NoSec or PreSharedKey deployments with nodes/key ratio > 1:1), may 3124 easily attack a single endpoint, a group of endpoints, as well as the 3125 whole network e.g. by: 3127 1. spoofing RST in response to a CON or NON message, thus making an 3128 endpoint "deaf"; or 3130 2. spoofing the entire response with forged payload/options (this 3131 has different levels of impact: from single response disruption, 3132 to much bolder attacks on the supporting infrastructure, e.g. 3133 poisoning proxy caches, or tricking validation / lookup 3134 interfaces in resource directories and, more generally, any 3135 component that stores global network state and uses CoAP as the 3136 messaging facility to handle state set/update's is a potential 3137 target.); or 3139 3. spoofing a multicast request for a target node which may result 3140 in both network congestion/collapse and victim DoS'ing / forced 3141 wakeup from sleeping; or 3143 4. spoofing observe messages, etc. 3145 In principle, spoofing can be detected by CoAP only in case CON 3146 semantics is used, because of unexpected ACK/RSTs coming from the 3147 deceived endpoint. But this imposes keeping track of the used 3148 Message IDs which is not always possible, and moreover detection 3149 becomes available usually after the damage is already done. This 3150 kind of attack can be prevented using security modes other than 3151 NoSec. 3153 11.5. Cross-Protocol Attacks 3155 The ability to incite a CoAP endpoint to send packets to a fake 3156 source address can be used not only for amplification, but also for 3157 cross-protocol attacks: 3159 o the attacker sends a message to a CoAP endpoint with a fake source 3160 address, 3162 o the CoAP endpoint replies with a message to the given source 3163 address, 3165 o the victim at the given source address receives a UDP packet that 3166 it interprets according to the rules of a different protocol. 3168 This may be used to circumvent firewall rules that prevent direct 3169 communication from the attacker to the victim, but happen to allow 3170 communication from the CoAP endpoint (which may also host a valid 3171 role in the other protocol) to the victim. 3173 Also, CoAP endpoints may be the victim of a cross-protocol attack 3174 generated through an endpoint of another UDP-based protocol such as 3175 DNS. In both cases, attacks are possible if the security properties 3176 of the endpoints rely on checking IP addresses (and firewalling off 3177 direct attacks sent from outside using fake IP addresses). In 3178 general, because of their lack of context, UDP-based protocols are 3179 relatively easy targets for cross-protocol attacks. 3181 Finally, CoAP URIs transported by other means could be used to incite 3182 clients to send messages to endpoints of other protocols. 3184 One mitigation against cross-protocol attacks is strict checking of 3185 the syntax of packets received, combined with sufficient difference 3186 in syntax. As an example, it might help if it were difficult to 3187 incite a DNS server to send a DNS response that would pass the checks 3188 of a CoAP endpoint. Unfortunately, the first two bytes of a DNS 3189 reply are an ID that can be chosen by the attacker, which map into 3190 the interesting part of the CoAP header, and the next two bytes are 3191 then interpreted as CoAP's Message ID (i.e., any value is 3192 acceptable). The DNS count words may be interpreted as multiple 3193 instances of a (non-existent, but elective) CoAP option 0. The 3194 echoed query finally may be manufactured by the attacker to achieve a 3195 desired effect on the CoAP endpoint; the response added by the server 3196 (if any) might then just be interpreted as added payload. 3198 1 1 1 1 1 1 3199 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 3200 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3201 | ID | T, OC, code 3202 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3203 |QR| Opcode |AA|TC|RD|RA| Z | RCODE | message id 3204 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3205 | QDCOUNT | (options 0) 3206 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3207 | ANCOUNT | (options 0) 3208 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3209 | NSCOUNT | (options 0) 3210 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3211 | ARCOUNT | (options 0) 3212 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3214 Figure 11: DNS Header vs. CoAP Message 3216 In general, for any pair of protocols, one of the protocols can very 3217 well have been designed in a way that enables an attacker to cause 3218 the generation of replies that look like messages of the other 3219 protocol. It is often much harder to ensure or prove the absence of 3220 viable attacks than to generate examples that may not yet completely 3221 enable an attack but might be further developed by more creative 3222 minds. Cross-protocol attacks can therefore only be completely 3223 mitigated if endpoints don't authorize actions desired by an attacker 3224 just based on trusting the source IP address of a packet. 3225 Conversely, a NoSec environment that completely relies on a firewall 3226 for CoAP security not only needs to firewall off the CoAP endpoints 3227 but also all other endpoints that might be incited to send UDP 3228 messages to CoAP endpoints using some other UDP-based protocol. 3230 In addition to the considerations above, the security considerations 3231 for DTLS with respect to cross-protocol attacks apply. E.g., if the 3232 same DTLS security association ("connection") is used to carry data 3233 of multiple protocols, DTLS no longer provides protection against 3234 cross-protocol attacks between these protocols. 3236 12. IANA Considerations 3238 12.1. CoAP Code Registry 3240 This document defines a registry for the values of the Code field in 3241 the CoAP header. The name of the registry is "CoAP Codes". 3243 All values are assigned by sub-registries according to the following 3244 ranges: 3246 0 Indicates an empty message (see Section 4.1). 3248 1-31 Indicates a request. Values in this range are assigned by 3249 the "CoAP Method Codes" sub-registry (see Section 12.1.1). 3251 32-63 Reserved 3253 64-191 Indicates a response. Values in this range are assigned by 3254 the "CoAP Response Codes" sub-registry (see 3255 Section 12.1.2). 3257 192-255 Reserved 3259 12.1.1. Method Codes 3261 The name of the sub-registry is "CoAP Method Codes". 3263 Each entry in the sub-registry must include the Method Code in the 3264 range 1-31, the name of the method, and a reference to the method's 3265 documentation. 3267 Initial entries in this sub-registry are as follows: 3269 +------+--------+-----------+ 3270 | Code | Name | Reference | 3271 +------+--------+-----------+ 3272 | 1 | GET | [RFCXXXX] | 3273 | 2 | POST | [RFCXXXX] | 3274 | 3 | PUT | [RFCXXXX] | 3275 | 4 | DELETE | [RFCXXXX] | 3276 +------+--------+-----------+ 3278 Table 2: CoAP Method Codes 3280 All other Method Codes are Unassigned. 3282 The IANA policy for future additions to this registry is "IETF 3283 Review" as described in [RFC5226]. 3285 The documentation of a method code should specify the semantics of a 3286 request with that code, including the following properties: 3288 o The response codes the method returns in the success case. 3290 o Whether the method is idempotent, safe, or both. 3292 12.1.2. Response Codes 3294 The name of the sub-registry is "CoAP Response Codes". 3296 Each entry in the sub-registry must include the Response Code in the 3297 range 64-191, a description of the Response Code, and a reference to 3298 the Response Code's documentation. 3300 Initial entries in this sub-registry are as follows: 3302 +------+-------------------------------+-----------+ 3303 | Code | Description | Reference | 3304 +------+-------------------------------+-----------+ 3305 | 65 | 2.01 Created | [RFCXXXX] | 3306 | 66 | 2.02 Deleted | [RFCXXXX] | 3307 | 67 | 2.03 Valid | [RFCXXXX] | 3308 | 68 | 2.04 Changed | [RFCXXXX] | 3309 | 69 | 2.05 Content | [RFCXXXX] | 3310 | 128 | 4.00 Bad Request | [RFCXXXX] | 3311 | 129 | 4.01 Unauthorized | [RFCXXXX] | 3312 | 130 | 4.02 Bad Option | [RFCXXXX] | 3313 | 131 | 4.03 Forbidden | [RFCXXXX] | 3314 | 132 | 4.04 Not Found | [RFCXXXX] | 3315 | 133 | 4.05 Method Not Allowed | [RFCXXXX] | 3316 | 134 | 4.06 Not Acceptable | [RFCXXXX] | 3317 | 140 | 4.12 Precondition Failed | [RFCXXXX] | 3318 | 141 | 4.13 Request Entity Too Large | [RFCXXXX] | 3319 | 143 | 4.15 Unsupported Media Type | [RFCXXXX] | 3320 | 160 | 5.00 Internal Server Error | [RFCXXXX] | 3321 | 161 | 5.01 Not Implemented | [RFCXXXX] | 3322 | 162 | 5.02 Bad Gateway | [RFCXXXX] | 3323 | 163 | 5.03 Service Unavailable | [RFCXXXX] | 3324 | 164 | 5.04 Gateway Timeout | [RFCXXXX] | 3325 | 165 | 5.05 Proxying Not Supported | [RFCXXXX] | 3326 +------+-------------------------------+-----------+ 3328 Table 3: CoAP Response Codes 3330 The Response Codes 96-127 are Reserved for future use. All other 3331 Response Codes are Unassigned. 3333 The IANA policy for future additions to this registry is "IETF 3334 Review" as described in [RFC5226]. 3336 The documentation of a response code should specify the semantics of 3337 a response with that code, including the following properties: 3339 o The methods the response code applies to. 3341 o Whether payload is required, optional or not allowed. 3343 o The semantics of the payload. For example, the payload of a 2.05 3344 (Content) response is a representation of the target resource; the 3345 payload in an error response is a human-readable diagnostic 3346 message. 3348 o The format of the payload. For example, the format in a 2.05 3349 (Content) response is indicated by the Content-Type Option; the 3350 format of the payload in an error response is always Net-Unicode 3351 text. 3353 o Whether the response is cacheable according to the freshness 3354 model. 3356 o Whether the response is validatable according to the validation 3357 model. 3359 o Whether the response causes a cache to mark responses stored for 3360 the request URI as not fresh. 3362 12.2. Option Number Registry 3364 This document defines a registry for the Option Numbers used in CoAP 3365 options. The name of the registry is "CoAP Option Numbers". 3367 Each entry in the registry must include the Option Number, the name 3368 of the option and a reference to the option's documentation. 3370 Initial entries in this registry are as follows: 3372 +--------+----------------+-----------+ 3373 | Number | Name | Reference | 3374 +--------+----------------+-----------+ 3375 | 0 | (Reserved) | | 3376 | 1 | Content-Type | [RFCXXXX] | 3377 | 2 | Max-Age | [RFCXXXX] | 3378 | 3 | Proxy-Uri | [RFCXXXX] | 3379 | 4 | ETag | [RFCXXXX] | 3380 | 5 | Uri-Host | [RFCXXXX] | 3381 | 6 | Location-Path | [RFCXXXX] | 3382 | 7 | Uri-Port | [RFCXXXX] | 3383 | 8 | Location-Query | [RFCXXXX] | 3384 | 9 | Uri-Path | [RFCXXXX] | 3385 | 10 | (Unassigned) | | 3386 | 11 | Token | [RFCXXXX] | 3387 | 12 | Accept | [RFCXXXX] | 3388 | 13 | If-Match | [RFCXXXX] | 3389 | 14 | (Unassigned) | | 3390 | 15 | Uri-Query | [RFCXXXX] | 3391 | 16-20 | (Unassigned) | | 3392 | 21 | If-None-Match | [RFCXXXX] | 3393 | 22-43 | (Unassigned) | | 3394 | 44 | (Reserved) | | 3395 | 45 | (Unassigned) | | 3396 | 46 | (Reserved) | | 3397 | 47 | (Unassigned) | | 3398 | 48 | (Reserved) | | 3399 | 49- | (Unassigned) | | 3400 +--------+----------------+-----------+ 3402 Table 4: CoAP Option Numbers 3404 The IANA policy for future additions to this registry is "IETF 3405 Review" as described in [RFC5226]. 3407 The documentation of an Option Number should specify the semantics of 3408 an option with that number, including the following properties: 3410 o The meaning of the option in a request. 3412 o The meaning of the option in a response. 3414 o Whether the option is critical or elective, as determined by the 3415 Option Number. 3417 o The format and length of the option's value. 3419 o Whether the option must occur at most once or whether it can occur 3420 multiple times. 3422 o The default value, if any. For a critical option with a default 3423 value, a discussion on how the default value enables processing by 3424 implementations not implementing the critical option 3425 (Section 5.4.3). For options with numbers that are a multiple of 3426 14, the default value MUST be empty. 3428 12.3. Media Type Registry 3430 Media types are identified by a string, such as "application/xml" 3431 [RFC2046]. In order to minimize the overhead of using these media 3432 types to indicate the format of payloads, this document defines a 3433 registry for a subset of Internet media types to be used in CoAP and 3434 assigns each a numeric identifier. The name of the registry is "CoAP 3435 Media Types". 3437 Each entry in the registry must include the media type registered 3438 with IANA, the numeric identifier in the range 0-65535 to be used for 3439 that media type in CoAP, the content-encoding associated with this 3440 identifier, and a reference to a document describing what a payload 3441 with that media type means semantically. 3443 CoAP does not include a way to convey content-encoding information 3444 with a request or response, and for that reason the content-encoding 3445 is also specified for each identifier (if any). If multiple content- 3446 encodings will be used with a media type, then a separate identifier 3447 for each is to be registered. 3449 Initial entries in this registry are as follows: 3451 +--------------------+----------+-----+-----------------------------+ 3452 | Media type | Encoding | Id. | Reference | 3453 +--------------------+----------+-----+-----------------------------+ 3454 | text/plain; | - | 0 | [RFC2046][RFC3676][RFC5147] | 3455 | charset=utf-8 | | | | 3456 | application/ | - | 40 | [I-D.ietf-core-link-format] | 3457 | link-format | | | | 3458 | application/xml | - | 41 | [RFC3023] | 3459 | application/ | - | 42 | [RFC2045][RFC2046] | 3460 | octet-stream | | | | 3461 | application/exi | - | 47 | [EXIMIME] | 3462 | application/json | - | 50 | [RFC4627] | 3463 +--------------------+----------+-----+-----------------------------+ 3465 Table 5: CoAP Media Types 3467 The identifiers between 201 and 255 inclusive are reserved for 3468 Private Use. All other identifiers are Unassigned. 3470 Because the name space of single-byte identifiers is so small, the 3471 IANA policy for future additions in the range 0-200 inclusive to the 3472 registry is "Expert Review" as described in [RFC5226]. The IANA 3473 policy for additions in the range 256-65535 inclusive is "First Come 3474 First Served" as described in [RFC5226]. 3476 In machine to machine applications, it is not expected that generic 3477 Internet media types such as text/plain, application/xml or 3478 application/octet-stream are useful for real applications in the long 3479 term. It is recommended that M2M applications making use of CoAP 3480 will request new Internet media types from IANA indicating semantic 3481 information about how to create or parse a payload. For example, a 3482 Smart Energy application payload carried as XML might request a more 3483 specific type like application/se+xml or application/se+exi. 3485 12.4. URI Scheme Registration 3487 This document requests the registration of the Uniform Resource 3488 Identifier (URI) scheme "coap". The registration request complies 3489 with [RFC4395]. 3491 URI scheme name. 3492 coap 3494 Status. 3495 Permanent. 3497 URI scheme syntax. 3498 Defined in Section 6.1 of [RFCXXXX]. 3500 URI scheme semantics. 3501 The "coap" URI scheme provides a way to identify resources that 3502 are potentially accessible over the Constrained Application 3503 Protocol (CoAP). The resources can be located by contacting the 3504 governing CoAP server and operated on by sending CoAP requests to 3505 the server. This scheme can thus be compared to the "http" URI 3506 scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of 3507 operation. 3509 Encoding considerations. 3510 The scheme encoding conforms to the encoding rules established for 3511 URIs in [RFC3986], i.e. internationalized and reserved characters 3512 are expressed using UTF-8-based percent-encoding. 3514 Applications/protocols that use this URI scheme name. 3515 The scheme is used by CoAP endpoints to access CoAP resources. 3517 Interoperability considerations. 3518 None. 3520 Security considerations. 3521 See Section 11.1 of [RFCXXXX]. 3523 Contact. 3524 IETF Chair 3526 Author/Change controller. 3527 IESG 3529 References. 3530 [RFCXXXX] 3532 12.5. Secure URI Scheme Registration 3534 This document requests the registration of the Uniform Resource 3535 Identifier (URI) scheme "coaps". The registration request complies 3536 with [RFC4395]. 3538 URI scheme name. 3539 coaps 3541 Status. 3542 Permanent. 3544 URI scheme syntax. 3545 Defined in Section 6.2 of [RFCXXXX]. 3547 URI scheme semantics. 3548 The "coaps" URI scheme provides a way to identify resources that 3549 are potentially accessible over the Constrained Application 3550 Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for 3551 transport security. The resources can be located by contacting 3552 the governing CoAP server and operated on by sending CoAP requests 3553 to the server. This scheme can thus be compared to the "https" 3554 URI scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details 3555 of operation. 3557 Encoding considerations. 3558 The scheme encoding conforms to the encoding rules established for 3559 URIs in [RFC3986], i.e. internationalized and reserved characters 3560 are expressed using UTF-8-based percent-encoding. 3562 Applications/protocols that use this URI scheme name. 3563 The scheme is used by CoAP endpoints to access CoAP resources 3564 using DTLS. 3566 Interoperability considerations. 3567 None. 3569 Security considerations. 3570 See Section 11.1 of [RFCXXXX]. 3572 Contact. 3573 IETF Chair 3575 Author/Change controller. 3576 IESG 3578 References. 3579 [RFCXXXX] 3581 12.6. Service Name and Port Number Registration 3583 One of the functions of CoAP is resource discovery: a CoAP client can 3584 ask a CoAP server about the resources offered by it (see Section 7). 3585 To enable resource discovery just based on the knowledge of an IP 3586 address, the CoAP port for resource discovery needs to be 3587 standardized. 3589 IANA has assigned the port number 5683 and the service name "coap", 3590 in accordance with [RFC6335]. 3592 Besides unicast, CoAP can be used with both multicast and anycast. 3594 Service Name. 3595 coap 3597 Transport Protocol. 3598 UDP 3600 Assignee. 3601 IESG 3603 Contact. 3604 IETF Chair 3606 Description. 3607 Constrained Application Protocol (CoAP) 3609 Reference. 3610 [RFCXXXX] 3612 Port Number. 3613 5683 3615 12.7. Secure Service Name and Port Number Registration 3617 CoAP resource discovery may also be provided using the DTLS-secured 3618 CoAP "coaps" scheme. Thus the CoAP port for secure resource 3619 discovery needs to be standardized. 3621 This document requests the assignment of the port number 3622 [IANA_TBD_PORT] and the service name "coaps", in accordance with 3623 [RFC6335]. 3625 Besides unicast, DTLS-secured CoAP can be used with anycast. 3627 Service Name. 3628 coaps 3630 Transport Protocol. 3631 UDP 3633 Assignee. 3634 IESG 3636 Contact. 3637 IETF Chair 3639 Description. 3640 DTLS-secured CoAP 3642 Reference. 3643 [RFCXXXX] 3645 Port Number. 3646 [IANA_TBD_PORT] 3648 12.8. Multicast Address Registration 3650 Section 8, "Multicast CoAP", defines the use of multicast. This 3651 document requests the assignment of the following multicast addresses 3652 for use by CoAP nodes: 3654 IPv4 -- "All CoAP Nodes" address [TBD1], from the IPv4 Multicast 3655 Address Space Registry. As the address is used for discovery that 3656 may span beyond a single network, it should come from the 3657 Internetwork Control Block (224.0.1.x, RFC 5771). 3659 IPv6 -- "All CoAP Nodes" address [TBD2], from the IPv6 Multicast 3660 Address Space Registry, in the Variable Scope Multicast Addresses 3661 space (RFC3307). Note that there is a distinct multicast address 3662 for each scope that interested CoAP nodes should listen to. 3664 [The explanatory text to be removed upon allocation of the addresses, 3665 except for the note about the distinct multicast addresses.] 3667 13. Acknowledgements 3669 Special thanks to Peter Bigot, Esko Dijk and Cullen Jennings for 3670 substantial contributions to the ideas and text in the document, 3671 along with countless detailed reviews and discussions. 3673 Thanks to Ed Beroset, Angelo P. Castellani, Gilbert Clark, Robert 3674 Cragie, Esko Dijk, Lisa Dussealt, Thomas Fossati, Tom Herbst, Richard 3675 Kelsey, Ari Keranen, Matthias Kovatsch, Salvatore Loreto, Kerry Lynn, 3676 Alexey Melnikov, Guido Moritz, Petri Mutka, Colin O'Flynn, Charles 3677 Palmer, Adriano Pezzuto, Robert Quattlebaum, Akbar Rahman, Eric 3678 Rescorla, David Ryan, Szymon Sasin, Michael Scharf, Dale Seed, Robby 3679 Simpson, Peter van der Stok, Michael Stuber, Linyi Tian, Gilman 3680 Tolle, Matthieu Vial and Alper Yegin for helpful comments and 3681 discussions that have shaped the document. 3683 Some of the text has been lifted from the working documents of the 3684 IETF httpbis working group. 3686 14. References 3688 14.1. Normative References 3690 [I-D.farrell-decade-ni] 3691 Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 3692 Keranen, A., and P. Hallam-Baker, "Naming Things with 3693 Hashes", draft-farrell-decade-ni-09 (work in progress), 3694 July 2012. 3696 [I-D.ietf-core-link-format] 3697 Shelby, Z., "CoRE Link Format", 3698 draft-ietf-core-link-format-14 (work in progress), 3699 June 2012. 3701 [I-D.ietf-tls-oob-pubkey] 3702 Wouters, P., Gilmore, J., Weiler, S., Kivinen, T., and H. 3703 Tschofenig, "Out-of-Band Public Key Validation for 3704 Transport Layer Security", draft-ietf-tls-oob-pubkey-04 3705 (work in progress), July 2012. 3707 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3708 Extensions (MIME) Part One: Format of Internet Message 3709 Bodies", RFC 2045, November 1996. 3711 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3712 Extensions (MIME) Part Two: Media Types", RFC 2046, 3713 November 1996. 3715 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3716 Requirement Levels", BCP 14, RFC 2119, March 1997. 3718 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3719 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3720 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3722 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 3723 Types", RFC 3023, January 2001. 3725 [RFC3602] Frankel, S., Glenn, R., and S. Kelly, "The AES-CBC Cipher 3726 Algorithm and Its Use with IPsec", RFC 3602, 3727 September 2003. 3729 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3730 10646", STD 63, RFC 3629, November 2003. 3732 [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", 3733 RFC 3676, February 2004. 3735 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3736 Resource Identifier (URI): Generic Syntax", STD 66, 3737 RFC 3986, January 2005. 3739 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 3740 for Transport Layer Security (TLS)", RFC 4279, 3741 December 2005. 3743 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 3744 RFC 4303, December 2005. 3746 [RFC4309] Housley, R., "Using Advanced Encryption Standard (AES) CCM 3747 Mode with IPsec Encapsulating Security Payload (ESP)", 3748 RFC 4309, December 2005. 3750 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 3751 Registration Procedures for New URI Schemes", BCP 35, 3752 RFC 4395, February 2006. 3754 [RFC4835] Manral, V., "Cryptographic Algorithm Implementation 3755 Requirements for Encapsulating Security Payload (ESP) and 3756 Authentication Header (AH)", RFC 4835, April 2007. 3758 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 3759 text/plain Media Type", RFC 5147, April 2008. 3761 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 3762 Interchange", RFC 5198, March 2008. 3764 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3765 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3766 May 2008. 3768 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3769 Specifications: ABNF", STD 68, RFC 5234, January 2008. 3771 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3772 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3774 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3775 Housley, R., and W. Polk, "Internet X.509 Public Key 3776 Infrastructure Certificate and Certificate Revocation List 3777 (CRL) Profile", RFC 5280, May 2008. 3779 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3780 Uniform Resource Identifiers (URIs)", RFC 5785, 3781 April 2010. 3783 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3784 Address Text Representation", RFC 5952, August 2010. 3786 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3788 [RFC5996] Kaufman, C., Hoffman, P., Nir, Y., and P. Eronen, 3789 "Internet Key Exchange Protocol Version 2 (IKEv2)", 3790 RFC 5996, September 2010. 3792 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 3793 Extension Definitions", RFC 6066, January 2011. 3795 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3796 Security Version 1.2", RFC 6347, January 2012. 3798 14.2. Informative References 3800 [EUI64] "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) 3801 REGISTRATION AUTHORITY", April 2010, . 3804 [EXIMIME] "Efficient XML Interchange (EXI) Format 1.0", 3805 December 2009, . 3808 [I-D.allman-tcpm-rto-consider] 3809 Allman, M., "Retransmission Timeout Considerations", 3810 draft-allman-tcpm-rto-consider-01 (work in progress), 3811 May 2012. 3813 [I-D.eggert-core-congestion-control] 3814 Eggert, L., "Congestion Control for the Constrained 3815 Application Protocol (CoAP)", 3816 draft-eggert-core-congestion-control-01 (work in 3817 progress), January 2011. 3819 [I-D.ietf-core-block] 3820 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 3821 draft-ietf-core-block-08 (work in progress), 3822 February 2012. 3824 [I-D.ietf-httpbis-p1-messaging] 3825 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 3826 1: Message Routing and Syntax"", 3827 draft-ietf-httpbis-p1-messaging-20 (work in progress), 3828 July 2012. 3830 [I-D.kivinen-ipsecme-ikev2-minimal] 3831 Kivinen, T., "Minimal IKEv2", 3832 draft-kivinen-ipsecme-ikev2-minimal-00 (work in progress), 3833 February 2011. 3835 [I-D.mcgrew-tls-aes-ccm] 3836 McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for TLS", 3837 draft-mcgrew-tls-aes-ccm-03 (work in progress), 3838 February 2012. 3840 [I-D.mcgrew-tls-aes-ccm-ecc] 3841 McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 3842 CCM ECC Cipher Suites for TLS", 3843 draft-mcgrew-tls-aes-ccm-ecc-02 (work in progress), 3844 October 2011. 3846 [REST] Fielding, R., "Architectural Styles and the Design of 3847 Network-based Software Architectures", Ph.D. Dissertation, 3848 University of California, Irvine, 2000, . 3852 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 3853 RFC 793, September 1981. 3855 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3857 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 3858 with Session Description Protocol (SDP)", RFC 3264, 3859 June 2002. 3861 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 3862 "Advanced Sockets Application Program Interface (API) for 3863 IPv6", RFC 3542, May 2003. 3865 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 3866 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 3867 for Transport Layer Security (TLS)", RFC 4492, May 2006. 3869 [RFC4627] Crockford, D., "The application/json Media Type for 3870 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 3872 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 3873 "Transmission of IPv6 Packets over IEEE 802.15.4 3874 Networks", RFC 4944, September 2007. 3876 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 3877 for Application Designers", BCP 145, RFC 5405, 3878 November 2008. 3880 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 3881 Protocol (XMPP): Core", RFC 6120, March 2011. 3883 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 3884 Cheshire, "Internet Assigned Numbers Authority (IANA) 3885 Procedures for the Management of the Service Name and 3886 Transport Protocol Port Number Registry", BCP 165, 3887 RFC 6335, August 2011. 3889 Appendix A. Examples 3891 This section gives a number of short examples with message flows for 3892 GET requests. These examples demonstrate the basic operation, the 3893 operation in the presence of retransmissions, and multicast. 3895 Figure 12 shows a basic GET request causing a piggy-backed response: 3896 The client sends a Confirmable GET request for the resource 3897 coap://server/temperature to the server with a Message ID of 0x7d34. 3898 The request includes one Uri-Path Option (Delta 0 + 9 = 9, Length 11, 3899 Value "temperature"); the Token is left at its default value (empty). 3900 This request is a total of 16 bytes long. A 2.05 (Content) response 3901 is returned in the Acknowledgement message that acknowledges the 3902 Confirmable request, echoing both the Message ID 0x7d34 and the 3903 (implicitly empty) Token value. The response includes a Payload of 3904 "22.3 C" and is 10 bytes long. 3906 Client Server 3907 | | 3908 | | 3909 +----->| Header: GET (T=CON, Code=1, MID=0x7d34) 3910 | GET | Uri-Path: "temperature" 3911 | | 3912 | | 3913 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d34) 3914 | 2.05 | Payload: "22.3 C" 3915 | | 3917 0 1 2 3 3918 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 3919 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3920 | 1 | 0 | 1 | GET=1 | MID=0x7d34 | 3921 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3922 | 9 | 11 | "temperature" (11 B) ... 3923 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3925 0 1 2 3 3926 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 3927 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3928 | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | 3929 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3930 | "22.3 C" (6 B) ... 3931 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3933 Figure 12: Confirmable request; piggy-backed response 3935 Figure 13 shows a similar example, but with the inclusion of an 3936 explicit Token Option (Delta 9 + 2 = 11, Length 1, Value 0x20) in the 3937 request and (Delta 11 + 0 = 11) in the response, increasing the sizes 3938 to 18 and 12 bytes, respectively. 3940 Client Server 3941 | | 3942 | | 3943 +----->| Header: GET (T=CON, Code=1, MID=0x7d35) 3944 | GET | Token: 0x20 3945 | | Uri-Path: "temperature" 3946 | | 3947 | | 3948 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d35) 3949 | 2.05 | Token: 0x20 3950 | | Payload: "22.3 C" 3951 | | 3953 0 1 2 3 3954 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 3955 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3956 | 1 | 0 | 2 | GET=1 | MID=0x7d35 | 3957 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3958 | 9 | 11 | "temperature" (11 B) ... 3959 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3960 | 2 | 1 | 0x20 | 3961 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3963 0 1 2 3 3964 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 3965 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3966 | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | 3967 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3968 | 11 | 1 | 0x20 | "22.3 C" (6 B) ... 3969 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3971 Figure 13: Confirmable request; piggy-backed response 3973 In Figure 14, the Confirmable GET request is lost. After ACK_TIMEOUT 3974 seconds, the client retransmits the request, resulting in a piggy- 3975 backed response as in the previous example. 3977 Client Server 3978 | | 3979 | | 3980 +----X | Header: GET (T=CON, Code=1, MID=0x7d36) 3981 | GET | Token: 0x31 3982 | | Uri-Path: "temperature" 3983 TIMEOUT | 3984 | | 3985 +----->| Header: GET (T=CON, Code=1, MID=0x7d36) 3986 | GET | Token: 0x31 3987 | | Uri-Path: "temperature" 3988 | | 3989 | | 3990 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d36) 3991 | 2.05 | Token: 0x31 3992 | | Payload: "22.3 C" 3993 | | 3995 Figure 14: Confirmable request (retransmitted); piggy-backed response 3997 In Figure 15, the first Acknowledgement message from the server to 3998 the client is lost. After ACK_TIMEOUT seconds, the client 3999 retransmits the request. 4001 Client Server 4002 | | 4003 | | 4004 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 4005 | GET | Token: 0x42 4006 | | Uri-Path: "temperature" 4007 | | 4008 | | 4009 | X----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 4010 | 2.05 | Token: 0x42 4011 | | Payload: "22.3 C" 4012 TIMEOUT | 4013 | | 4014 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 4015 | GET | Token: 0x42 4016 | | Uri-Path: "temperature" 4017 | | 4018 | | 4019 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 4020 | 2.05 | Token: 0x42 4021 | | Payload: "22.3 C" 4022 | | 4024 Figure 15: Confirmable request; piggy-backed response (retransmitted) 4025 In Figure 16, the server acknowledges the Confirmable request and 4026 sends a 2.05 (Content) response separately in a Confirmable message. 4027 Note that the Acknowledgement message and the Confirmable response do 4028 not necessarily arrive in the same order as they were sent. The 4029 client acknowledges the Confirmable response. 4031 Client Server 4032 | | 4033 | | 4034 +----->| Header: GET (T=CON, Code=1, MID=0x7d38) 4035 | GET | Token: 0x53 4036 | | Uri-Path: "temperature" 4037 | | 4038 | | 4039 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d38) 4040 | | 4041 | | 4042 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7b) 4043 | 2.05 | Token: 0x53 4044 | | Payload: "22.3 C" 4045 | | 4046 | | 4047 +- - ->| Header: (T=ACK, Code=0, MID=0xad7b) 4048 | | 4050 Figure 16: Confirmable request; separate response 4052 Figure 17 shows an example where the client loses its state (e.g., 4053 crashes and is rebooted) right after sending a Confirmable request, 4054 so the separate response arriving some time later comes unexpected. 4055 In this case, the client rejects the Confirmable response with a 4056 Reset message. Note that the unexpected ACK is silently ignored. 4058 Client Server 4059 | | 4060 | | 4061 +----->| Header: GET (T=CON, Code=1, MID=0x7d39) 4062 | GET | Token: 0x64 4063 | | Uri-Path: "temperature" 4064 CRASH | 4065 | | 4066 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d39) 4067 | | 4068 | | 4069 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7c) 4070 | 2.05 | Token: 0x64 4071 | | Payload: "22.3 C" 4072 | | 4073 | | 4074 +- - ->| Header: (T=RST, Code=0, MID=0xad7c) 4075 | | 4077 Figure 17: Confirmable request; separate response (unexpected) 4079 Figure 18 shows a basic GET request where the request and the 4080 response are non-confirmable, so both may be lost without notice. 4082 Client Server 4083 | | 4084 | | 4085 +----->| Header: GET (T=NON, Code=1, MID=0x7d40) 4086 | GET | Token: 0x75 4087 | | Uri-Path: "temperature" 4088 | | 4089 | | 4090 |<-----+ Header: 2.05 Content (T=NON, Code=69, MID=0xad7d) 4091 | 2.05 | Token: 0x75 4092 | | Payload: "22.3 C" 4093 | | 4095 Figure 18: Non-confirmable request; Non-confirmable response 4097 In Figure 19, the client sends a Non-confirmable GET request to a 4098 multicast address: all nodes in link-local scope. There are 3 4099 servers on the link: A, B and C. Servers A and B have a matching 4100 resource, therefore they send back a Non-confirmable 2.05 (Content) 4101 response. The response sent by B is lost. C does not have matching 4102 response, therefore it sends a Non-confirmable 4.04 (Not Found) 4103 response. 4105 Client ff02::1 A B C 4106 | | | | | 4107 | | | | | 4108 +------>| | | | Header: GET (T=NON, Code=1, MID=0x7d41) 4109 | GET | | | | Token: 0x86 4110 | | | | Uri-Path: "temperature" 4111 | | | | 4112 | | | | 4113 |<------------+ | | Header: 2.05 (T=NON, Code=69, MID=0x60b1) 4114 | 2.05 | | | Token: 0x86 4115 | | | | Payload: "22.3 C" 4116 | | | | 4117 | | | | 4118 | X------------+ | Header: 2.05 (T=NON, Code=69, MID=0x01a0) 4119 | 2.05 | | | Token: 0x86 4120 | | | | Payload: "20.9 C" 4121 | | | | 4122 | | | | 4123 |<------------------+ Header: 4.04 (T=NON, Code=132, MID=0x952a) 4124 | 4.04 | | | Token: 0x86 4125 | | | | 4127 Figure 19: Non-confirmable request (multicast); Non-confirmable 4128 response 4130 Appendix B. URI Examples 4132 The following examples demonstrate different sets of Uri options, and 4133 the result after constructing an URI from them. 4135 o coap://[2001:db8::2:1]/ 4137 Destination IP Address = [2001:db8::2:1] 4139 Destination UDP Port = 5683 4141 o coap://example.net/ 4143 Destination IP Address = [2001:db8::2:1] 4145 Destination UDP Port = 5683 4147 Uri-Host = "example.net" 4149 o coap://example.net/.well-known/core 4150 Destination IP Address = [2001:db8::2:1] 4152 Destination UDP Port = 5683 4154 Uri-Host = "example.net" 4156 Uri-Path = ".well-known" 4158 Uri-Path = "core" 4160 o coap:// 4161 xn--18j4d.example/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF 4163 Destination IP Address = [2001:db8::2:1] 4165 Destination UDP Port = 5683 4167 Uri-Host = "xn--18j4d.example" 4169 Uri-Path = the string composed of the Unicode characters U+3053 4170 U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as 4171 E38193E38293E381ABE381A1E381AF hexadecimal 4173 o coap://198.51.100.1:61616//%2F//?%2F%2F&?%26 4175 Destination IP Address = 198.51.100.1 4177 Destination UDP Port = 61616 4179 Uri-Path = "" 4181 Uri-Path = "/" 4183 Uri-Path = "" 4185 Uri-Path = "" 4187 Uri-Query = "//" 4189 Uri-Query = "?&" 4191 Appendix C. Changelog 4193 Changed from ietf-10 to ietf-11: 4195 o Expanded section 4.8 on Transmission Parameters, and used the 4196 derived values defined there (#201). Changed parameter names to 4197 be shorter and more to the point. 4199 o Several more small editorial changes, clarifications and 4200 improvements have been made. 4202 Changed from ietf-09 to ietf-10: 4204 o Option deltas are restricted to 0 to 14; the option delta 15 is 4205 used exclusively for the end-of-options marker (#239). 4207 o Option numbers that are a multiple of 14 are not reserved, but are 4208 required to have an empty default value (#212). 4210 o Fixed misleading language that was introduced in 5.10.2 in coap-07 4211 re Uri-Host and Uri-Port (#208). 4213 o Segments and arguments can have a length of zero characters 4214 (#213). 4216 o The Location-* options describe together describe one location. 4217 The location is a relative URI, not an "absolute path URI" (#218). 4219 o The value of the Location-Path Option must not be '.' or '..' 4220 (#218). 4222 o Added a sentence on constructing URIs from Location-* options 4223 (#231). 4225 o Reserved option numbers for future Location-* options (#230). 4227 o Fixed response codes with payload inconsistency (#233). 4229 o Added advice on default values for critical options (#207). 4231 o Clarified use of identifiers in RawPublicKey Mode Provisioning 4232 (#222). 4234 o Moved "Securing CoAP" out of the "Security Considerations" (#229). 4236 o Added "All CoAP Nodes" multicast addresses to "IANA 4237 Considerations" (#216). 4239 o Over 100 small editorial changes, clarifications and improvements 4240 have been made. 4242 Changed from ietf-08 to ietf-09: 4244 o Improved consistency of statements about RST on NON: RST is a 4245 valid response to a NON message (#183). 4247 o Clarified that the protocol constants can be configured for 4248 specific application environments. 4250 o Added implementation note recommending piggy-backing whenever 4251 possible (#182). 4253 o Added a content-encoding column to the media type registry (#181). 4255 o Minor improvements to Appendix D. 4257 o Added text about multicast response suppression (#177). 4259 o Included the new End-of-options Marker (#176). 4261 o Added a reference to draft-ietf-tls-oob-pubkey and updated the RPK 4262 text accordingly. 4264 Changed from ietf-07 to ietf-08: 4266 o Clarified matching rules for messages (#175) 4268 o Fixed a bug in Section 8.2.2 on Etags (#168) 4270 o Added an IP address spoofing threat analysis contribution (#167) 4272 o Re-focused the security section on raw public keys (#166) 4274 o Added an 4.06 error to Accept (#165) 4276 Changed from ietf-06 to ietf-07: 4278 o application/link-format added to Media types registration (#160) 4280 o Moved content-type attribute to the document from link-format. 4282 o Added coaps scheme and DTLS-secured CoAP default port (#154) 4284 o Allowed 0-length Content-type options (#150) 4286 o Added congestion control recommendations (#153) 4288 o Improved text on PUT/POST response payloads (#149) 4290 o Added an Accept option for content-negotiation (#163) 4291 o Added If-Match and If-None-Match options (#155) 4293 o Improved Token Option explanation (#147) 4295 o Clarified mandatory to implement security (#156) 4297 o Added first come first server policy for 2-byte Media type codes 4298 (#161) 4300 o Clarify matching rules for messages and tokens (#151) 4302 o Changed OPTIONS and TRACE to always return 501 in HTTP-CoAP 4303 mapping (#164) 4305 Changed from ietf-05 to ietf-06: 4307 o HTTP mapping section improved with the minimal protocol standard 4308 text for CoAP-HTTP and HTTP-CoAP forward proxying (#137). 4310 o Eradicated percent-encoding by including one Uri-Query Option per 4311 &-delimited argument in a query. 4313 o Allowed RST message in reply to a NON message with unexpected 4314 token (#135). 4316 o Cache Invalidation only happens upon successful responses (#134). 4318 o 50% jitter added to the initial retransmit timer (#142). 4320 o DTLS cipher suites aligned with ZigBee IP, DTLS clarified as 4321 default CoAP security mechanism (#138, #139) 4323 o Added a minimal reference to draft-kivinen-ipsecme-ikev2-minimal 4324 (#140). 4326 o Clarified the comparison of UTF-8s (#136). 4328 o Minimized the initial media type registry (#101). 4330 Changed from ietf-04 to ietf-05: 4332 o Renamed Immediate into Piggy-backed and Deferred into Separate -- 4333 should finally end the confusion on what this is about. 4335 o GET requests now return a 2.05 (Content) response instead of 2.00 4336 (OK) response (#104). 4338 o Added text to allow 2.02 (Deleted) responses in reply to POST 4339 requests (#105). 4341 o Improved message deduplication rules (#106). 4343 o Section added on message size implementation considerations 4344 (#103). 4346 o Clarification made on human readable error payloads (#109). 4348 o Definition of CoAP methods improved (#108). 4350 o Max-Age removed from requests (#107). 4352 o Clarified uniqueness of tokens (#112). 4354 o Location-Query Option added (#113). 4356 o ETag length set to 1-8 bytes (#123). 4358 o Clarified relation between elective/critical and option numbers 4359 (#110). 4361 o Defined when to update Version header field (#111). 4363 o URI scheme registration improved (#102). 4365 o Added review guidelines for new CoAP codes and numbers. 4367 Changes from ietf-03 to ietf-04: 4369 o Major document reorganization (#51, #63, #71, #81). 4371 o Max-age length set to 0-4 bytes (#30). 4373 o Added variable unsigned integer definition (#31). 4375 o Clarification made on human readable error payloads (#50). 4377 o Definition of POST improved (#52). 4379 o Token length changed to 0-8 bytes (#53). 4381 o Section added on multiplexing CoAP, DTLS and STUN (#56). 4383 o Added cross-protocol attack considerations (#61). 4385 o Used new Immediate/Deferred response definitions (#73). 4387 o Improved request/response matching rules (#74). 4389 o Removed unnecessary media types and added recommendations for 4390 their use in M2M (#76). 4392 o Response codes changed to base 32 coding, new Y.XX naming (#77). 4394 o References updated as per AD review (#79). 4396 o IANA section completed (#80). 4398 o Proxy-Uri Option added to disambiguate between proxy and non-proxy 4399 requests (#82). 4401 o Added text on critical options in cached states (#83). 4403 o HTTP mapping sections improved (#88). 4405 o Added text on reverse proxies (#72). 4407 o Some security text on multicast added (#54). 4409 o Trust model text added to introduction (#58, #60). 4411 o AES-CCM vs. AES-CCB text added (#55). 4413 o Text added about device capabilities (#59). 4415 o DTLS section improvements (#87). 4417 o Caching semantics aligned with RFC2616 (#78). 4419 o Uri-Path Option split into multiple path segments. 4421 o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. 4423 Changes from ietf-02 to ietf-03: 4425 o Token Option and related use in asynchronous requests added (#25). 4427 o CoAP specific error codes added (#26). 4429 o Erroring out on unknown critical options changed to a MUST (#27). 4431 o Uri-Query Option added. 4433 o Terminology and definitions of URIs improved. 4435 o Security section completed (#22). 4437 Changes from ietf-01 to ietf-02: 4439 o Sending an error on a critical option clarified (#18). 4441 o Clarification on behavior of PUT and idempotent operations (#19). 4443 o Use of Uri-Authority clarified along with server processing rules; 4444 Uri-Scheme Option removed (#20, #23). 4446 o Resource discovery section removed to a separate CoRE Link Format 4447 draft (#21). 4449 o Initial security section outline added. 4451 Changes from ietf-00 to ietf-01: 4453 o New cleaner transaction message model and header (#5). 4455 o Removed subscription while being designed (#1). 4457 o Section 2 re-written (#3). 4459 o Text added about use of short URIs (#4). 4461 o Improved header option scheme (#5, #14). 4463 o Date option removed whiled being designed (#6). 4465 o New text for CoAP default port (#7). 4467 o Completed proxying section (#8). 4469 o Completed resource discovery section (#9). 4471 o Completed HTTP mapping section (#10). 4473 o Several new examples added (#11). 4475 o URI split into 3 options (#12). 4477 o MIME type defined for link-format (#13, #16). 4479 o New text on maximum message size (#15). 4481 o Location Option added. 4483 Changes from shelby-01 to ietf-00: 4485 o Removed the TCP binding section, left open for the future. 4487 o Fixed a bug in the example. 4489 o Marked current Sub/Notify as (Experimental) while under WG 4490 discussion. 4492 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 4493 CoAP-CoAP proxying to work). 4495 o Temporarily removed the Magic Byte header as TCP is no longer 4496 included as a binding. 4498 o Removed the Uri-code Option as different URI encoding schemes are 4499 being discussed. 4501 o Changed the rel= field to desc= for resource discovery. 4503 o Changed the maximum message size to 1024 bytes to allow for IP/UDP 4504 headers. 4506 o Made the URI slash optimization and method idempotence MUSTs 4508 o Minor editing and bug fixing. 4510 Changes from shelby-00 to shelby-01: 4512 o Unified the message header and added a notify message type. 4514 o Renamed methods with HTTP names and removed the NOTIFY method. 4516 o Added a number of options field to the header. 4518 o Combines the Option Type and Length into an 8-bit field. 4520 o Added the magic byte header. 4522 o Added new ETag Option. 4524 o Added new Date Option. 4526 o Added new Subscription Option. 4528 o Completed the HTTP Code - CoAP Code mapping table appendix. 4530 o Completed the Content-type Identifier appendix and tables. 4532 o Added more simplifications for URI support. 4534 o Initial subscription and discovery sections. 4536 o A Flag requirements simplified. 4538 Authors' Addresses 4540 Zach Shelby 4541 Sensinode 4542 Kidekuja 2 4543 Vuokatti 88600 4544 Finland 4546 Phone: +358407796297 4547 Email: zach@sensinode.com 4549 Klaus Hartke 4550 Universitaet Bremen TZI 4551 Postfach 330440 4552 Bremen D-28359 4553 Germany 4555 Phone: +49-421-218-63905 4556 Fax: +49-421-218-7000 4557 Email: hartke@tzi.org 4559 Carsten Bormann 4560 Universitaet Bremen TZI 4561 Postfach 330440 4562 Bremen D-28359 4563 Germany 4565 Phone: +49-421-218-63921 4566 Fax: +49-421-218-7000 4567 Email: cabo@tzi.org 4568 Brian Frank 4569 SkyFoundry 4570 Richmond, VA 4571 USA 4573 Phone: 4574 Email: brian@skyfoundry.com