idnits 2.17.1 draft-ietf-core-coap-12.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 4474 has weird spacing: '... Client ff02:...' -- The document date (October 1, 2012) is 4196 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 484, but not defined == Missing Reference: '0x01a0' is mentioned on line 499, but not defined == Missing Reference: '0xbc90' is mentioned on line 540, but not defined == Missing Reference: '0xbc91' is mentioned on line 540, but not defined == Missing Reference: '0x7a10' is mentioned on line 564, but not defined == Missing Reference: '0x23bb' is mentioned on line 575, but not defined == Missing Reference: '0x7a11' is mentioned on line 588, but not defined == Missing Reference: '0x23bc' is mentioned on line 593, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 4024, but not defined == Missing Reference: 'TBD1' is mentioned on line 4035, but not defined == Missing Reference: 'TBD2' is mentioned on line 4040, but not defined == 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-09 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-06 == Outdated reference: A later version (-01) exists of draft-kivinen-ipsecme-ikev2-minimal-00 == Outdated reference: A later version (-08) exists of draft-mcgrew-tls-aes-ccm-ecc-05 -- 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 (~~), 19 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: April 4, 2013 C. Bormann 6 Universitaet Bremen TZI 7 B. Frank 8 SkyFoundry 9 October 1, 2012 11 Constrained Application Protocol (CoAP) 12 draft-ietf-core-coap-12 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 endpoints, 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 April 4, 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 . . . . . . . . . . . . . . 10 71 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 11 72 2.2. Request/Response Model . . . . . . . . . . . . . . . . . 12 73 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 15 74 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . 15 75 3. Message Format . . . . . . . . . . . . . . . . . . . . . . . 15 76 3.1. Header Format . . . . . . . . . . . . . . . . . . . . . . 16 77 3.2. Option Format . . . . . . . . . . . . . . . . . . . . . . 17 78 3.3. Option Jump . . . . . . . . . . . . . . . . . . . . . . . 19 79 3.4. Option Value Formats . . . . . . . . . . . . . . . . . . 20 80 3.4.1. uint . . . . . . . . . . . . . . . . . . . . . . . . 21 81 3.4.2. string . . . . . . . . . . . . . . . . . . . . . . . 21 82 3.4.3. opaque . . . . . . . . . . . . . . . . . . . . . . . 21 83 3.4.4. empty . . . . . . . . . . . . . . . . . . . . . . . 22 84 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 22 85 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 22 86 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 23 87 4.3. Messages Transmitted Without Reliability . . . . . . . . 24 88 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 24 89 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 25 90 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 26 91 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 27 92 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 27 93 4.8.1. Changing The Parameters . . . . . . . . . . . . . . 28 94 4.8.2. Time Values derived from Transmission Parameters . . 29 95 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 31 96 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 31 97 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 31 98 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 32 99 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 33 100 5.2.3. Non-Confirmable . . . . . . . . . . . . . . . . . . 34 101 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 34 102 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 35 103 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . 37 104 5.4.2. Proxy Unsafe/Safe and Cache-Key . . . . . . . . . . 37 105 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 38 106 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 38 107 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 38 108 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 38 109 5.5. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 39 110 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 39 111 5.5.2. Diagnostic Message . . . . . . . . . . . . . . . . . 39 112 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 39 113 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . 40 114 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 40 115 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 41 116 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . 42 117 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . 43 118 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . 43 119 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 44 120 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 44 121 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 44 122 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . 45 123 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 45 124 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 45 125 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 45 126 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . 47 127 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . 48 128 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 49 129 5.10.1. Token . . . . . . . . . . . . . . . . . . . . . . . 50 130 5.10.2. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 50 131 5.10.3. Proxy-Uri . . . . . . . . . . . . . . . . . . . . . 51 132 5.10.4. Content-Format . . . . . . . . . . . . . . . . . . . 51 133 5.10.5. Accept . . . . . . . . . . . . . . . . . . . . . . . 52 134 5.10.6. Max-Age . . . . . . . . . . . . . . . . . . . . . . 52 135 5.10.7. ETag . . . . . . . . . . . . . . . . . . . . . . . . 52 136 5.10.8. Location-Path and Location-Query . . . . . . . . . . 53 137 5.10.9. If-Match . . . . . . . . . . . . . . . . . . . . . . 53 138 5.10.10. If-None-Match . . . . . . . . . . . . . . . . . . . 54 139 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 54 140 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 55 141 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 56 142 6.3. Normalization and Comparison Rules . . . . . . . . . . . 56 143 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 57 144 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 58 146 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 59 147 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 59 148 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 60 149 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 60 150 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 60 151 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 61 152 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 61 153 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . 62 154 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 62 155 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 63 156 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 64 157 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . 65 158 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 65 159 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . 66 160 9.2. Using CoAP with IPsec . . . . . . . . . . . . . . . . . . 68 161 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 68 162 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 69 163 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 70 164 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . 70 165 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 70 166 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 71 167 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 71 168 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . 71 169 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . 71 170 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 72 171 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 72 172 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . 73 173 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 73 174 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . 73 175 11. Security Considerations . . . . . . . . . . . . . . . . . . . 73 176 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . . 74 177 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 74 178 11.3. Risk of amplification . . . . . . . . . . . . . . . . . . 75 179 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . . 76 180 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 76 181 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 182 12.1. CoAP Code Registry . . . . . . . . . . . . . . . . . . . 78 183 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 79 184 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 80 185 12.2. Option Number Registry . . . . . . . . . . . . . . . . . 81 186 12.3. Content-Format Registry . . . . . . . . . . . . . . . . . 83 187 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 84 188 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 85 189 12.6. Service Name and Port Number Registration . . . . . . . . 86 190 12.7. Secure Service Name and Port Number Registration . . . . 87 191 12.8. Multicast Address Registration . . . . . . . . . . . . . 88 192 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 88 193 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 89 194 14.1. Normative References . . . . . . . . . . . . . . . . . . 89 195 14.2. Informative References . . . . . . . . . . . . . . . . . 91 196 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 93 197 Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 98 198 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 99 199 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 107 201 1. Introduction 203 The use of web services on the Internet has become ubiquitous in most 204 applications, and depends on the fundamental Representational State 205 Transfer [REST] architecture of the web. 207 The Constrained RESTful Environments (CoRE) work aims at realizing 208 the REST architecture in a suitable form for the most constrained 209 nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and 210 networks (e.g. 6LoWPAN, [RFC4944]). Constrained networks like 211 6LoWPAN support the expensive fragmentation of IPv6 packets into 212 small link-layer frames. One design goal of CoAP has been to keep 213 message overhead small, thus limiting the use of fragmentation. 215 One of the main goals of CoAP is to design a generic web protocol for 216 the special requirements of this constrained environment, especially 217 considering energy, building automation and other machine-to-machine 218 (M2M) applications. The goal of CoAP is not to blindly compress HTTP 219 [RFC2616], but rather to realize a subset of REST common with HTTP 220 but optimized for M2M applications. Although CoAP could be used for 221 compressing simple HTTP interfaces, it more importantly also offers 222 features for M2M such as built-in discovery, multicast support and 223 asynchronous message exchanges. 225 This document specifies the Constrained Application Protocol (CoAP), 226 which easily translates to HTTP for integration with the existing web 227 while meeting specialized requirements such as multicast support, 228 very low overhead and simplicity for constrained environments and M2M 229 applications. 231 1.1. Features 233 CoAP has the following main features: 235 o Constrained web protocol fulfilling M2M requirements. 237 o UDP binding with optional reliability supporting unicast and 238 multicast requests. 240 o Asynchronous message exchanges. 242 o Low header overhead and parsing complexity. 244 o URI and Content-type support. 246 o Simple proxy and caching capabilities. 248 o A stateless HTTP mapping, allowing proxies to be built providing 249 access to CoAP resources via HTTP in a uniform way or for HTTP 250 simple interfaces to be realized alternatively over CoAP. 252 o Security binding to Datagram Transport Layer Security (DTLS). 254 1.2. Terminology 256 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 257 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 258 "OPTIONAL" in this document are to be interpreted as described in 259 [RFC2119] when they appear in ALL CAPS. These words may also appear 260 in this document in lower case as plain English words, absent their 261 normative meanings. 263 This specification requires readers to be familiar with all the terms 264 and concepts that are discussed in [RFC2616]. In addition, this 265 specification defines the following terminology: 267 Endpoint 268 An entity participating in the CoAP protocol. Colloquially, an 269 endpoint lives on a "Node", although "Host" would be more 270 consistent with Internet standards usage, and is further 271 identified by transport layer multiplexing information that can 272 include a UDP port number and a security association 273 (Section 4.1). 275 Sender 276 The originating endpoint of a message. When the aspect of 277 identification of the specific sender is in focus, also "source 278 endpoint". 280 Recipient 281 The destination endpoint of a message. When the aspect of 282 identification of the specific recipient is in focus, also 283 "destination endpoint". 285 Client 286 The originating endpoint of a request; the destination endpoint of 287 a response. 289 Server 290 The destination endpoint of a request; the originating endpoint of 291 a response. 293 Origin Server 294 The server on which a given resource resides or is to be created. 296 Intermediary 297 A CoAP endpoint that acts both as a server and as a client towards 298 (possibly via further intermediaries) an origin server. A common 299 form of an intermediary is a proxy; several classes of such 300 proxies are discussed in this specification. 302 Proxy 303 An intermediary that mainly is concerned with forwarding requests 304 and relaying back responses, possibly performing caching, 305 namespace translation, or protocol translation in the process. As 306 opposed to intermediaries in the general sense, proxies generally 307 do not implement specific application semantics. Based on the 308 position in the overall structure of the request forwarding, there 309 are two common forms of proxy: forward-proxy and reverse-proxy. 310 In some cases, a single endpoint might act as an origin server, 311 forward-proxy, or reverse-proxy, switching behavior based on the 312 nature of each request. 314 Forward-Proxy 315 A "forward-proxy" is an endpoint selected by a client, usually via 316 local configuration rules, to perform requests on behalf of the 317 client, doing any necessary translations. Some translations are 318 minimal, such as for proxy requests for "coap" URIs, whereas other 319 requests might require translation to and from entirely different 320 application-layer protocols. 322 Reverse-Proxy 323 A "reverse-proxy" is an endpoint that stands in for one or more 324 other server(s) and satisfies requests on behalf of these, doing 325 any necessary translations. Unlike a forward-proxy, the client 326 may not be aware that it is communicating with a reverse-proxy; a 327 reverse-proxy receives requests as if it was the origin server for 328 the target resource. 330 Cross-Proxy 331 A cross-protocol proxy, or "cross-proxy" for short, is a proxy 332 that translates between different protocols, such as a CoAP-to- 333 HTTP proxy or an HTTP-to-CoAP proxy. While this specification 334 makes very specific demands of CoAP-to-CoAP proxies, there is more 335 variation possible in cross-proxies. 337 Confirmable Message 338 Some messages require an acknowledgement. These messages are 339 called "Confirmable". When no packets are lost, each confirmable 340 message elicits exactly one return message of type Acknowledgement 341 or type Reset. 343 Non-Confirmable Message 344 Some other messages do not require an acknowledgement. This is 345 particularly true for messages that are repeated regularly for 346 application requirements, such as repeated readings from a sensor 347 where eventual success is sufficient. 349 Acknowledgement Message 350 An Acknowledgement message acknowledges that a specific 351 Confirmable Message arrived. It does not indicate success or 352 failure of any encapsulated request. 354 Reset Message 355 A Reset message indicates that a specific message (confirmable or 356 non-confirmable) was received, but some context is missing to 357 properly process it. This condition is usually caused when the 358 receiving node has rebooted and has forgotten some state that 359 would be required to interpret the message. 361 Piggy-backed Response 362 A Piggy-backed Response is included right in a CoAP 363 Acknowledgement (ACK) message that is sent to acknowledge receipt 364 of the Request for this Response (Section 5.2.1). 366 Separate Response 367 When a Confirmable message carrying a Request is acknowledged with 368 an empty message (e.g., because the server doesn't have the answer 369 right away), a Separate Response is sent in a separate message 370 exchange (Section 5.2.2). 372 Critical Option 373 An option that would need to be understood by the endpoint 374 receiving the message in order to properly process the message 375 (Section 5.4.1). Note that the implementation of critical options 376 is, as the name "Option" implies, generally optional: unsupported 377 critical options lead to an error response or summary rejection of 378 the message. 380 Elective Option 381 An option that is intended to be ignored by an endpoint that does 382 not understand it. Processing the message even without 383 understanding the option is acceptable (Section 5.4.1). 385 Unsafe Option 386 An option that would need to be understood by a proxy receiving 387 the message in order to safely forward the message 388 (Section 5.4.2). 390 Safe Option 391 An option that is intended to be safe for forwarding by a proxy 392 that does not understand it. Forwarding the message even without 393 understanding the option is acceptable (Section 5.4.2). 395 Resource Discovery 396 The process where a CoAP client queries a server for its list of 397 hosted resources (i.e., links, Section 7). 399 Content-Format 400 The combination of an Internet media type, potentially with 401 specific parameters given, and a content-coding (which is often 402 the identity content-coding), identified by a numeric identifier 403 defined by the CoAP Content-Format registry. 405 In this specification, the term "byte" is used in its now customary 406 sense as a synonym for "octet". 408 All multi-byte integers in this protocol are interpreted in network 409 byte order. 411 Where arithmetic is used, this specification uses the notation 412 familiar from the programming language C, except that the operator 413 "**" stands for exponentiation. 415 2. Constrained Application Protocol 417 The interaction model of CoAP is similar to the client/server model 418 of HTTP. However, machine-to-machine interactions typically result 419 in a CoAP implementation acting in both client and server roles. A 420 CoAP request is equivalent to that of HTTP, and is sent by a client 421 to request an action (using a method code) on a resource (identified 422 by a URI) on a server. The server then sends a response with a 423 response code; this response may include a resource representation. 425 Unlike HTTP, CoAP deals with these interchanges asynchronously over a 426 datagram-oriented transport such as UDP. This is done logically 427 using a layer of messages that supports optional reliability (with 428 exponential back-off). CoAP defines four types of messages: 429 Confirmable, Non-Confirmable, Acknowledgement, Reset; method codes 430 and response codes included in some of these messages make them carry 431 requests or responses. The basic exchanges of the four types of 432 messages are somewhat orthogonal to the request/response 433 interactions; requests can be carried in Confirmable and Non- 434 Confirmable messages, and responses can be carried in these as well 435 as piggy-backed in Acknowledgement messages. 437 One could think of CoAP logically as using a two-layer approach, a 438 CoAP messaging layer used to deal with UDP and the asynchronous 439 nature of the interactions, and the request/response interactions 440 using Method and Response codes (see Figure 1). CoAP is however a 441 single protocol, with messaging and request/response just features of 442 the CoAP header. 444 +----------------------+ 445 | Application | 446 +----------------------+ 447 +----------------------+ \ 448 | Requests/Responses | | 449 |----------------------| | CoAP 450 | Messages | | 451 +----------------------+ / 452 +----------------------+ 453 | UDP | 454 +----------------------+ 456 Figure 1: Abstract layering of CoAP 458 2.1. Messaging Model 460 The CoAP messaging model is based on the exchange of messages over 461 UDP between endpoints. 463 CoAP uses a short fixed-length binary header (4 bytes) that may be 464 followed by compact binary options and a payload. This message 465 format is shared by requests and responses. The CoAP message format 466 is specified in Section 3. Each message contains a Message ID used 467 to detect duplicates and for optional reliability. 469 Reliability is provided by marking a message as Confirmable (CON). A 470 Confirmable message is retransmitted using a default timeout and 471 exponential back-off between retransmissions, until the recipient 472 sends an Acknowledgement message (ACK) with the same Message ID (for 473 example, 0x7d34) from the corresponding endpoint; see Figure 2. When 474 a recipient is not at all able to process a Confirmable message 475 (i.e., not even able to provide a suitable error response), it 476 replies with a Reset message (RST) instead of an Acknowledgement 477 (ACK). 479 Client Server 480 | | 481 | CON [0x7d34] | 482 +----------------->| 483 | | 484 | ACK [0x7d34] | 485 |<-----------------+ 486 | | 488 Figure 2: Reliable message transmission 490 A message that does not require reliable transmission, for example 491 each single measurement out of a stream of sensor data, can be sent 492 as a Non-confirmable message (NON). These are not acknowledged, but 493 still have a Message ID for duplicate detection; see Figure 3. When 494 a recipient is not able to process a Non-confirmable message, it may 495 reply with a Reset message (RST). 497 Client Server 498 | | 499 | NON [0x01a0] | 500 +----------------->| 501 | | 503 Figure 3: Unreliable message transmission 505 See Section 4 for details of CoAP messages. 507 As CoAP is based on UDP, it also supports the use of multicast IP 508 destination addresses, enabling multicast CoAP requests. Section 8 509 discusses the proper use of CoAP messages with multicast addresses 510 and precautions for avoiding response congestion. 512 Several security modes are defined for CoAP in Section 9 ranging from 513 no security to certificate-based security. The use of IPsec along 514 with a binding to DTLS are specified for securing the protocol. 516 2.2. Request/Response Model 518 CoAP request and response semantics are carried in CoAP messages, 519 which include either a Method code or Response code, respectively. 520 Optional (or default) request and response information, such as the 521 URI and payload media type are carried as CoAP options. A Token 522 Option is used to match responses to requests independently from the 523 underlying messages (Section 5.3). 525 A request is carried in a Confirmable (CON) or Non-confirmable (NON) 526 message, and if immediately available, the response to a request 527 carried in a Confirmable message is carried in the resulting 528 Acknowledgement (ACK) message. This is called a piggy-backed 529 response, detailed in Section 5.2.1. Two examples for a basic GET 530 request with piggy-backed response are shown in Figure 4, one 531 successful, one resulting in a 4.04 (Not Found) response. 533 Client Server Client Server 534 | | | | 535 | CON [0xbc90] | | CON [0xbc91] | 536 | GET /temperature | | GET /temperature | 537 | (Token 0x71) | | (Token 0x72) | 538 +----------------->| +----------------->| 539 | | | | 540 | ACK [0xbc90] | | ACK [0xbc91] | 541 | 2.05 Content | | 4.04 Not Found | 542 | (Token 0x71) | | (Token 0x72) | 543 | "22.5 C" | | "Not found" | 544 |<-----------------+ |<-----------------+ 545 | | | | 547 Figure 4: Two GET requests with piggy-backed responses 549 If the server is not able to respond immediately to a request carried 550 in a Confirmable message, it simply responds with an empty 551 Acknowledgement message so that the client can stop retransmitting 552 the request. When the response is ready, the server sends it in a 553 new Confirmable message (which then in turn needs to be acknowledged 554 by the client). This is called a separate response, as illustrated 555 in Figure 5 and described in more detail in Section 5.2.2. 557 Client Server 558 | | 559 | CON [0x7a10] | 560 | GET /temperature | 561 | (Token 0x73) | 562 +----------------->| 563 | | 564 | ACK [0x7a10] | 565 |<-----------------+ 566 | | 567 ... Time Passes ... 568 | | 569 | CON [0x23bb] | 570 | 2.05 Content | 571 | (Token 0x73) | 572 | "22.5 C" | 573 |<-----------------+ 574 | | 575 | ACK [0x23bb] | 576 +----------------->| 577 | | 579 Figure 5: A GET request with a separate response 581 Likewise, if a request is sent in a Non-Confirmable message, then the 582 response is usually sent using a new Non-Confirmable message, 583 although the server may send a Confirmable message. This type of 584 exchange is illustrated in Figure 6. 586 Client Server 587 | | 588 | NON [0x7a11] | 589 | GET /temperature | 590 | (Token 0x74) | 591 +----------------->| 592 | | 593 | NON [0x23bc] | 594 | 2.05 Content | 595 | (Token 0x74) | 596 | "22.5 C" | 597 |<-----------------+ 598 | | 600 Figure 6: A NON request and response 602 CoAP makes use of GET, PUT, POST and DELETE methods in a similar 603 manner to HTTP, with the semantics specified in Section 5.8. (Note 604 that the detailed semantics of CoAP methods are "almost, but not 605 entirely unlike" those of HTTP methods: Intuition taken from HTTP 606 experience generally does apply well, but there are enough 607 differences that make it worthwhile to actually read the present 608 specification.) 610 URI support in a server is simplified as the client already parses 611 the URI and splits it into host, port, path and query components, 612 making use of default values for efficiency. Response codes 613 correspond to a small subset of HTTP response codes with a few CoAP 614 specific codes added, as defined in Section 5.9. 616 2.3. Intermediaries and Caching 618 The protocol supports the caching of responses in order to 619 efficiently fulfill requests. Simple caching is enabled using 620 freshness and validity information carried with CoAP responses. A 621 cache could be located in an endpoint or an intermediary. Caching 622 functionality is specified in Section 5.6. 624 Proxying is useful in constrained networks for several reasons, 625 including network traffic limiting, to improve performance, to access 626 resources of sleeping devices or for security reasons. The proxying 627 of requests on behalf of another CoAP endpoint is supported in the 628 protocol. When using a proxy, the URI of the resource to request is 629 included in the request, while the destination IP address is set to 630 the address of the proxy. See Section 5.7 for more information on 631 proxy functionality. 633 As CoAP was designed according to the REST architecture and thus 634 exhibits functionality similar to that of the HTTP protocol, it is 635 quite straightforward to map from CoAP to HTTP and from HTTP to CoAP. 636 Such a mapping may be used to realize an HTTP REST interface using 637 CoAP, or for converting between HTTP and CoAP. This conversion can 638 be carried out by a cross-protocol proxy ("cross-proxy"), which 639 converts the method or response code, media type, and options to the 640 corresponding HTTP feature. Section 10 provides more detail about 641 HTTP mapping. 643 2.4. Resource Discovery 645 Resource discovery is important for machine-to-machine interactions, 646 and is supported using the CoRE Link Format [RFC6690] as discussed in 647 Section 7. 649 3. Message Format 651 CoAP is based on the exchange of short messages which, by default, 652 are transported over UDP (i.e. each CoAP message occupies the data 653 section of one UDP datagram). CoAP may also be used over Datagram 654 Transport Layer Security (DTLS) (see Section 9.1). It could also be 655 used over other transports such as SMS, TCP or SCTP, the 656 specification of which is out of this document's scope. 658 CoAP messages are encoded in a simple binary format. A message 659 consists of a fixed-sized CoAP Header followed by options in Type- 660 Length-Value (TLV) format and a payload. The number of options is 661 determined by the header. The payload is made up of the bytes after 662 the options, if any; its length is calculated from the datagram 663 length. 665 0 1 2 3 666 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 667 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 668 |Ver| T | OC | Code | Message ID | 669 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 670 | Options (if any) ... 671 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 672 | Payload (if any) ... 673 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 675 Figure 7: Message Format 677 3.1. Header Format 679 The fields in the header are defined as follows: 681 Version (Ver): 2-bit unsigned integer. Indicates the CoAP version 682 number. Implementations of this specification MUST set this field 683 to 1. Other values are reserved for future versions. 685 Type (T): 2-bit unsigned integer. Indicates if this message is of 686 type Confirmable (0), Non-Confirmable (1), Acknowledgement (2) or 687 Reset (3). See Section 4 for the semantics of these message 688 types. 690 Option Count (OC): 4-bit unsigned integer. Indicates the number of 691 options after the header (0-14). If set to 0, there are no 692 options and the payload (if any) immediately follows the header. 693 If set to 15, then an end-of-options marker is used to indicate 694 the end of options and the start of the payload. The format of 695 options is defined below. 697 Code: 8-bit unsigned integer. Indicates if the message carries a 698 request (1-31) or a response (64-191), or is empty (0). (All 699 other code values are reserved.) In case of a request, the Code 700 field indicates the Request Method; in case of a response a 701 Response Code. Possible values are maintained in the CoAP Code 702 Registry (Section 12.1). See Section 5 for the semantics of 703 requests and responses. 705 Message ID: 16-bit unsigned integer in network byte order. Used for 706 the detection of message duplication, and to match messages of 707 type Acknowledgement/Reset and messages of type Confirmable/ 708 Non-confirmable. See Section 4 for Message ID generation rules 709 and how messages are matched. 711 3.2. Option Format 713 Options MUST appear in order of their Option Number (see 714 Section 5.4.6). A delta encoding is used between options: The Option 715 Number for each Option is calculated as the sum of its Option Delta 716 field and the Option Number of the preceding Option in the message, 717 if any. For the first Option in the message, the Option Delta 718 becomes the Option Number (i.e., an implementation can simply 719 initialize the number variable as zero). Multiple options with the 720 same Option Number can be included by using an Option Delta of zero. 721 The Option Jump mechanism (Section 3.3) is used when the delta to the 722 next option number is greater than 14. 724 Following the Option Delta, each option has a Length field which 725 specifies the length of the Option Value, in bytes. The Length field 726 can be extended for options with values longer than 14 bytes by 727 adding extension bytes. The maximum length for an option is 1034 728 bytes. The Option Value immediately follows the Length field. 730 for 0..14: 731 0 1 2 3 4 5 6 7 732 +---+---+---+---+---+---+---+---+ 733 | Option Delta | Length | 734 +---+---+---+---+---+---+---+---+ 735 | Option Value ... 736 +---+---+---+---+---+---+---+---+ 738 for 15..269: 739 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 740 | Option Delta | 1 1 1 1 | Length - 15 | 741 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 742 | Option Value ... 743 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 745 for 270..524: 746 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 747 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 748 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 749 | Length - 270 | Option Value ... 750 +---+---+---+---+---+---+---+---+ 751 | 752 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 754 for 525..779: 755 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 756 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 757 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 758 | 1 1 1 1 1 1 1 1 | Length - 525 | 759 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 760 | Option Value ... 761 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 763 for 780..1034: 764 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 765 | Option Delta | 1 1 1 1 | 1 1 1 1 1 1 1 1 | 766 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 767 | 1 1 1 1 1 1 1 1 | 1 1 1 1 1 1 1 1 | 768 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 769 | Length - 780 | Option Value ... 770 +---+---+---+---+---+---+---+---+ 771 | 772 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 774 Figure 8: Option Format 776 The fields in an option are defined as follows: 778 Option Delta: 4-bit unsigned integer. Indicates the difference 779 between the Option Number of this option and the previous option 780 (or zero for the first option). In other words, the Option Number 781 is calculated by simply summing the Option Delta fields of this 782 and previous options before it. The Option Delta 15 is reserved 783 for special constructs such as the end-of-options marker (see 784 below) and Option Jumps. The Option Jump mechanism (Section 3.3) 785 is used when the delta to the next option number is larger than 786 14. 788 Length: Indicates the length of the Option Value, in bytes. 789 Normally Length is a 4-bit unsigned integer allowing value lengths 790 of 0-14 bytes. When the Length field is set to 15, another byte 791 is added as an 8-bit unsigned integer whose value is added to the 792 15, allowing option value lengths of 15-270 bytes. For option 793 lengths beyond 270 bytes, we reserve the value 255 of an extension 794 byte to mean "add 255, read another extension byte". Options that 795 are longer than 1034 bytes MUST NOT be sent; an option that has 796 255 (all one bits) in the field called "Length - 780" MUST be 797 rejected upon reception as an encoding error. 799 Value: The length and format of the Option Value depends on the 800 respective option, which MAY define variable length values. See 801 Section 3.4 for the formats the options defined in this document 802 make use of; other options MAY make use of other option value 803 formats. 805 If the Option Count field in the CoAP header is 15 and the Option 806 Header byte is 0xf0 (the Option Delta is 15 and the Option Length is 807 0), the option is interpreted as the end-of-options marker instead of 808 the option with the resulting Option Number. (In other words, the 809 end-of-options marker always is just a single byte valued 0xf0.) 810 When this marker is encountered, it is immediately followed by the 811 payload (if any). (Note that, by this special meaning, the Option 812 Delta of 15 is made special, not any specific Option Number.) The 813 sender MUST NOT include the end-of-options marker in an Option in a 814 message with an Option Count other than 15; recipients MUST treat 815 this as an encoding error. 817 Option Numbers are maintained in the CoAP Option Number Registry 818 (Section 12.2). See Section 5.10 for the semantics of the options 819 defined in this document. 821 3.3. Option Jump 823 The following construct can occur in front of any Option: 825 0 1 2 3 4 5 6 7 826 +---+---+---+---+---+---+---+---+ 827 | 1 1 1 1 | 0 0 0 1 | 0xf1 (Delta = 15) 828 +---+---+---+---+---+---+---+---+ 830 0 1 2 3 4 5 6 7 831 +---+---+---+---+---+---+---+---+ 832 | 1 1 1 1 | 0 0 1 0 | 0xf2 833 +---+---+---+---+---+---+---+---+ 834 | Option Jump Value | (Delta/8)-2 835 +---+---+---+---+---+---+---+---+ 837 0 1 2 3 4 5 6 7 838 +---+---+---+---+---+---+---+---+ 839 | 1 1 1 1 | 0 0 1 1 | 0xf3 840 +---+---+---+---+---+---+---+---+ 841 | | 842 +--- Option Jump Value ---+ (Delta/8)-258 843 | | 844 +---+---+---+---+---+---+---+---+ 846 Figure 9: Option Jump Format 848 This construct is not by itself an Option. It can occur in front of 849 any Option to increase the current Option number that then goes into 850 its Option number calculation. The increase is done by 15 or in 851 multiples of eight. For the formats that include an Option Jump 852 Value, the actual addition to the current Option number is computed 853 as follows: 855 Delta = ((Option Jump Value) + N) * 8 857 where N is 2 for the one-byte version and N is 258 for the two-byte 858 version. 860 An Option Jump MUST be followed by an actual Option, i.e., it MUST 861 NOT be followed by another Option Jump or an end-of-options 862 indicator. A message violating this MUST be treated as an encoding 863 error. 865 Option Jumps do NOT count as Options in the Option Count field of the 866 header (i.e., they cannot by themselves end the Option sequence). 868 3.4. Option Value Formats 870 The options defined in this document make use of the following option 871 value formats. 873 3.4.1. uint 875 A non-negative integer which is represented in network byte order 876 using the given number of bytes. An option definition may specify a 877 range of permissible numbers of bytes; if it has a choice, a sender 878 SHOULD represent the integer with as few bytes as possible, i.e., 879 without leading zeros. A recipient MUST be prepared to process 880 values with leading zeros. 882 Implementation Note: The exceptional behavior permitted above is for 883 highly constrained templated implementations (e.g. hardware 884 implementations) that use fixed size options in the templates. 886 Length = 0 (implies value of 0) 888 0 889 0 1 2 3 4 5 6 7 890 +-+-+-+-+-+-+-+-+ 891 Length = 1 | 0-255 | 892 +-+-+-+-+-+-+-+-+ 894 0 1 895 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 896 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 897 Length = 2 | 0-65535 | 898 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 900 Length = 3 is 24 bits, Length = 4 is 32 bits etc. 902 3.4.2. string 904 A Unicode string which is encoded using UTF-8 [RFC3629] in Net- 905 Unicode form [RFC5198]. Note that here and in all other places where 906 UTF-8 encoding is used in the CoAP protocol, the intention is that 907 the encoded strings can be directly used and compared as opaque byte 908 strings by CoAP protocol implementations. There is no expectation 909 and no need to perform normalization within a CoAP implementation 910 unless Unicode strings that are not known to be normalized are 911 imported from sources outside the CoAP protocol. Note also that 912 ASCII strings (that do not make use of special control characters) 913 are always valid UTF-8 Net-Unicode strings. 915 3.4.3. opaque 917 An opaque sequence of bytes. 919 3.4.4. empty 921 A zero-length sequence of bytes. 923 4. Message Transmission 925 CoAP messages are exchanged asynchronously between CoAP endpoints. 926 They are used to transport CoAP requests and responses, the semantics 927 of which are defined in Section 5. 929 As CoAP is bound to non-reliable transports such as UDP, CoAP 930 messages may arrive out of order, appear duplicated, or go missing 931 without notice. For this reason, CoAP implements a lightweight 932 reliability mechanism, without trying to re-create the full feature 933 set of a transport like TCP. It has the following features: 935 o Simple stop-and-wait retransmission reliability with exponential 936 back-off for Confirmable messages. 938 o Duplicate detection for both Confirmable and Non-confirmable 939 messages. 941 4.1. Messages and Endpoints 943 A CoAP endpoint is the source or destination of a CoAP message. It 944 is identified depending on the security mode used (see Section 9): 945 With no security, the endpoint is solely identified by an IP address 946 and a UDP port number. With other security modes, the endpoint is 947 identified as defined by the security mode. 949 There are different types of messages. The type of a message is 950 specified by the T field of the CoAP header. 952 Separate from the message type, a message may carry a request, a 953 response, or be empty. This is signaled by the Code field in the 954 CoAP header and is relevant to the request/response model. Possible 955 values for the Code field are maintained by the CoAP Code Registry 956 (Section 12.1). 958 An empty message has the Code field set to 0. The OC field SHOULD be 959 set to 0 and no bytes SHOULD be present after the Message ID field. 960 The OC field and any bytes trailing the header MUST be ignored by any 961 recipient. 963 4.2. Messages Transmitted Reliably 965 The reliable transmission of a message is initiated by marking the 966 message as Confirmable in the CoAP header. A Confirmable message 967 always carries either a request or response and MUST NOT be empty. A 968 recipient MUST acknowledge such a message with an Acknowledgement 969 message or, if it lacks context to process the message properly 970 (including the case where the message is empty or has an encoding 971 error), MUST reject it; rejecting a Confirmable message is effected 972 by sending a matching Reset message and otherwise ignoring it. The 973 Acknowledgement message MUST echo the Message ID of the Confirmable 974 message, and MUST carry a response or be empty (see Section 5.2.1 and 975 Section 5.2.2). The Reset message MUST echo the Message ID of the 976 confirmable message, and MUST be empty. Rejecting an Acknowledgement 977 or Reset message is effected by silently ignoring it. 979 The sender retransmits the Confirmable message at exponentially 980 increasing intervals, until it receives an acknowledgement (or Reset 981 message), or runs out of attempts. 983 Retransmission is controlled by two things that a CoAP endpoint MUST 984 keep track of for each Confirmable message it sends while waiting for 985 an acknowledgement (or reset): a timeout and a retransmission 986 counter. For a new Confirmable message, the initial timeout is set 987 to a random number between ACK_TIMEOUT and (ACK_TIMEOUT * 988 ACK_RANDOM_FACTOR) (see Section 4.8), and the retransmission counter 989 is set to 0. When the timeout is triggered and the retransmission 990 counter is less than MAX_RETRANSMIT, the message is retransmitted, 991 the retransmission counter is incremented, and the timeout is 992 doubled. If the retransmission counter reaches MAX_RETRANSMIT on a 993 timeout, or if the endpoint receives a Reset message, then the 994 attempt to transmit the message is canceled and the application 995 process informed of failure. On the other hand, if the endpoint 996 receives an acknowledgement message in time, transmission is 997 considered successful. 999 A CoAP endpoint that sent a Confirmable message MAY give up in 1000 attempting to obtain an ACK even before the MAX_RETRANSMIT counter 1001 value is reached: E.g., the application has canceled the request as 1002 it no longer needs a response, or there is some other indication that 1003 the CON message did arrive. In particular, a CoAP request message 1004 may have elicited a separate response, in which case it is clear to 1005 the requester that only the ACK was lost and a retransmission of the 1006 request would serve no purpose. However, a responder MUST NOT in 1007 turn rely on this cross-layer behavior from a requester, i.e. it 1008 SHOULD retain the state to create the ACK for the request, if needed, 1009 even if a Confirmable response was already acknowledged by the 1010 requester. 1012 4.3. Messages Transmitted Without Reliability 1014 Some messages do not require an acknowledgement. This is 1015 particularly true for messages that are repeated regularly for 1016 application requirements, such as repeated readings from a sensor 1017 where eventual success is sufficient. 1019 As a more lightweight alternative, a message can be transmitted less 1020 reliably by marking the message as Non-confirmable. A Non- 1021 confirmable message always carries either a request or response and 1022 MUST NOT be empty. A Non-confirmable message MUST NOT be 1023 acknowledged by the recipient. If a recipient lacks context to 1024 process the message properly (including the case where the message is 1025 empty or has an encoding error), it MUST reject the message; 1026 rejecting a Non-Confirmable message MAY involve sending a matching 1027 Reset message, and apart from the Reset message the rejected message 1028 MUST be silently ignored. 1030 At the CoAP level, there is no way for the sender to detect if a Non- 1031 confirmable message was received or not. A sender MAY choose to 1032 transmit multiple copies of a Non-confirmable message within 1033 MAX_TRANSMIT_SPAN, or the network may duplicate the message in 1034 transit. To enable the receiver to act only once on the message, 1035 Non-confirmable messages specify a Message ID as well. (This Message 1036 ID is drawn from the same number space as the Message IDs for 1037 Confirmable messages.) 1039 4.4. Message Correlation 1041 An Acknowledgement or Reset message is related to a Confirmable 1042 message or Non-confirmable message by means of a Message ID along 1043 with additional address information of the corresponding endpoint. 1044 The Message ID is a 16-bit unsigned integer that is generated by the 1045 sender of a Confirmable or Non-confirmable message and included in 1046 the CoAP header. The Message ID MUST be echoed in the 1047 Acknowledgement or Reset message by the recipient. 1049 The same Message ID MUST NOT be re-used (in communicating with the 1050 same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2). 1052 Implementation Note: Several implementation strategies can be 1053 employed for generating Message IDs. In the simplest case a CoAP 1054 endpoint generates Message IDs by keeping a single Message ID 1055 variable, which is changed each time a new confirmable or non- 1056 confirmable message is sent regardless of the destination address 1057 or port. Endpoints dealing with large numbers of transactions 1058 could keep multiple Message ID variables, for example per prefix 1059 or destination address. The initial variable value should be 1060 randomized. 1062 For an Acknowledgement or Reset message to match a Confirmable or 1063 Non-confirmable message, the Message ID and source endpoint of the 1064 Acknowledgement or Reset message MUST match the Message ID and 1065 destination endpoint of the Confirmable or Non-confirmable message. 1067 4.5. Message Deduplication 1069 A recipient MUST be prepared to receive the same Confirmable message 1070 (as indicated by the Message ID and source endpoint) multiple times 1071 within the EXCHANGE_LIFETIME (Section 4.8.2), for example, when its 1072 Acknowledgement went missing or didn't reach the original sender 1073 before the first timeout. The recipient SHOULD acknowledge each 1074 duplicate copy of a Confirmable message using the same 1075 Acknowledgement or Reset message, but SHOULD process any request or 1076 response in the message only once. This rule MAY be relaxed in case 1077 the Confirmable message transports a request that is idempotent (see 1078 Section 5.1) or can be handled in an idempotent fashion. Examples 1079 for relaxed message deduplication: 1081 o A server MAY relax the requirement to answer all retransmissions 1082 of an idempotent request with the same response (Section 4.2), so 1083 that it does not have to maintain state for Message IDs. For 1084 example, an implementation might want to process duplicate 1085 transmissions of a GET, PUT or DELETE request as separate requests 1086 if the effort incurred by duplicate processing is less expensive 1087 than keeping track of previous responses would be. 1089 o A constrained server MAY even want to relax this requirement for 1090 certain non-idempotent requests if the application semantics make 1091 this trade-off favorable. For example, if the result of a POST 1092 request is just the creation of some short-lived state at the 1093 server, it may be less expensive to incur this effort multiple 1094 times for a request than keeping track of whether a previous 1095 transmission of the same request already was processed. 1097 A recipient MUST be prepared to receive the same Non-confirmable 1098 message (as indicated by the Message ID and source endpoint) multiple 1099 times within NON_LIFETIME (Section 4.8.2). As a general rule that 1100 may be relaxed based on the specific semantics of a message, the 1101 recipient SHOULD silently ignore any duplicated Non-confirmable 1102 message, and SHOULD process any request or response in the message 1103 only once. 1105 4.6. Message Size 1107 While specific link layers make it beneficial to keep CoAP messages 1108 small enough to fit into their link layer packets (see Section 1), 1109 this is a matter of implementation quality. The CoAP specification 1110 itself provides only an upper bound to the message size. Messages 1111 larger than an IP fragment result in undesired packet fragmentation. 1112 A CoAP message, appropriately encapsulated, SHOULD fit within a 1113 single IP packet (i.e., avoid IP fragmentation) and (by fitting into 1114 one UDP payload) obviously MUST fit within a single IP datagram. If 1115 the Path MTU is not known for a destination, an IP MTU of 1280 bytes 1116 SHOULD be assumed; if nothing is known about the size of the headers, 1117 good upper bounds are 1152 bytes for the message size and 1024 bytes 1118 for the payload size. 1120 Implementation Note: CoAP's choice of message size parameters works 1121 well with IPv6 and with most of today's IPv4 paths. (However, 1122 with IPv4, it is harder to absolutely ensure that there is no IP 1123 fragmentation. If IPv4 support on unusual networks is a 1124 consideration, implementations may want to limit themselves to 1125 more conservative IPv4 datagram sizes such as 576 bytes; worse, 1126 the absolute minimum value of the IP MTU for IPv4 is as low as 68 1127 bytes, which would leave only 40 bytes minus security overhead for 1128 a UDP payload. Implementations extremely focused on this problem 1129 set might also set the IPv4 DF bit and perform some form of path 1130 MTU discovery; this should generally be unnecessary in most 1131 realistic use cases for CoAP, however.) A more important kind of 1132 fragmentation in many constrained networks is that on the 1133 adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 1134 bytes including various overheads); this may motivate 1135 implementations to be frugal in their packet sizes and to move to 1136 block-wise transfers [I-D.ietf-core-block] when approaching three- 1137 digit message sizes. 1139 Message sizes are also of considerable importance to 1140 implementations on constrained nodes. Many implementations will 1141 need to allocate a buffer for incoming messages. If an 1142 implementation is too constrained to allow for allocating the 1143 above-mentioned upper bound, it could apply the following 1144 implementation strategy: Implementations receiving a datagram into 1145 a buffer that is too small are usually able to determine if the 1146 trailing portion of a datagram was discarded and to retrieve the 1147 initial portion. So, if not all of the payload, at least the CoAP 1148 header and options are likely to fit within the buffer. A server 1149 can thus fully interpret a request and return a 4.13 (Request 1150 Entity Too Large) response code if the payload was truncated. A 1151 client sending an idempotent request and receiving a response 1152 larger than would fit in the buffer can repeat the request with a 1153 suitable value for the Block Option [I-D.ietf-core-block]. 1155 4.7. Congestion Control 1157 Basic congestion control for CoAP is provided by the exponential 1158 back-off mechanism in Section 4.2. 1160 In order not to cause congestion, Clients (including proxies) MUST 1161 strictly limit the number of simultaneous outstanding interactions 1162 that they maintain to a given server (including proxies) to NSTART. 1163 An outstanding interaction is either a CON for which an ACK has not 1164 yet been received but is still expected (message layer) or a request 1165 for which neither a response nor an Acknowledgment message has yet 1166 been received but is still expected (which may both occur at the same 1167 time, counting as one outstanding interaction). The default value of 1168 NSTART for this specification is 1. 1170 Further congestion control optimizations and considerations are 1171 expected in the future, which may for example provide automatic 1172 initialization of the CoAP transmission parameters defined in 1173 Section 4.8, and thus may allow a value for NSTART greater than one. 1175 A client stops expecting a response to a Confirmable request for 1176 which no acknowledgment message was received, after 1177 EXCHANGE_LIFETIME. The specific algorithm by which a client stops to 1178 "expect" a response to a Confirmable request that was acknowledged, 1179 or to a Non-confirmable request, is not defined. Unless this is 1180 modified by additional congestion control optimizations, it MUST be 1181 chosen in such a way that an endpoint does not exceed an average data 1182 rate of PROBING_RATE in sending to another endpoint that does not 1183 respond. 1185 Note: CoAP places the onus of congestion control mostly on the 1186 clients. However, clients may malfunction or actually be 1187 attackers, e.g. to perform amplification attacks (Section 11.3). 1188 To limit the damage (to the network and to its own energy 1189 resources), a server SHOULD implement some rate limiting for its 1190 response transmission based on reasonable assumptions about 1191 application requirements. This is most helpful if the rate limit 1192 can be made effective for the misbehaving endpoints, only. 1194 4.8. Transmission Parameters 1196 Message transmission is controlled by the following parameters: 1198 +-------------------+---------------+ 1199 | name | default value | 1200 +-------------------+---------------+ 1201 | ACK_TIMEOUT | 2 seconds | 1202 | ACK_RANDOM_FACTOR | 1.5 | 1203 | MAX_RETRANSMIT | 4 | 1204 | NSTART | 1 | 1205 | DEFAULT_LEISURE | 5 seconds | 1206 | PROBING_RATE | 1 Byte/second | 1207 +-------------------+---------------+ 1209 4.8.1. Changing The Parameters 1211 The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT, 1212 NSTART, DEFAULT_LEISURE, and PROBING_RATE may be configured to values 1213 specific to the application environment (including dynamically 1214 adjusted values), however the configuration method is out of scope of 1215 this document. It is recommended that an application environment use 1216 consistent values for these parameters. 1218 The transmission parameters have been chosen to achieve a behavior in 1219 the presence of congestion that is safe in the Internet. If a 1220 configuration desires to use different values, the onus is on the 1221 configuration to ensure these congestion control properties are not 1222 violated. In particular, a decrease of ACK_TIMEOUT below 1 second 1223 would violate the guidelines of [RFC5405]. 1224 ([I-D.allman-tcpm-rto-consider] provides some additional background.) 1225 CoAP was designed to enable implementations that do not maintain 1226 round-trip-time (RTT) measurements. However, where it is desired to 1227 decrease the ACK_TIMEOUT significantly or increase NSTART, this can 1228 only be done safely when maintaining such measurements. 1229 Configurations MUST NOT decrease ACK_TIMEOUT or increase NSTART 1230 without using mechanisms that ensure congestion control safety, 1231 either defined in the configuration or in future standards documents. 1233 ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have 1234 a value that is sufficiently different from 1.0 to provide some 1235 protection from synchronization effects. 1237 MAX_RETRANSMIT can be freely adjusted, but a too small value will 1238 reduce the probability that a confirmable message is actually 1239 received, while a larger value than given here will require further 1240 adjustments in the time values (see discussion below). 1242 If the choice of transmission parameters leads to an increase of 1243 derived time values (see below), the configuration mechanism MUST 1244 ensure the adjusted value is also available to all the endpoints in 1245 communicating with which these adjusted values are to be used. 1247 4.8.2. Time Values derived from Transmission Parameters 1249 The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR and MAX_RETRANSMIT 1250 influences the timing of retransmissions, which in turn influences 1251 how long certain information items need to be kept by an 1252 implementation. To be able to unambiguously reference these derived 1253 time values, we give them names as follows: 1255 o MAX_TRANSMIT_SPAN is the maximum time from the first transmission 1256 of a confirmable message to its last retransmission. For the 1257 default transmission parameters, the value is (2+4+8+16)*1.5 = 45 1258 seconds, or more generally: 1260 ACK_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * ACK_RANDOM_FACTOR 1262 o MAX_TRANSMIT_WAIT is the maximum time from the first transmission 1263 of a confirmable message to the time when the sender gives up on 1264 receiving an acknowledgement or reset. For the default 1265 transmission parameters, the value is (2+4+8+16+32)*1.5 = 93 1266 seconds, or more generally: 1268 ACK_TIMEOUT * (2 ** (MAX_RETRANSMIT + 1) - 1) * 1269 ACK_RANDOM_FACTOR 1271 In addition, some assumptions need to be made on the characteristics 1272 of the network and the nodes. 1274 o MAX_LATENCY is the maximum time a datagram is expected to take 1275 from the start of its transmission to the completion of its 1276 reception. This constant is related to the MSL (Maximum Segment 1277 Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 1278 minutes" ([RFC0793] glossary, page 81). Note that this is not 1279 necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not 1280 intended to describe a situation when the protocol works well, but 1281 the worst case situation against which the protocol has to guard. 1282 We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart 1283 from being reasonably realistic for the bulk of configurations as 1284 well as close to the historic choice for TCP, this value also 1285 allows message ID lifetime timers to be represented in 8 bits 1286 (when measured in seconds). In these calculations, there is no 1287 assumption that the direction of the transmission is irrelevant 1288 (i.e. that the network is symmetric), just that the same value can 1289 reasonably be used as a maximum value for both directions. If 1290 that is not the case, the following calculations become only 1291 slightly more complex. 1293 o PROCESSING_DELAY is the time a node takes to turn around a 1294 confirmable message into an acknowledgement. We assume the node 1295 will attempt to send an ACK before having the sender time out, so 1296 as a conservative assumption we set it equal to ACK_TIMEOUT. 1298 o MAX_RTT is the maximum round-trip time, or: 1300 2 * MAX_LATENCY + PROCESSING_DELAY 1302 From these values, we can derive the following values relevant to the 1303 protocol operation: 1305 o EXCHANGE_LIFETIME is the time from starting to send a confirmable 1306 message to the time when an acknowledgement is no longer expected, 1307 i.e. message layer information about the message exchange can be 1308 purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a 1309 MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the 1310 way back. Note that there is no need to consider 1311 MAX_TRANSMIT_WAIT if the configuration is chosen such that the 1312 last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the 1313 difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is 1314 less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY 1315 is a worst case value unlikely to be met in the real world. In 1316 this case, EXCHANGE_LIFETIME simplifies to: 1318 (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * ACK_RANDOM_FACTOR) + 1319 (2 * MAX_LATENCY) + PROCESSING_DELAY 1321 or 248 seconds with the default transmission parameters. 1323 o NON_LIFETIME is the time from sending a non-confirmable message to 1324 the time its message-ID can be safely reused. If multiple 1325 transmission of a NON message is not used, its value is 1326 MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a 1327 NON message multiple times, in particular for multicast 1328 applications. While the period of re-use is not bounded by the 1329 specification, an expectation of reliable detection of duplication 1330 at the receiver is in the timescales of MAX_TRANSMIT_SPAN. 1331 Therefore, for this purpose, it is safer to use the value: 1333 MAX_TRANSMIT_SPAN + MAX_LATENCY 1335 or 145 seconds with the default transmission parameters; however, 1336 an implementation that just wants to use a single timeout value 1337 for retiring message-IDs can safely use the larger value for 1338 EXCHANGE_LIFETIME. 1340 5. Request/Response Semantics 1342 CoAP operates under a similar request/response model as HTTP: a CoAP 1343 endpoint in the role of a "client" sends one or more CoAP requests to 1344 a "server", which services the requests by sending CoAP responses. 1345 Unlike HTTP, requests and responses are not sent over a previously 1346 established connection, but exchanged asynchronously over CoAP 1347 messages. 1349 5.1. Requests 1351 A CoAP request consists of the method to be applied to the resource, 1352 the identifier of the resource, a payload and Internet media type (if 1353 any), and optional meta-data about the request. 1355 CoAP supports the basic methods of GET, POST, PUT, DELETE, which are 1356 easily mapped to HTTP. They have the same properties of safe (only 1357 retrieval) and idempotent (you can invoke it multiple times with the 1358 same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method 1359 is safe, therefore it MUST NOT take any other action on a resource 1360 other than retrieval. The GET, PUT and DELETE methods MUST be 1361 performed in such a way that they are idempotent. POST is not 1362 idempotent, because its effect is determined by the origin server and 1363 dependent on the target resource; it usually results in a new 1364 resource being created or the target resource being updated. 1366 A request is initiated by setting the Code field in the CoAP header 1367 of a Confirmable or a Non-confirmable message to a Method Code and 1368 including request information. 1370 The methods used in requests are described in detail in Section 5.8. 1372 5.2. Responses 1374 After receiving and interpreting a request, a server responds with a 1375 CoAP response, which is matched to the request by means of a client- 1376 generated token. 1378 A response is identified by the Code field in the CoAP header being 1379 set to a Response Code. Similar to the HTTP Status Code, the CoAP 1380 Response Code indicates the result of the attempt to understand and 1381 satisfy the request. These codes are fully defined in Section 5.9. 1382 The Response Code numbers to be set in the Code field of the CoAP 1383 header are maintained in the CoAP Response Code Registry 1384 (Section 12.1.2). 1386 0 1387 0 1 2 3 4 5 6 7 1388 +-+-+-+-+-+-+-+-+ 1389 |class| detail | 1390 +-+-+-+-+-+-+-+-+ 1392 Figure 10: Structure of a Response Code 1394 The upper three bits of the 8-bit Response Code number define the 1395 class of response. The lower five bits do not have any 1396 categorization role; they give additional detail to the overall class 1397 (Figure 10). There are 3 classes: 1399 2 - Success: The request was successfully received, understood, and 1400 accepted. 1402 4 - Client Error: The request contains bad syntax or cannot be 1403 fulfilled. 1405 5 - Server Error: The server failed to fulfill an apparently valid 1406 request. 1408 The response codes are designed to be extensible: Response Codes in 1409 the Client Error and Server Error class that are unrecognized by an 1410 endpoint MUST be treated as being equivalent to the generic Response 1411 Code of that class (4.00 and 5.00, respectively). However, there is 1412 no generic Response Code indicating success, so a Response Code in 1413 the Success class that is unrecognized by an endpoint can only be 1414 used to determine that the request was successful without any further 1415 details. 1417 As a human readable notation for specifications and protocol 1418 diagnostics, the numeric value of a response code is indicated by 1419 giving the upper three bits in decimal, followed by a dot and then 1420 the lower five bits in a two-digit decimal. E.g., "Not Found" is 1421 written as 4.04 -- indicating a value of hexadecimal 0x84 or decimal 1422 132. In other words, the dot "." functions as a short-cut for 1423 "*32+". 1425 The possible response codes are described in detail in Section 5.9. 1427 Responses can be sent in multiple ways, which are defined below. 1429 5.2.1. Piggy-backed 1431 In the most basic case, the response is carried directly in the 1432 Acknowledgement message that acknowledges the request (which requires 1433 that the request was carried in a Confirmable message). This is 1434 called a "Piggy-backed" Response. 1436 The response is returned in the Acknowledgement message independent 1437 of whether the response indicates success or failure. In effect, the 1438 response is piggy-backed on the Acknowledgement message, so no 1439 separate message is required to both acknowledge that the request was 1440 received and return the response. 1442 Implementation Note: The protocol leaves the decision whether to 1443 piggy-back a response or not (i.e., send a separate response) to 1444 the server. The client MUST be prepared to receive either. On 1445 the quality of implementation level, there is a strong expectation 1446 that servers will implement code to piggy-back whenever possible 1447 -- saving resources in the network and both at the client and at 1448 the server. 1450 5.2.2. Separate 1452 It may not be possible to return a piggy-backed response in all 1453 cases. For example, a server might need longer to obtain the 1454 representation of the resource requested than it can wait sending 1455 back the Acknowledgement message, without risking the client to 1456 repeatedly retransmit the request message. Responses to requests 1457 carried in a Non-Confirmable message are always sent separately (as 1458 there is no Acknowledgement message). 1460 The server maybe initiates the attempt to obtain the resource 1461 representation and times out an acknowledgement timer, or it 1462 immediately sends an acknowledgement knowing in advance that there 1463 will be no piggy-backed response. The acknowledgement effectively is 1464 a promise that the request will be acted upon. 1466 When the server finally has obtained the resource representation, it 1467 sends the response. When it is desired that this message is not 1468 lost, it is sent as a Confirmable message from the server to the 1469 client and answered by the client with an Acknowledgement, echoing 1470 the new Message ID chosen by the server. (It may also be sent as a 1471 Non-Confirmable message; see Section 5.2.3.) 1473 Implementation Notes: Note that, as the underlying datagram 1474 transport may not be sequence-preserving, the Confirmable message 1475 carrying the response may actually arrive before or after the 1476 acknowledgement message for the request. Note also that, while 1477 the CoAP protocol itself does not make any specific demands here, 1478 there is an expectation that the response will come within a time 1479 frame that is reasonable from an application point of view; as 1480 there is no underlying transport protocol that could be instructed 1481 to run a keep-alive mechanism, the requester MAY want to set up a 1482 timeout that is unrelated to CoAP's retransmission timers in case 1483 the server is destroyed or otherwise unable to send the response.) 1485 An exchange is separate by definition when the Acknowledgement to the 1486 Confirmable request is an empty message. The Acknowledgement to the 1487 Confirmable response MUST also be an empty message, i.e. one that 1488 carries neither a request nor a response. However, a server MUST 1489 stop retransmitting its response on any matching Acknowledgement 1490 (silently ignoring any response code or payload) or Reset message. 1492 5.2.3. Non-Confirmable 1494 If the request message is Non-confirmable, then the response SHOULD 1495 be returned in a Non-confirmable message as well. However, an 1496 endpoint MUST be prepared to receive a Non-confirmable response 1497 (preceded or followed by an empty acknowledgement message) in reply 1498 to a Confirmable request, or a Confirmable response in reply to a 1499 Non-confirmable request. 1501 5.3. Request/Response Matching 1503 Regardless of how a response is sent, it is matched to the request by 1504 means of a token that is included by the client in the request as one 1505 of the options along with additional address information of the 1506 corresponding endpoint. The token MUST be echoed by the server in 1507 any resulting response without modification. 1509 The exact rules for matching a response to a request are as follows: 1511 1. The source endpoint of the response MUST be the same as the 1512 destination endpoint of the original request. 1514 2. In a piggy-backed response, both the Message ID of the 1515 Confirmable request and the Acknowledgement, and the token of the 1516 response and original request MUST match. In a separate 1517 response, just the token of the response and original request 1518 MUST match. 1520 The client SHOULD generate tokens in a way that tokens currently in 1521 use for a given source/destination pair are unique. (Note that a 1522 client can use the same token for any request if it uses a different 1523 source port number each time.) 1525 An endpoint that did not generate a token MUST treat it as opaque and 1526 make no assumptions about its format. (Note that there is a default 1527 value for the Token Option, so every message carries a token, even if 1528 it is not explicitly expressed in a CoAP option.) 1529 In case a message carrying a response is unexpected (i.e. the client 1530 is not waiting for a response at the endpoint addressed and/or with 1531 the given token), the response is rejected (Section 4.2, 1532 Section 4.3). 1534 Implementation Note: A client that receives a response in a CON 1535 message may want to clean up the message state right after sending 1536 the ACK. If that ACK is lost and the server retransmits the CON, 1537 the client may no longer have any state to correlate this response 1538 to, making the retransmission an unexpected message; the client 1539 may send a Reset message so it does not receive any more 1540 retransmissions. This behavior is normal and not an indication of 1541 an error. (Clients that are not aggressively optimized in their 1542 state memory usage will still have message state that will 1543 identify the second CON as a retransmission. Clients that 1544 actually expect more messages from the server 1545 [I-D.ietf-core-observe] will have to keep state in any case.) 1547 5.4. Options 1549 Both requests and responses may include a list of one or more 1550 options. For example, the URI in a request is transported in several 1551 options, and meta-data that would be carried in an HTTP header in 1552 HTTP is supplied as options as well. 1554 CoAP defines a single set of options that are used in both requests 1555 and responses: 1557 o Content-Format 1559 o ETag 1561 o Location-Path 1563 o Location-Query 1565 o Max-Age 1567 o Proxy-Uri 1569 o Token 1571 o Uri-Host 1573 o Uri-Path 1575 o Uri-Port 1576 o Uri-Query 1578 o Accept 1580 o If-Match 1582 o If-None-Match 1584 The semantics of these options along with their properties are 1585 defined in detail in Section 5.10. 1587 Not all options are defined for use with all methods and response 1588 codes. The possible options for methods and response codes are 1589 defined in Section 5.8 and Section 5.9 respectively. In case an 1590 option is not defined for a method or response code, it MUST NOT be 1591 included by a sender and MUST be treated like an unrecognized option 1592 by a recipient. 1594 An Option number is constructed with a bit mask to indicate if an 1595 option is Critical/Elective, Unsafe/Safe and in the case of Safe, 1596 also a Cache-Key as indicated by the following figure. When bit 7 1597 (the least significant bit) is 1, an option is Critical (and likewise 1598 Elective when 0). When bit 6 is 1, an option is Unsafe (and likewise 1599 Safe when 0). When an option is not Unsafe, it is not a Cache-Key 1600 (NoCacheKey) if and only if bits 3-5 are all set to 1; all other bit 1601 combinations mean that it indeed is a Cache-Key. These classes of 1602 options are explained in the next sections. 1604 0 1 2 3 4 5 6 7 1605 +---+---+---+---+---+---+---+---+ 1606 | | NoCacheKey| U | C | 1607 +---+---+---+---+---+---+---+---+ 1609 Figure 11: Option Number Mask 1611 An endpoint may use an equivalent of the following C code to derive 1612 the characteristics of an option number "onum": 1614 Critical = (onum & 1); 1615 UnSafe = (onum & 2); 1616 NoCacheKey = ((onum & 0x1e) == 0x1c); 1618 Figure 12 1620 5.4.1. Critical/Elective 1622 Options fall into one of two classes: "critical" or "elective". The 1623 difference between these is how an option unrecognized by an endpoint 1624 is handled: 1626 o Upon reception, unrecognized options of class "elective" MUST be 1627 silently ignored. 1629 o Unrecognized options of class "critical" that occur in a 1630 confirmable request MUST cause the return of a 4.02 (Bad Option) 1631 response. This response SHOULD include a diagnostic message 1632 describing the unrecognized option(s) (see Section 5.5.2). 1634 o Unrecognized options of class "critical" that occur in a 1635 confirmable response, or piggy-backed in an acknowledgement, MUST 1636 cause the response to be rejected (Section 4.2). 1638 o Unrecognized options of class "critical" that occur in a non- 1639 confirmable message MUST cause the message to be rejected 1640 (Section 4.3). 1642 Note that, whether critical or elective, an option is never 1643 "mandatory" (it is always optional): These rules are defined in order 1644 to enable implementations to stop processing options they do not 1645 understand or implement. 1647 Critical/Elective rules apply to non-proxying endpoints. A proxy 1648 processes options based on Unsafe/Safe classes as defined in 1649 Section 5.7. 1651 5.4.2. Proxy Unsafe/Safe and Cache-Key 1653 In addition to an option being marked as Critical or Elective, 1654 options are also classified based on how a proxy is to deal with the 1655 option if it does not recognize it. For this purpose, an option can 1656 either be considered Unsafe to Forward (UnSafe is set) or Safe to 1657 Forward (UnSafe is clear). 1659 In addition, for options that are marked Safe to Forward, the option 1660 indicates whether it is intended to be part of the Cache-Key in a 1661 request (NoCacheKey is not all set) or not (NoCacheKey is set). 1663 Note: The Cache-Key indication is relevant only for proxies that do 1664 not implement the given option as a request option and instead 1665 rely on the Safe/Unsafe indication only. E.g., for ETag, actually 1666 using the request option as a cache key is grossly inefficient, 1667 but it is the best thing one can do if ETag is not implemented by 1668 a proxy, as the reponse is going to differ based on the presence 1669 of the request option. A more useful proxy that does implement 1670 the ETag request option is not using ETag as a cache key. 1672 Proxy behavior with regard to these classes is defined in 1673 Section 5.7. 1675 5.4.3. Length 1677 Option values are defined to have a specific length, often in the 1678 form of an upper and lower bound. If the length of an option value 1679 in a request is outside the defined range, that option MUST be 1680 treated like an unrecognized option (see Section 5.4.1). 1682 5.4.4. Default Values 1684 Options may be defined to have a default value. If the value of 1685 option is intended to be this default value, the option SHOULD NOT be 1686 included in the message. If the option is not present, the default 1687 value MUST be assumed. 1689 Where a critical option has a default value, this is chosen in such a 1690 way that the absence of the option in a message can be processed 1691 properly both by implementations unaware of the critical option and 1692 by implementations that interpret this absence as the presence of the 1693 default value for the option. 1695 5.4.5. Repeatable Options 1697 The definition of an option MAY specify the option to be repeatable. 1698 An option that is repeatable MAY be included one or more times in a 1699 message. An option that is not repeatable MUST NOT be included more 1700 than once in a message. 1702 If a message includes an option with more occurrences than the option 1703 is defined for, the additional option occurrences MUST be treated 1704 like an unrecognized option (see Section 5.4.1). 1706 5.4.6. Option Numbers 1708 Options are identified by an option number. Odd numbers indicate a 1709 critical option, while even numbers indicate an elective option. 1710 (Note that this is not just a convention, it is a feature of the 1711 protocol: Whether an option is elective or critical is entirely 1712 determined by whether its option number is even or odd.) 1714 The option numbers for the options defined in this document are 1715 listed in the CoAP Option Number Registry (Section 12.2). 1717 5.5. Payload 1719 Both requests and responses may include payload, depending on the 1720 method or response code respectively. If a method or response code 1721 is not defined to have a payload, then a sender MUST NOT include one, 1722 and a recipient MUST ignore it. 1724 5.5.1. Representation 1726 The payload of requests or of responses indicating success is 1727 typically a representation of a resource or the result of the 1728 requested action. Its format is specified by the Internet media type 1729 and content coding given by the Content-Format Option. In the 1730 absence of this option, no default value is assumed and the format 1731 must be inferred by the application (e.g., from the application 1732 context or by "sniffing" the payload). 1734 5.5.2. Diagnostic Message 1736 The payload of responses indicating a client or server error is a 1737 brief human-readable diagnostic message, explaining the error 1738 situation. This diagnostic message MUST be encoded using UTF-8 1739 [RFC3629], more specifically using Net-Unicode form [RFC5198]. The 1740 Content-Format Option MUST NOT be included by the sender and MUST be 1741 treated like an unrecognized option by the recipient. 1743 The message is similar to the Reason-Phrase on an HTTP status line. 1744 It is not intended for end-users but for software engineers that 1745 during debugging need to interpret it in the context of the present, 1746 English-language specification; therefore no mechanism for language 1747 tagging is needed or provided. In contrast to what is usual in HTTP, 1748 the message SHOULD be empty if there is no additional information 1749 beyond the response code. 1751 5.6. Caching 1753 CoAP endpoints MAY cache responses in order to reduce the response 1754 time and network bandwidth consumption on future, equivalent 1755 requests. 1757 The goal of caching in CoAP is to reuse a prior response message to 1758 satisfy a current request. In some cases, a stored response can be 1759 reused without the need for a network request, reducing latency and 1760 network round-trips; a "freshness" mechanism is used for this purpose 1761 (see Section 5.6.1). Even when a new request is required, it is 1762 often possible to reuse the payload of a prior response to satisfy 1763 the request, thereby reducing network bandwidth usage; a "validation" 1764 mechanism is used for this purpose (see Section 5.6.2). 1766 Unlike HTTP, the cacheability of CoAP responses does not depend on 1767 the request method, but the Response Code. The cacheability of each 1768 Response Code is defined along the Response Code definitions in 1769 Section 5.9. Response Codes that indicate success and are 1770 unrecognized by an endpoint MUST NOT be cached. 1772 For a presented request, a CoAP endpoint MUST NOT use a stored 1773 response, unless: 1775 o the presented request method and that used to obtain the stored 1776 response match, 1778 o all options match between those in the presented request and those 1779 of the request used to obtain the stored response (which includes 1780 the request URI), except that there is no need for a match of the 1781 Token, Max-Age, or ETag request option(s), or any request options 1782 marked as NoCacheKey (Section 5.4), and 1784 o the stored response is either fresh or successfully validated as 1785 defined below. 1787 5.6.1. Freshness Model 1789 When a response is "fresh" in the cache, it can be used to satisfy 1790 subsequent requests without contacting the origin server, thereby 1791 improving efficiency. 1793 The mechanism for determining freshness is for an origin server to 1794 provide an explicit expiration time in the future, using the Max-Age 1795 Option (see Section 5.10.6). The Max-Age Option indicates that the 1796 response is to be considered not fresh after its age is greater than 1797 the specified number of seconds. 1799 The Max-Age Option defaults to a value of 60. Thus, if it is not 1800 present in a cacheable response, then the response is considered not 1801 fresh after its age is greater than 60 seconds. If an origin server 1802 wishes to prevent caching, it MUST explicitly include a Max-Age 1803 Option with a value of zero seconds. 1805 If a client has a fresh stored response and makes a new request 1806 matching the request for that stored response, the new response 1807 invalidates the old response. 1809 5.6.2. Validation Model 1811 When an endpoint has one or more stored responses for a GET request, 1812 but cannot use any of them (e.g., because they are not fresh), it can 1813 use the ETag Option (Section 5.10.7) in the GET request to give the 1814 origin server an opportunity to both select a stored response to be 1815 used, and to update its freshness. This process is known as 1816 "validating" or "revalidating" the stored response. 1818 When sending such a request, the endpoint SHOULD add an ETag Option 1819 specifying the entity-tag of each stored response that is applicable. 1821 A 2.03 (Valid) response indicates the stored response identified by 1822 the entity-tag given in the response's ETag Option can be reused, 1823 after updating its freshness with the value of the Max-Age Option 1824 that is included (explicitly, or implicitly as a default value) with 1825 the response (see Section 5.9.1.3). 1827 Any other response code indicates that none of the stored responses 1828 nominated in the request is suitable. Instead, the response SHOULD 1829 be used to satisfy the request and MAY replace the stored response. 1831 5.7. Proxying 1833 A proxy is a CoAP endpoint that can be tasked by CoAP clients to 1834 perform requests on their behalf. This may be useful, for example, 1835 when the request could otherwise not be made, or to service the 1836 response from a cache in order to reduce response time and network 1837 bandwidth or energy consumption. 1839 In an overall architecture for a Constrained RESTful Environment, 1840 proxies can serve quite different purposes. Proxies can be 1841 explicitly selected by clients, a role that we term "forward-proxy". 1842 Proxies can also be inserted to stand in for origin servers, a role 1843 that we term "reverse-proxy". Orthogonal to this distinction, a 1844 proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP 1845 proxy) or translate from or to a different protocol ("cross-proxy"). 1846 Full definitions of these terms are provided in Section 1.2. 1848 Notes: The terminology in this specification has been selected to be 1849 culturally compatible with the terminology used in the wider Web 1850 application environments, without necessarily matching it in every 1851 detail (which may not even be relevant to Constrained RESTful 1852 Environments). Not too much semantics should be ascribed to the 1853 components of the terms (such as "forward", "reverse", or 1854 "cross"). 1856 HTTP proxies, besides acting as HTTP proxies, often offer a 1857 transport protocol proxying function ("CONNECT") to enable end-to- 1858 end transport layer security through the proxy. No such function 1859 is defined for CoAP-to-CoAP proxies in this specification, as 1860 forwarding of UDP packets is unlikely to be of much value in 1861 Constrained RESTful environments. See also Section 10.2.7 for the 1862 cross-proxy case. 1864 5.7.1. Proxy Operation 1866 A proxy generally needs a way to determine potential request 1867 parameters for a request to a destination based on the request it 1868 received. This way is fully specified for a forward-proxy, but may 1869 depend on the specific configuration for a reverse-proxy. In 1870 particular, the client of a reverse-proxy generally does not indicate 1871 a locator for the destination, necessitating some form of namespace 1872 translation in the reverse-proxy. However, some aspects of the 1873 operation of proxies are common to all its forms. 1875 If a proxy does not employ a cache, then it simply forwards the 1876 translated request to the determined destination. Otherwise, if it 1877 does employ a cache but does not have a stored response that matches 1878 the translated request and is considered fresh, then it needs to 1879 refresh its cache according to Section 5.6. For options in the 1880 request that the proxy recognizes, it knows whether the option is 1881 intended to act as part of the key used in looking up the cached 1882 value or not. E.g., since requests for different Uri-Path values 1883 address different resources, Uri-Path values are always parts of the 1884 cache key, while, e.g., Token values are never part of the cache key. 1885 For options that the proxy does not recognize but that are marked 1886 Safe in the option number, the option also indicates whether it is to 1887 be included in the cache key (NoCacheKey is not all set) or not 1888 (NoCacheKey is all set). (Options that are unrecognized and marked 1889 Unsafe lead to 4.02 Bad Option.) 1891 If the request to the destination times out, then a 5.04 (Gateway 1892 Timeout) response MUST be returned. If the request to the 1893 destination returns a response that cannot be processed by the proxy 1894 (e.g, due to unrecognized critical options, encoding errors), then a 1895 5.02 (Bad Gateway) response MUST be returned. Otherwise, the proxy 1896 returns the response to the client. 1898 If a response is generated out of a cache, it MUST be generated with 1899 a Max-Age Option that does not extend the max-age originally set by 1900 the server, considering the time the resource representation spent in 1901 the cache. E.g., the Max-Age Option could be adjusted by the proxy 1902 for each response using the formula: 1904 proxy-max-age = original-max-age - cache-age 1906 For example if a request is made to a proxied resource that was 1907 refreshed 20 seconds ago and had an original Max-Age of 60 seconds, 1908 then that resource's proxied max-age is now 40 seconds. Considering 1909 potential network delays on the way from the origin server, a proxy 1910 SHOULD be conservative in the max-age values offered. 1912 All options present in a proxy request MUST be processed at the 1913 proxy. Unsafe options in a request that are not recognized by the 1914 proxy MUST lead to a 4.02 (Bad Option) response being returned by the 1915 proxy. A CoAP-to-CoAP proxy MUST forward to the origin server all 1916 Safe options that it does not recognize. Similarly, Unsafe options 1917 in a response that are not recognized by the CoAP-to-CoAP proxy 1918 server MUST lead to a 5.02 (Bad Gateway) response. Again, Safe 1919 options that are not recognized MUST be forwarded. 1921 Additional considerations for cross-protocol proxying between CoAP 1922 and HTTP are discussed in Section 10. 1924 5.7.2. Forward-Proxies 1926 CoAP distinguishes between requests made (as if) to an origin server 1927 and a request made through a forward-proxy. CoAP requests to a 1928 forward-proxy are made as normal confirmable or non-confirmable 1929 requests to the forward-proxy endpoint, but specify the request URI 1930 in a different way: The request URI in a proxy request is specified 1931 as a string in the Proxy-Uri Option (see Section 5.10.3), while the 1932 request URI in a request to an origin server is split into the Uri- 1933 Host, Uri-Port, Uri-Path and Uri-Query Options (see Section 5.10.2). 1935 When a proxy request is made to an endpoint and the endpoint is 1936 unwilling or unable to act as proxy for the request URI, it MUST 1937 return a 5.05 (Proxying Not Supported) response. If the authority 1938 (host and port) is recognized as identifying the proxy endpoint 1939 itself (see Section 5.10.3), then the request MUST be treated as a 1940 local (non-proxied) request. 1942 Unless a proxy is configured to forward the proxy request to another 1943 proxy, it MUST translate the request as follows: The scheme of the 1944 request URI defines the outgoing protocol and its details (e.g., CoAP 1945 is used over UDP for the "coap" scheme and over DTLS for the "coaps" 1946 scheme.) For a CoAP-to-CoAP proxy, the origin server's IP address 1947 and port are determined by the authority component of the request 1948 URI, and the request URI is decoded and split into the Uri-Host, Uri- 1949 Port, Uri-Path and Uri-Query Options. This consumes the Proxy-URI 1950 option, which is therefore not forwarded to the origin server. 1952 5.7.3. Reverse-Proxies 1954 Reverse-proxies do not make use of the Proxy-Uri option, but need to 1955 determine the destination (next hop) of a request from information in 1956 the request and information in their configuration. E.g., a reverse- 1957 proxy might offer various resources the existence of which it has 1958 learned through resource discovery as if they were its own resources. 1959 The reverse-proxy is free to build a namespace for the URIs that 1960 identify these resources. A reverse-proxy may also build a namespace 1961 that gives the client more control over where the request goes, e.g. 1962 by embedding host identifiers and port numbers into the URI path of 1963 the resources offered. 1965 In processing the response, a reverse-proxy has to be careful about 1966 namespacing the ETag option. In many cases, it can be forwarded 1967 unchanged. If the mapping from a resource offered by the reverse- 1968 proxy to resources offered by its various origin servers is not 1969 unique, the reverse-proxy may need to generate a new ETag, making 1970 sure the semantics of this option are properly preserved. 1972 5.8. Method Definitions 1974 In this section each method is defined along with its behavior. A 1975 request with an unrecognized or unsupported Method Code MUST generate 1976 a 4.05 (Method Not Allowed) piggy-backed response. 1978 5.8.1. GET 1980 The GET method retrieves a representation for the information that 1981 currently corresponds to the resource identified by the request URI. 1982 If the request includes one or more Accept Options, they indicate the 1983 preferred content-format of a response. If the request includes an 1984 ETag Option, the GET method requests that ETag be validated and that 1985 the representation be transferred only if validation failed. Upon 1986 success a 2.05 (Content) or 2.03 (Valid) response code SHOULD be 1987 present in the response. 1989 The GET method is safe and idempotent. 1991 5.8.2. POST 1993 The POST method requests that the representation enclosed in the 1994 request be processed. The actual function performed by the POST 1995 method is determined by the origin server and dependent on the target 1996 resource. It usually results in a new resource being created or the 1997 target resource being updated. 1999 If a resource has been created on the server, the response returned 2000 by the server SHOULD have a 2.01 (Created) response code and SHOULD 2001 include the URI of the new resource in a sequence of one or more 2002 Location-Path and/or Location-Query Options (Section 5.10.8). If the 2003 POST succeeds but does not result in a new resource being created on 2004 the server, the response SHOULD have a 2.04 (Changed) response code. 2005 If the POST succeeds and results in the target resource being 2006 deleted, the response SHOULD have a 2.02 (Deleted) response code. 2008 POST is neither safe nor idempotent. 2010 5.8.3. PUT 2012 The PUT method requests that the resource identified by the request 2013 URI be updated or created with the enclosed representation. The 2014 representation format is specified by the media type and content 2015 coding given in the Content-Format Option, if provided. 2017 If a resource exists at the request URI the enclosed representation 2018 SHOULD be considered a modified version of that resource, and a 2.04 2019 (Changed) response code SHOULD be returned. If no resource exists 2020 then the server MAY create a new resource with that URI, resulting in 2021 a 2.01 (Created) response code. If the resource could not be created 2022 or modified, then an appropriate error response code SHOULD be sent. 2024 Further restrictions to a PUT can be made by including the If-Match 2025 (see Section 5.10.9) or If-None-Match (see Section 5.10.10) options 2026 in the request. 2028 PUT is not safe, but is idempotent. 2030 5.8.4. DELETE 2032 The DELETE method requests that the resource identified by the 2033 request URI be deleted. A 2.02 (Deleted) response code SHOULD be 2034 used on success or in case the resource did not exist before the 2035 request. 2037 DELETE is not safe, but is idempotent. 2039 5.9. Response Code Definitions 2041 Each response code is described below, including any options required 2042 in the response. Where appropriate, some of the codes will be 2043 specified in regards to related response codes in HTTP [RFC2616]; 2044 this does not mean that any such relationship modifies the HTTP 2045 mapping specified in Section 10. 2047 5.9.1. Success 2.xx 2049 This class of status code indicates that the clients request was 2050 successfully received, understood, and accepted. 2052 5.9.1.1. 2.01 Created 2054 Like HTTP 201 "Created", but only used in response to POST and PUT 2055 requests. The payload returned with the response, if any, is a 2056 representation of the action result. 2058 If the response includes one or more Location-Path and/or Location- 2059 Query Options, the values of these options specify the location at 2060 which the resource was created. Otherwise, the resource was created 2061 at the request URI. A cache receiving this response MUST mark any 2062 stored response for the created resource as not fresh. 2064 This response is not cacheable. 2066 5.9.1.2. 2.02 Deleted 2068 Like HTTP 204 "No Content", but only used in response to DELETE 2069 requests. The payload returned with the response, if any, is a 2070 representation of the action result. 2072 This response is not cacheable. However, a cache SHOULD mark any 2073 stored response for the deleted resource as not fresh. 2075 5.9.1.3. 2.03 Valid 2077 Related to HTTP 304 "Not Modified", but only used to indicate that 2078 the response identified by the entity-tag identified by the included 2079 ETag Option is valid. Accordingly, the response MUST include an ETag 2080 Option. 2082 When a cache receives a 2.03 (Valid) response, it MUST update the 2083 stored response with the value of the Max-Age Option included in the 2084 response (see Section 5.6.2). 2086 5.9.1.4. 2.04 Changed 2088 Like HTTP 204 "No Content", but only used in response to POST and PUT 2089 requests. The payload returned with the response, if any, is a 2090 representation of the action result. 2092 This response is not cacheable. However, a cache MUST mark any 2093 stored response for the changed resource as not fresh. 2095 5.9.1.5. 2.05 Content 2097 Like HTTP 200 "OK", but only used in response to GET requests. 2099 The payload returned with the response is a representation of the 2100 target resource. 2102 This response is cacheable: Caches can use the Max-Age Option to 2103 determine freshness (see Section 5.6.1) and (if present) the ETag 2104 Option for validation (see Section 5.6.2). 2106 5.9.2. Client Error 4.xx 2108 This class of response code is intended for cases in which the client 2109 seems to have erred. These response codes are applicable to any 2110 request method. 2112 The server SHOULD include a diagnostic message as detailed in 2113 Section 5.5.2. 2115 Responses of this class are cacheable: Caches can use the Max-Age 2116 Option to determine freshness (see Section 5.6.1). They cannot be 2117 validated. 2119 5.9.2.1. 4.00 Bad Request 2121 Like HTTP 400 "Bad Request". 2123 5.9.2.2. 4.01 Unauthorized 2125 The client is not authorized to perform the requested action. The 2126 client SHOULD NOT repeat the request without previously improving its 2127 authentication status to the server. Which specific mechanism can be 2128 used for this is outside this document's scope; see also Section 9. 2130 5.9.2.3. 4.02 Bad Option 2132 The request could not be understood by the server due to one or more 2133 unrecognized or malformed options. The client SHOULD NOT repeat the 2134 request without modification. 2136 5.9.2.4. 4.03 Forbidden 2138 Like HTTP 403 "Forbidden". 2140 5.9.2.5. 4.04 Not Found 2142 Like HTTP 404 "Not Found". 2144 5.9.2.6. 4.05 Method Not Allowed 2146 Like HTTP 405 "Method Not Allowed", but with no parallel to the 2147 "Allow" header field. 2149 5.9.2.7. 4.06 Not Acceptable 2151 Like HTTP 406 "Not Acceptable", but with no response entity. 2153 5.9.2.8. 4.12 Precondition Failed 2155 Like HTTP 412 "Precondition Failed". 2157 5.9.2.9. 4.13 Request Entity Too Large 2159 Like HTTP 413 "Request Entity Too Large". 2161 5.9.2.10. 4.15 Unsupported Content-Format 2163 Like HTTP 415 "Unsupported Media Type". 2165 5.9.3. Server Error 5.xx 2167 This class of response code indicates cases in which the server is 2168 aware that it has erred or is incapable of performing the request. 2169 These response codes are applicable to any request method. 2171 The server SHOULD include a diagnostic message as detailed in 2172 Section 5.5.2. 2174 Responses of this class are cacheable: Caches can use the Max-Age 2175 Option to determine freshness (see Section 5.6.1). They cannot be 2176 validated. 2178 5.9.3.1. 5.00 Internal Server Error 2180 Like HTTP 500 "Internal Server Error". 2182 5.9.3.2. 5.01 Not Implemented 2184 Like HTTP 501 "Not Implemented". 2186 5.9.3.3. 5.02 Bad Gateway 2188 Like HTTP 502 "Bad Gateway". 2190 5.9.3.4. 5.03 Service Unavailable 2192 Like HTTP 503 "Service Unavailable", but using the Max-Age Option in 2193 place of the "Retry-After" header field to indicate the number of 2194 seconds after which to retry. 2196 5.9.3.5. 5.04 Gateway Timeout 2198 Like HTTP 504 "Gateway Timeout". 2200 5.9.3.6. 5.05 Proxying Not Supported 2202 The server is unable or unwilling to act as a forward-proxy for the 2203 URI specified in the Proxy-Uri Option (see Section 5.10.3). 2205 5.10. Option Definitions 2207 The individual CoAP options are summarized in Table 1 and explained 2208 below. 2210 +-----+---+---+---+---+----------------+--------+--------+----------+ 2211 | No. | C | U | N | R | Name | Format | Length | Default | 2212 +-----+---+---+---+---+----------------+--------+--------+----------+ 2213 | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | 2214 | 3 | x | x | | | Uri-Host | string | 1-255 | (see | 2215 | | | | | | | | | below) | 2216 | 4 | | | | x | ETag | opaque | 1-8 | (none) | 2217 | 5 | x | | | | If-None-Match | empty | 0 | (none) | 2218 | 7 | x | x | | | Uri-Port | uint | 0-2 | (see | 2219 | | | | | | | | | below) | 2220 | 8 | | | | x | Location-Path | string | 0-255 | (none) | 2221 | 11 | x | x | | x | Uri-Path | string | 0-255 | (none) | 2222 | 12 | | | | | Content-Format | uint | 0-2 | (none) | 2223 | 14 | | x | | | Max-Age | uint | 0-4 | 60 | 2224 | 15 | x | x | | x | Uri-Query | string | 1-255 | (none) | 2225 | 16 | | | | x | Accept | uint | 0-2 | (none) | 2226 | 19 | x | x | | | Token | opaque | 1-8 | (empty) | 2227 | 20 | | | | x | Location-Query | string | 0-255 | (none) | 2228 | 35 | x | x | | | Proxy-Uri | string | 1-1034 | (none) | 2229 +-----+---+---+---+---+----------------+--------+--------+----------+ 2231 C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable 2233 Table 1: Options 2235 Temporary Note: At the time of submission, the great renumbering is 2236 not yet reflected in [I-D.ietf-core-block] and 2237 [I-D.ietf-core-observe]. The new numbers are: 6 for Observe, 23 2238 for Block2, 27 for Block1, and 28 for Size. This note to be 2239 removed when the satellite drafts are updated. 2241 5.10.1. Token 2243 The Token Option is used to match a response with a request. Every 2244 request has a client-generated token which the server MUST echo in 2245 any response. The token value is a sequence of 0 to 8 bytes. A 2246 default value of the zero-length token is assumed in the absence of 2247 the option. A value of 1 to 8 bytes can be sent as an option value. 2248 Thus when the token value is empty, the Token Option MUST be elided. 2250 A token is intended for use as a client-local identifier for 2251 differentiating between concurrent requests (see Section 5.3). A 2252 client SHOULD generate tokens in a way that tokens currently in use 2253 for a given source/destination pair are unique. An empty token value 2254 is appropriate e.g. when no other tokens are in use to a destination, 2255 or when requests are made serially per destination. There are 2256 however multiple possible implementation strategies to fulfill this. 2257 An endpoint receiving a token MUST treat it as opaque and make no 2258 assumptions about its format. 2260 5.10.2. Uri-Host, Uri-Port, Uri-Path and Uri-Query 2262 The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to 2263 specify the target resource of a request to a CoAP origin server. 2264 The options encode the different components of the request URI in a 2265 way that no percent-encoding is visible in the option values and that 2266 the full URI can be reconstructed at any involved endpoint. The 2267 syntax of CoAP URIs is defined in Section 6. 2269 The steps for parsing URIs into options is defined in Section 6.4. 2270 These steps result in zero or more Uri-Host, Uri-Port, Uri-Path and 2271 Uri-Query Options being included in a request, where each option 2272 holds the following values: 2274 o the Uri-Host Option specifies the Internet host of the resource 2275 being requested, 2277 o the Uri-Port Option specifies the transport layer port number of 2278 the resource, 2280 o each Uri-Path Option specifies one segment of the absolute path to 2281 the resource, and 2283 o each Uri-Query Option specifies one argument parameterizing the 2284 resource. 2286 Note: Fragments ([RFC3986], Section 3.5) are not part of the request 2287 URI and thus will not be transmitted in a CoAP request. 2289 The default value of the Uri-Host Option is the IP literal 2290 representing the destination IP address of the request message. 2291 Likewise, the default value of the Uri-Port Option is the destination 2292 UDP port. The default values for the Uri-Host and Uri-Port Options 2293 are sufficient for requests to most servers. Explicit Uri-Host and 2294 Uri-Port Options are typically used when an endpoint hosts multiple 2295 virtual servers. 2297 The Uri-Path and Uri-Query Option can contain any character sequence. 2298 No percent-encoding is performed. The value of a Uri-Path Option 2299 MUST NOT be "." or ".." (as the request URI must be resolved before 2300 parsing it into options). 2302 The steps for constructing the request URI from the options are 2303 defined in Section 6.5. Note that an implementation does not 2304 necessarily have to construct the URI; it can simply look up the 2305 target resource by looking at the individual options. 2307 Examples can be found in Appendix B. 2309 5.10.3. Proxy-Uri 2311 The Proxy-Uri Option is used to make a request to a forward-proxy 2312 (see Section 5.7). The forward-proxy is requested to forward the 2313 request or service it from a valid cache, and return the response. 2315 The option value is an absolute-URI ([RFC3986], Section 4.3). 2317 Note that the forward-proxy MAY forward the request on to another 2318 proxy or directly to the server specified by the absolute-URI. In 2319 order to avoid request loops, a proxy MUST be able to recognize all 2320 of its server names, including any aliases, local variations, and the 2321 numeric IP addresses. 2323 An endpoint receiving a request with a Proxy-Uri Option that is 2324 unable or unwilling to act as a forward-proxy for the request MUST 2325 cause the return of a 5.05 (Proxying Not Supported) response. 2327 The Proxy-Uri Option MUST take precedence over any of the Uri-Host, 2328 Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included 2329 at the same time in a request containing the Proxy-Uri Option). 2331 5.10.4. Content-Format 2333 The Content-Format Option indicates the representation format of the 2334 message payload. The representation format is given as a numeric 2335 content format identifier that is defined in the CoAP Content Format 2336 registry (Section 12.3). In the absence of the option, no default 2337 value is assumed, i.e. the representation format of any 2338 representation message payload is indeterminate (Section 5.5). 2340 5.10.5. Accept 2342 The CoAP Accept option indicates when included one or more times in a 2343 request, one or more Content-Formats, each of which is an acceptable 2344 Content-Format for the client, in the order of preference (most 2345 preferred first). The representation format is given as a numeric 2346 Content-Format identifier that is defined in the CoAP Content-Format 2347 registry (Section 12.3). If no Accept options are given, the client 2348 does not express a preference (thus no default value is assumed). 2349 The client prefers the representation returned by the server to be in 2350 one of the Content-Formats indicated. The server SHOULD return one 2351 of the preferred Content-Formats if available. If none of the 2352 preferred Content-Formats can be returned, then a 4.06 "Not 2353 Acceptable" SHOULD be sent as a response. 2355 Note that as a server might not support the Accept option (and thus 2356 would ignore it as it is elective), the client needs to be prepared 2357 to receive a representation in a different Content-Format. The 2358 client can simply discard a representation it can not make use of. 2360 5.10.6. Max-Age 2362 The Max-Age Option indicates the maximum time a response may be 2363 cached before it MUST be considered not fresh (see Section 5.6.1). 2365 The option value is an integer number of seconds between 0 and 2366 2**32-1 inclusive (about 136.1 years). A default value of 60 seconds 2367 is assumed in the absence of the option in a response. 2369 The value is intended to be current at the time of transmission. 2370 Servers that provide resources with strict tolerances on the value of 2371 Max-Age SHOULD update the value before each retransmission. (See 2372 also Section 5.7.1.) 2374 5.10.7. ETag 2376 The ETag Option in a response provides the current value of the 2377 entity-tag for the enclosed representation of the target resource. 2379 An entity-tag is intended for use as a resource-local identifier for 2380 differentiating between representations of the same resource that 2381 vary over time. It may be generated in any number of ways including 2382 a version, checksum, hash or time. An endpoint receiving an entity- 2383 tag MUST treat it as opaque and make no assumptions about its format. 2384 (Endpoints generating an entity-tag are encouraged to use the most 2385 compact representation possible, in particular in regards to clients 2386 and intermediaries that may want to store multiple ETag values.) 2388 An endpoint that has one or more representations previously obtained 2389 from the resource can specify the ETag Option in a request for each 2390 stored response to determine if any of those representations is 2391 current (see Section 5.6.2). 2393 The ETag Option MUST NOT occur more than once in a response, and MAY 2394 occur one or more times in a request. 2396 5.10.8. Location-Path and Location-Query 2398 The Location-Path and Location-Query Options together indicate a 2399 relative URI that consists either of an absolute path, a query string 2400 or both. A combination of these options is included in a 2.01 2401 (Created) response to indicate the location of the resource created 2402 as the result of a POST request (see Section 5.8.2). The location is 2403 resolved relative to the request URI. 2405 If a response with one or more Location-Path and/or Location-Query 2406 Options passes through a cache and the implied URI identifies one or 2407 more currently stored responses, those entries SHOULD be marked as 2408 not fresh. 2410 Each Location-Path Option specifies one segment of the absolute path 2411 to the resource, and each Location-Query Option specifies one 2412 argument parameterizing the resource. The Location-Path and 2413 Location-Query Option can contain any character sequence. No 2414 percent-encoding is performed. The value of a Location-Path Option 2415 MUST NOT be "." or "..". 2417 The steps for constructing the location URI from the options are 2418 analogous to Section 6.5, except that the first five steps are 2419 skipped and the result is a relative URI-reference. 2421 More Location-* options may be defined in the future, and have been 2422 reserved option numbers 128, 132 and 136. If any of these reserved 2423 option numbers occurs in addition to Location-Path and/or Location- 2424 Query and are not supported, then a 4.02 (Bad Option) error MUST be 2425 returned. 2427 5.10.9. If-Match 2429 The If-Match Option MAY be used to make a request conditional on the 2430 current existence or value of an ETag for one or more representations 2431 of the target resource. If-Match is generally useful for resource 2432 update requests, such as PUT requests, as a means for protecting 2433 against accidental overwrites when multiple clients are acting in 2434 parallel on the same resource (i.e., the "lost update" problem). 2436 The value of an If-Match option is either an ETag or the empty 2437 string. An If-Match option with an ETag matches a representation 2438 with that exact ETag. An If-Match option with an empty value matches 2439 any existing representation (i.e., it places the precondition on the 2440 existence of any current representation for the target resource). 2442 The If-Match Option can occur multiple times. If any of the options 2443 match, then the server performs the request method as if the set of 2444 If-Match Options were not present. 2446 If there is one or more If-Match Option, but none of the options 2447 match, the server MUST NOT perform the requested method. Instead, 2448 the server MUST respond with the 4.12 (Precondition Failed) response 2449 code. 2451 If the request would, without the If-Match Options, result in 2452 anything other than a 2.xx or 4.12 response code, then any If-Match 2453 Options MUST be ignored. 2455 5.10.10. If-None-Match 2457 The If-None-Match Option MAY be used to make a request conditional on 2458 the non-existence of the target resource. If-None-Match is useful 2459 for resource creation requests, such as PUT requests, as a means for 2460 protecting against accidental overwrites when multiple clients are 2461 acting in parallel on the same resource. The If-None-Match Option 2462 carries no value. 2464 If the target resource does exist, then the server MUST NOT perform 2465 the requested method. Instead, the server MUST respond with the 4.12 2466 (Precondition Failed) response code. 2468 6. CoAP URIs 2470 CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP 2471 resources and providing a means of locating the resource. Resources 2472 are organized hierarchically and governed by a potential CoAP origin 2473 server listening for CoAP requests ("coap") or DTLS-secured CoAP 2474 requests ("coaps") on a given UDP port. The CoAP server is 2475 identified via the generic syntax's authority component, which 2476 includes a host component and optional UDP port number. The 2477 remainder of the URI is considered to be identifying a resource which 2478 can be operated on by the methods defined by the CoAP protocol. The 2479 "coap" and "coaps" URI schemes can thus be compared to the "http" and 2480 "https" URI schemes respectively. 2482 The syntax of the "coap" and "coaps" URI schemes is specified below 2483 in Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 2484 "host", "port", "path-abempty", "query", "segment", "IP-literal", 2485 "IPv4address" and "reg-name" are adopted from [RFC3986]. 2487 Implementation Note: Unfortunately, over time the URI format has 2488 acquired significant complexity. Implementers are encouraged to 2489 examine [RFC3986] closely. E.g., the ABNF for IPv6 addresses is 2490 more complicated than maybe expected. Also, implementers should 2491 take care to perform the processing of percent decoding/encoding 2492 exactly once on the way from a URI to its decoded components or 2493 back. Percent encoding is crucial for data transparency, but may 2494 lead to unusual results such as a slash in a path component. 2496 6.1. coap URI Scheme 2498 coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] 2500 If the host component is provided as an IP-literal or IPv4address, 2501 then the CoAP server can be reached at that IP address. If host is a 2502 registered name, then that name is considered an indirect identifier 2503 and the endpoint might use a name resolution service, such as DNS, to 2504 find the address of that host. The host MUST NOT be empty; if a URI 2505 is received with a missing authority or an empty host, then it MUST 2506 be considered invalid. The port subcomponent indicates the UDP port 2507 at which the CoAP server is located. If it is empty or not given, 2508 then the default port 5683 is assumed. 2510 The path identifies a resource within the scope of the host and port. 2511 It consists of a sequence of path segments separated by a slash 2512 character (U+002F SOLIDUS "/"). 2514 The query serves to further parameterize the resource. It consists 2515 of a sequence of arguments separated by an ampersand character 2516 (U+0026 AMPERSAND "&"). An argument is often in the form of a 2517 "key=value" pair. 2519 The "coap" URI scheme supports the path prefix "/.well-known/" 2520 defined by [RFC5785] for "well-known locations" in the name-space of 2521 a host. This enables discovery of policy or other information about 2522 a host ("site-wide metadata"), such as hosted resources (see 2523 Section 7). 2525 Application designers are encouraged to make use of short, but 2526 descriptive URIs. As the environments that CoAP is used in are 2527 usually constrained for bandwidth and energy, the trade-off between 2528 these two qualities should lean towards the shortness, without 2529 ignoring descriptiveness. 2531 6.2. coaps URI Scheme 2533 coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty 2534 [ "?" query ] 2536 All of the requirements listed above for the "coap" scheme are also 2537 requirements for the "coaps" scheme, except that a default UDP port 2538 of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or 2539 not given, and the UDP datagrams MUST be secured for privacy through 2540 the use of DTLS as described in Section 9.1. 2542 Unlike the "coap" scheme, responses to "coaps" identified requests 2543 are never "public" and thus MUST NOT be reused for shared caching 2544 unless the cache is able to make equivalent access control decisions 2545 to the ones that led to the cached entry (Section 11.2). They can, 2546 however, be reused in a private cache if the message is cacheable by 2547 default in CoAP. 2549 Resources made available via the "coaps" scheme have no shared 2550 identity with the "coap" scheme even if their resource identifiers 2551 indicate the same authority (the same host listening to the same UDP 2552 port). They are distinct name spaces and are considered to be 2553 distinct origin servers. 2555 6.3. Normalization and Comparison Rules 2557 Since the "coap" and "coaps" schemes conform to the URI generic 2558 syntax, such URIs are normalized and compared according to the 2559 algorithm defined in [RFC3986], Section 6, using the defaults 2560 described above for each scheme. 2562 If the port is equal to the default port for a scheme, the normal 2563 form is to elide the port subcomponent. Likewise, an empty path 2564 component is equivalent to an absolute path of "/", so the normal 2565 form is to provide a path of "/" instead. The scheme and host are 2566 case-insensitive and normally provided in lowercase; IP-literals are 2567 in recommended form [RFC5952]; all other components are compared in a 2568 case-sensitive manner. Characters other than those in the "reserved" 2569 set are equivalent to their percent-encoded octets (see [RFC3986], 2570 Section 2.1): the normal form is to not encode them. 2572 For example, the following three URIs are equivalent, and cause the 2573 same options and option values to appear in the CoAP messages: 2575 coap://example.com:5683/~sensors/temp.xml 2576 coap://EXAMPLE.com/%7Esensors/temp.xml 2577 coap://EXAMPLE.com:/%7esensors/temp.xml 2579 6.4. Decomposing URIs into Options 2581 The steps to parse a request's options from a string /url/ are as 2582 follows. These steps either result in zero or more of the Uri-Host, 2583 Uri-Port, Uri-Path and Uri-Query Options being included in the 2584 request, or they fail. 2586 1. If the /url/ string is not an absolute URI ([RFC3986]), then fail 2587 this algorithm. 2589 2. Resolve the /url/ string using the process of reference 2590 resolution defined by [RFC3986], with the URL character encoding 2591 set to UTF-8 [RFC3629]. 2593 NOTE: It doesn't matter what it is resolved relative to, since we 2594 already know it is an absolute URL at this point. 2596 3. If /url/ does not have a component whose value, when 2597 converted to ASCII lowercase, is "coap" or "coaps", then fail 2598 this algorithm. 2600 4. If /url/ has a component, then fail this algorithm. 2602 5. If the component of /url/ does not represent the request's 2603 destination IP address as an IP-literal or IPv4address, include a 2604 Uri-Host Option and let that option's value be the value of the 2605 component of /url/, converted to ASCII lowercase, and then 2606 converting all percent-encodings ("%" followed by two hexadecimal 2607 digits) to the corresponding characters. 2609 NOTE: In the usual case where the request's destination IP 2610 address is derived from the host part, this ensures that a Uri- 2611 Host Option is only used for a component of the form reg- 2612 name. 2614 6. If /url/ has a component, then let /port/ be that 2615 component's value interpreted as a decimal integer; otherwise, 2616 let /port/ be the default port for the scheme. 2618 7. If /port/ does not equal the request's destination UDP port, 2619 include a Uri-Port Option and let that option's value be /port/. 2621 8. If the value of the component of /url/ is empty or 2622 consists of a single slash character (U+002F SOLIDUS "/"), then 2623 move to the next step. 2625 Otherwise, for each segment in the component, include a 2626 Uri-Path Option and let that option's value be the segment (not 2627 including the delimiting slash characters) after converting all 2628 percent-encodings ("%" followed by two hexadecimal digits) to the 2629 corresponding characters. 2631 9. If /url/ has a component, then, for each argument in the 2632 component, include a Uri-Query Option and let that 2633 option's value be the argument (not including the question mark 2634 and the delimiting ampersand characters) after converting all 2635 percent-encodings to the corresponding characters. 2637 Note that these rules completely resolve any percent-encoding. 2639 6.5. Composing URIs from Options 2641 The steps to construct a URI from a request's options are as follows. 2642 These steps either result in a URI, or they fail. In these steps, 2643 percent-encoding a character means replacing each of its (UTF-8 2644 encoded) bytes by a "%" character followed by two hexadecimal digits 2645 representing the byte, where the digits A-F are in upper case (as 2646 defined in [RFC3986] Section 2.1; to reduce variability, the 2647 hexadecimal notation for percent-encoding in CoAP URIs MUST use 2648 uppercase letters). The definitions of "unreserved" and "sub-delims" 2649 are adopted from [RFC3986]. 2651 1. If the request is secured using DTLS, let /url/ be the string 2652 "coaps://". Otherwise, let /url/ be the string "coap://". 2654 2. If the request includes a Uri-Host Option, let /host/ be that 2655 option's value, where any non-ASCII characters are replaced by 2656 their corresponding percent-encoding. If /host/ is not a valid 2657 reg-name or IP-literal or IPv4address, fail the algorithm. If 2658 the request does not include a Uri-Host Option, let /host/ be 2659 the IP-literal (making use of the conventions of [RFC5952]) or 2660 IPv4address representing the request's destination IP address. 2662 3. Append /host/ to /url/. 2664 4. If the request includes a Uri-Port Option, let /port/ be that 2665 option's value. Otherwise, let /port/ be the request's 2666 destination UDP port. 2668 5. If /port/ is not the default port for the scheme, then append a 2669 single U+003A COLON character (:) followed by the decimal 2670 representation of /port/ to /url/. 2672 6. Let /resource name/ be the empty string. For each Uri-Path 2673 Option in the request, append a single character U+002F SOLIDUS 2674 (/) followed by the option's value to /resource name/, after 2675 converting any character that is not either in the "unreserved" 2676 set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL 2677 AT (@) character, to its percent-encoded form. 2679 7. If /resource name/ is the empty string, set it to a single 2680 character U+002F SOLIDUS (/). 2682 8. For each Uri-Query Option in the request, append a single 2683 character U+003F QUESTION MARK (?) (first option) or U+0026 2684 AMPERSAND (&) (subsequent options) followed by the option's 2685 value to /resource name/, after converting any character that is 2686 not either in the "unreserved" set, "sub-delims" set (except 2687 U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT 2688 (@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, 2689 to its percent-encoded form. 2691 9. Append /resource name/ to /url/. 2693 10. Return /url/. 2695 Note that these steps have been designed to lead to a URI in normal 2696 form (see Section 6.3). 2698 7. Discovery 2700 7.1. Service Discovery 2702 A server is discovered by a client by the client knowing or learning 2703 a URI that references a resource in the namespace of the server. 2704 Alternatively, clients can use Multicast CoAP (see Section 8) and the 2705 "All CoAP Nodes" multicast address to find CoAP servers. 2707 Unless the port subcomponent in a "coap" or "coaps" URI indicates the 2708 UDP port at which the CoAP server is located, the server is assumed 2709 to be reachable at the default port. 2711 The CoAP default port number 5683 MUST be supported by a server that 2712 offers resources for resource discovery (see Section 7.2 below) and 2713 SHOULD be supported for providing access to other resources. The 2714 default port number [IANA_TBD_PORT] for DTLS-secured CoAP MAY be 2715 supported by a server for resource discovery and for providing access 2716 to other resources. In addition other endpoints may be hosted at 2717 other ports, e.g. in the dynamic port space. 2719 Implementation Note: When a CoAP server is hosted by a 6LoWPAN node, 2720 header compression efficiency is improved when it also supports a 2721 port number in the 61616-61631 compressed UDP port space defined 2722 in [RFC4944] (note that, as its UDP port differs from the default 2723 port, it is a different endpoint from the server at the default 2724 port). 2726 7.2. Resource Discovery 2728 The discovery of resources offered by a CoAP endpoint is extremely 2729 important in machine-to-machine applications where there are no 2730 humans in the loop and static interfaces result in fragility. A CoAP 2731 endpoint SHOULD support the CoRE Link Format of discoverable 2732 resources as described in [RFC6690]. It is up to the server which 2733 resources are made discoverable (if any). 2735 7.2.1. 'ct' Attribute 2737 This section defines a new Web Linking [RFC5988] attribute for use 2738 with [RFC6690]. The Content-Format code "ct" attribute provides a 2739 hint about the Content-Formats this resource returns. Note that this 2740 is only a hint, and does not override the Content-Format Option of a 2741 CoAP response obtained by actually requesting the representation of 2742 the resource. The value is in the CoAP identifier code format as a 2743 decimal ASCII integer and MUST be in the range of 0-65535 (16-bit 2744 unsigned integer). For example application/xml would be indicated as 2745 "ct=41". If no Content-Format code attribute is present then nothing 2746 about the type can be assumed. The Content-Format code attribute MAY 2747 include a space-separated sequence of Content-Format codes, 2748 indicating that multiple content-formats are available. The syntax 2749 of the attribute value is summarized in the production ct-value in 2750 Figure 13, where cardinal, SP and DQUOTE are defined as in [RFC6690]. 2752 ct-value = cardinal 2753 / DQUOTE cardinal *( 1*SP cardinal ) DQUOTE 2755 Figure 13 2757 8. Multicast CoAP 2759 CoAP supports making requests to a IP multicast group. This is 2760 defined by a series of deltas to Unicast CoAP. 2762 CoAP endpoints that offer services that they want other endpoints to 2763 be able to find using multicast service discovery, join one or more 2764 of the appropriate all-CoAP-nodes multicast addresses Section 12.8 2765 and listen on the default CoAP port. Note that an endpoint might 2766 receive multicast requests on other multicast addresses, including 2767 the all-nodes IPv6 address (or via broadcast on IPv4); an endpoint 2768 MUST therefore be prepared to receive such messages but MAY ignore 2769 them if multicast service discovery is not desired. 2771 8.1. Messaging Layer 2773 A multicast request is characterized by being transported in a CoAP 2774 message that is addressed to an IP multicast address instead of a 2775 CoAP endpoint. Such multicast requests MUST be Non-Confirmable. 2777 A server SHOULD be aware that a request arrived via multicast, e.g. 2778 by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 2779 available. 2781 When a server is aware that a request arrived via multicast, it MUST 2782 NOT return a RST in reply to NON. If it is not aware, it MAY return 2783 a RST in reply to NON as usual. Because such a Reset message will 2784 look identical to an RST for a unicast message from the sender, the 2785 sender MUST avoid using a Message ID that is also still active from 2786 this endpoint with any unicast endpoint that might receive the 2787 multicast message. 2789 8.2. Request/Response Layer 2791 When a server is aware that a request arrived via multicast, the 2792 server MAY always pretend it did not receive the request, in 2793 particular if it doesn't have anything useful to respond (e.g., if it 2794 only has an empty payload or an error response). The decision for 2795 this may depend on the application. (For example, in [RFC6690] query 2796 filtering, a server should not respond to a multicast request if the 2797 filter does not match.) 2799 If a server does decide to respond to a multicast request, it should 2800 not respond immediately. Instead, it should pick a duration for the 2801 period of time during which it intends to respond. For purposes of 2802 this exposition, we call the length of this period the Leisure. The 2803 specific value of this Leisure may depend on the application, or MAY 2804 be derived as described below. The server SHOULD then pick a random 2805 point of time within the chosen Leisure period to send back the 2806 unicast response to the multicast request. If further responses need 2807 to be sent based on the same multicast address membership, a new 2808 leisure period starts at the earliest after the previous one 2809 finishes. 2811 To compute a value for Leisure, the server should have a group size 2812 estimate G, a target data transfer rate R (which both should be 2813 chosen conservatively) and an estimated response size S; a rough 2814 lower bound for Leisure can then be computed as 2815 lb_Leisure = S * G / R 2817 E.g., for a multicast request with link-local scope on an 2.4 GHz 2818 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 2819 conservatively) set to 100, S to 100 bytes, and the target rate to a 2820 conservative 8 kbit/s = 1 kB/s. The resulting lower bound for the 2821 Leisure is 10 seconds. 2823 If a CoAP endpoint does not have suitable data to compute a value for 2824 Leisure, it MAY resort to DEFAULT_LEISURE. 2826 When matching a response to a multicast request, only the token MUST 2827 match; the source endpoint of the response does not need to (and will 2828 not) be the same as the destination endpoint of the original request. 2830 8.2.1. Caching 2832 When a client makes a multicast request, it always makes a new 2833 request to the multicast group (since there may be new group members 2834 that joined meanwhile or ones that did not get the previous request). 2835 It MAY update the cache with the received responses. Then it uses 2836 both cached-still-fresh and 'new' responses as the result of the 2837 request. 2839 A response received in reply to a GET request to a multicast group 2840 MAY be used to satisfy a subsequent request on the related unicast 2841 request URI. The unicast request URI is obtained by replacing the 2842 authority part of the request URI with the transport layer source 2843 address of the response message. 2845 A cache MAY revalidate a response by making a GET request on the 2846 related unicast request URI. 2848 A GET request to a multicast group MUST NOT contain an ETag option. 2849 A mechanism to suppress responses the client already has is left for 2850 further study. 2852 8.2.2. Proxying 2854 When a forward-proxy receives a request with a Proxy-Uri that 2855 indicates a multicast address, the proxy obtains a set of responses 2856 as described above and sends all responses (both cached-still-fresh 2857 and new) back to the original client. 2859 9. Securing CoAP 2861 This section defines the DTLS binding for CoAP, and the alternative 2862 use of IPsec. 2864 During the provisioning phase, a CoAP device is provided with the 2865 security information that it needs, including keying materials and 2866 access control lists. This specification defines provisioning for 2867 the RawPublicKey mode in Section 9.1.3.2.1. At the end of the 2868 provisioning phase, the device will be in one of four security modes 2869 with the following information for the given mode. The NoSec and 2870 RawPublicKey modes are mandatory to implement for this specification. 2872 NoSec: There is no protocol level security (DTLS is disabled). 2873 Alternative techniques to provide lower layer security SHOULD be 2874 used when appropriate. The use of IPsec is discussed in 2875 Section 9.2. 2877 PreSharedKey: DTLS is enabled and there is a list of pre-shared keys 2878 [RFC4279] and each key includes a list of which nodes it can be 2879 used to communicate with as described in Section 9.1.3.1. At the 2880 extreme there may be one key for each node this CoAP node needs to 2881 communicate with (1:1 node/key ratio). 2883 RawPublicKey: DTLS is enabled and the device has an asymmetric key 2884 pair without a certificate (a raw public key) that is validated 2885 using an out-of-band mechanism [I-D.ietf-tls-oob-pubkey] as 2886 described in Section 9.1.3.2. The device also has an identity 2887 calculated from the public key and a list of identities of the 2888 nodes it can communicate with. 2890 Certificate: DTLS is enabled and the device has an asymmetric key 2891 pair with an X.509 certificate [RFC5280] that binds it to its 2892 Authority Name and is signed by some common trust root as 2893 described in Section 9.1.3.3. The device also has a list of root 2894 trust anchors that can be used for validating a certificate. 2896 In the "NoSec" mode, the system simply sends the packets over normal 2897 UDP over IP and is indicated by the "coap" scheme and the CoAP 2898 default port. The system is secured only by keeping attackers from 2899 being able to send or receive packets from the network with the CoAP 2900 nodes; see Section 11.5 for an additional complication with this 2901 approach. 2903 The other three security modes are achieved using DTLS and are 2904 indicated by the "coaps" scheme and DTLS-secured CoAP default port. 2905 The result is a security association that can be used to authenticate 2906 (within the limits of the security model) and, based on this 2907 authentication, authorize the communication partner. CoAP itself 2908 does not provide protocol primitives for authentication or 2909 authorization; where this is required, it can either be provided by 2910 communication security (i.e., IPsec or DTLS) or by object security 2911 (within the payload). Devices that require authorization for certain 2912 operations are expected to require one of these two forms of 2913 security. Necessarily, where an intermediary is involved, 2914 communication security only works when that intermediary is part of 2915 the trust relationships; CoAP does not provide a way to forward 2916 different levels of authorization that clients may have with an 2917 intermediary to further intermediaries or origin servers -- it 2918 therefore may be required to perform all authorization at the first 2919 intermediary. 2921 9.1. DTLS-secured CoAP 2923 Just as HTTP is secured using Transport Layer Security (TLS) over 2924 TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP 2925 (see Figure 14). This section defines the CoAP binding to DTLS, 2926 along with the minimal mandatory-to-implement configurations 2927 appropriate for constrained environments. The binding is defined by 2928 a series of deltas to Unicast CoAP. DTLS is in practice TLS with 2929 added features to deal with the unreliable nature of the UDP 2930 transport. 2932 +----------------------+ 2933 | Application | 2934 +----------------------+ 2935 +----------------------+ 2936 | Requests/Responses | 2937 |----------------------| CoAP 2938 | Messages | 2939 +----------------------+ 2940 +----------------------+ 2941 | DTLS | 2942 +----------------------+ 2943 +----------------------+ 2944 | UDP | 2945 +----------------------+ 2947 Figure 14: Abstract layering of DTLS-secured CoAP 2949 In some constrained nodes (limited flash and/or RAM) and networks 2950 (limited bandwidth or high scalability requirements), and depending 2951 on the specific cipher suites in use, all modes of DTLS may not be 2952 applicable. Some DTLS cipher suites can add significant 2953 implementation complexity as well as some initial handshake overhead 2954 needed when setting up the security association. Once the initial 2955 handshake is completed, DTLS adds a limited per-datagram overhead of 2956 approximately 13 bytes, not including any initialization vectors/ 2957 nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]), 2958 integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 2959 [RFC6655]) and padding required by the cipher suite. Whether and 2960 which mode of using DTLS is applicable for a CoAP-based application 2961 should be carefully weighed considering the specific cipher suites 2962 that may be applicable, and whether the session maintenance makes it 2963 compatible with application flows and sufficient resources are 2964 available on the constrained nodes and for the added network 2965 overhead. DTLS is not applicable to group keying (multicast 2966 communication); however, it may be a component in a future group key 2967 management protocol. 2969 9.1.1. Messaging Layer 2971 The endpoint acting as the CoAP client should also act as the DTLS 2972 client. It should initiate a session to the server on the 2973 appropriate port. When the DTLS handshake has finished, the client 2974 may initiate the first CoAP request. All CoAP messages MUST be sent 2975 as DTLS "application data". 2977 The following rules are added for matching an ACK or RST to a CON 2978 message or a RST to a NON message: The DTLS session MUST be the same 2979 and the epoch MUST be the same. 2981 A message is the same when it is sent within the same DTLS session 2982 and same epoch and has the same Message ID. 2984 Note: When a confirmable message is retransmitted, a new DTLS 2985 sequence_number is used for each attempt, even though the CoAP 2986 Message ID stays the same. So a recipient still has to perform 2987 deduplication as described in Section 4.5. Retransmissions MUST NOT 2988 be performed across epochs. 2990 DTLS connections in RawPublicKey and Certificate mode are set up 2991 using mutual authentication so they can remain up and be reused for 2992 future message exchanges in either direction. Devices can close a 2993 DTLS connection when they need to recover resources but in general 2994 they should keep the connection up for as long as possible. Closing 2995 the DTLS connection after every CoAP message exchange is very 2996 inefficient. 2998 9.1.2. Request/Response Layer 3000 The following rules are added for matching a response to a request: 3001 The DTLS session MUST be the same and the epoch MUST be the same. 3003 9.1.3. Endpoint Identity 3005 Devices SHOULD support the Server Name Indication (SNI) to indicate 3006 their Authority Name in the SNI HostName field as defined in Section 3007 3 of [RFC6066]. This is needed so that when a host that acts as a 3008 virtual server for multiple Authorities receives a new DTLS 3009 connection, it knows which keys to use for the DTLS session. 3011 9.1.3.1. Pre-Shared Keys 3013 When forming a connection to a new node, the system selects an 3014 appropriate key based on which nodes it is trying to reach and then 3015 forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. 3016 Implementations in these modes MUST support the mandatory to 3017 implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in 3018 [RFC6655]. 3020 The security considerations of [RFC4279] (Section 7) apply. In 3021 particular, applications should carefully weigh whether they need 3022 Perfect Forward Secrecy (PFS) or not and select an appropriate cipher 3023 suite (7.1). The entropy of the PSK must be sufficient to mitigate 3024 against brute-force and (where the PSK is not chosen randomly but by 3025 a human) dictionary attacks (7.2). The cleartext communication of 3026 client identities may leak data or compromise privacy (7.3). 3028 9.1.3.2. Raw Public Key Certificates 3030 In this mode the device has an asymmetric key pair but without an 3031 X.509 certificate (called a raw public key). A device MAY be 3032 configured with multiple raw public keys. The type and length of the 3033 raw public key depends on the cipher suite used. Implementations in 3034 RawPublicKey mode MUST support the mandatory to implement cipher 3035 suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in 3036 [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. The mechanism 3037 for using raw public keys with TLS is specified in 3038 [I-D.ietf-tls-oob-pubkey]. 3040 9.1.3.2.1. Provisioning 3042 The RawPublicKey mode was designed to be easily provisioned in M2M 3043 deployments. It is assumed that each device has an appropriate 3044 asymmetric public key pair installed. An identifier is calculated 3045 from the public key as described in Section 2 of 3046 [I-D.farrell-decade-ni]. All implementations that support checking 3047 RawPublicKey identities MUST support at least the sha-256-120 mode 3048 (SHA-256 truncated to 120 bits). Implementations SHOULD support also 3049 longer length identifiers and MAY support shorter lengths. Note that 3050 the shorter lengths provide less security against attacks and their 3051 use is NOT RECOMMENDED. 3053 Depending on how identifiers are given to the system that verifies 3054 them, support for URI, binary, and/or human-speakable format 3055 [I-D.farrell-decade-ni] needs to be implemented. All implementations 3056 SHOULD support the binary mode and implementations that have a user 3057 interface SHOULD also support the human-speakable format. 3059 During provisioning, the identifier of each node is collected, for 3060 example by reading a barcode on the outside of the device or by 3061 obtaining a pre-compiled list of the identifiers. These identifiers 3062 are then installed in the corresponding endpoint, for example an M2M 3063 data collection server. The identifier is used for two purposes, to 3064 associate the endpoint with further device information and to perform 3065 access control. During provisioning, an access control list of 3066 identifiers the device may start DTLS sessions with SHOULD also be 3067 installed. 3069 9.1.3.3. X.509 Certificates 3071 Implementations in Certificate Mode MUST support the mandatory to 3072 implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as 3073 specified in [RFC5246]. 3075 The Authority Name in the certificate is the name that would be used 3076 in the Authority part of a CoAP URI. It is worth noting that this 3077 would typically not be either an IP address or DNS name but would 3078 instead be a long term unique identifier for the device such as the 3079 EUI-64 [EUI64]. The discovery process used in the system would build 3080 up the mapping between IP addresses of the given devices and the 3081 Authority Name for each device. Some devices could have more than 3082 one Authority and would need more than a single certificate. 3084 When a new connection is formed, the certificate from the remote 3085 device needs to be verified. If the CoAP node has a source of 3086 absolute time, then the node SHOULD check that the validity dates of 3087 the certificate are within range. The certificate MUST also be 3088 signed by an appropriate chain of trust. If the certificate contains 3089 a SubjectAltName, then the Authority Name MUST match at least one of 3090 the authority names of any CoAP URI found in a URI type field in the 3091 SubjectAltName set. If there is no SubjectAltName in the 3092 certificate, then the Authoritative Name must match the CN found in 3093 the certificate using the matching rules defined in [RFC2818] with 3094 the exception that certificates with wildcards are not allowed. 3096 If the system has a shared key in addition to the certificate, then a 3097 cipher suite that includes the shared key such as 3098 TLS_RSA_PSK_WITH_AES_128_CBC_SHA [RFC4279] SHOULD be used. 3100 9.2. Using CoAP with IPsec 3102 One mechanism to secure CoAP in constrained environments is the IPsec 3103 Encapsulating Security Payload (ESP) [RFC4303] when CoAP is used 3104 without DTLS in NoSec Mode. Using IPsec ESP with the appropriate 3105 configuration, it is possible for many constrained devices to support 3106 encryption with built-in link-layer encryption hardware. For 3107 example, some IEEE 802.15.4 radio chips are compatible with AES-CBC 3108 (with 128-bit keys) [RFC3602] as defined for use with IPsec in 3109 [RFC4835]. Alternatively, particularly on more common IEEE 802.15.4 3110 hardware that supports AES encryption but not decryption, and to 3111 avoid the need for padding, nodes could directly use the more widely 3112 supported AES-CCM as defined for use with IPsec in [RFC4309], if the 3113 security considerations in Section 9 of that specification can be 3114 fulfilled. 3116 Necessarily for AES-CCM, but much preferably also for AES-CBC, static 3117 keying should be avoided and the initial keying material be derived 3118 into transient session keys, e.g. using a low-overhead mode of IKEv2 3119 [RFC5996] as described in [I-D.kivinen-ipsecme-ikev2-minimal]; such a 3120 protocol for managing keys and sequence numbers is also the only way 3121 to achieve anti-replay capabilities. However, no recommendation can 3122 be made at this point on how to manage group keys (i.e., for 3123 multicast) in a constrained environment. Once any initial setup is 3124 completed, IPsec ESP adds a limited overhead of approximately 10 3125 bytes per packet, not including initialization vectors, integrity 3126 check values and padding required by the cipher suite. 3128 When using IPsec to secure CoAP, both authentication and 3129 confidentiality SHOULD be applied as recommended in [RFC4303]. The 3130 use of IPsec between CoAP endpoints is transparent to the application 3131 layer and does not require special consideration for a CoAP 3132 implementation. 3134 IPsec may not be appropriate for all environments. For example, 3135 IPsec support is not available for many embedded IP stacks and even 3136 in full PC operating systems or on back-end web servers, application 3137 developers may not have sufficient access to configure or enable 3138 IPsec or to add a security gateway to the infrastructure. Problems 3139 with firewalls and NATs may furthermore limit the use of IPsec. 3141 10. Cross-Protocol Proxying between CoAP and HTTP 3143 CoAP supports a limited subset of HTTP functionality, and thus cross- 3144 protocol proxying to HTTP is straightforward. There might be several 3145 reasons for proxying between CoAP and HTTP, for example when 3146 designing a web interface for use over either protocol or when 3147 realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied 3148 to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the 3149 definition of these mechanisms is out of scope of this specification. 3151 There are two possible directions to access a resource via a forward- 3152 proxy: 3154 CoAP-HTTP Proxying: Enables CoAP clients to access resources on HTTP 3155 servers through an intermediary. This is initiated by including 3156 the Proxy-Uri Option with an "http" or "https" URI in a CoAP 3157 request to a CoAP-HTTP proxy. 3159 HTTP-CoAP Proxying: Enables HTTP clients to access resources on CoAP 3160 servers through an intermediary. This is initiated by specifying 3161 a "coap" or "coaps" URI in the Request-Line of an HTTP request to 3162 an HTTP-CoAP proxy. 3164 Either way, only the Request/Response model of CoAP is mapped to 3165 HTTP. The underlying model of confirmable or non-confirmable 3166 messages, etc., is invisible and MUST have no effect on a proxy 3167 function. The following sections describe the handling of requests 3168 to a forward-proxy. Reverse proxies are not specified as the proxy 3169 function is transparent to the client with the proxy acting as if it 3170 was the origin server. 3172 10.1. CoAP-HTTP Proxying 3174 If a request contains a Proxy-URI Option with an 'http' or 'https' 3175 URI [RFC2616], then the receiving CoAP endpoint (called "the proxy" 3176 henceforth) is requested to perform the operation specified by the 3177 request method on the indicated HTTP resource and return the result 3178 to the client. 3180 This section specifies for any CoAP request the CoAP response that 3181 the proxy should return to the client. How the proxy actually 3182 satisfies the request is an implementation detail, although the 3183 typical case is expected to be the proxy translating and forwarding 3184 the request to an HTTP origin server. 3186 Since HTTP and CoAP share the basic set of request methods, 3187 performing a CoAP request on an HTTP resource is not so different 3188 from performing it on a CoAP resource. The meanings of the 3189 individual CoAP methods when performed on HTTP resources are 3190 explained below. 3192 If the proxy is unable or unwilling to service a request with an HTTP 3193 URI, a 5.05 (Proxying Not Supported) response is returned to the 3194 client. If the proxy services the request by interacting with a 3195 third party (such as the HTTP origin server) and is unable to obtain 3196 a result within a reasonable time frame, a 5.04 (Gateway Timeout) 3197 response is returned; if a result can be obtained but is not 3198 understood, a 5.02 (Bad Gateway) response is returned. 3200 10.1.1. GET 3202 The GET method requests the proxy to return a representation of the 3203 HTTP resource identified by the request URI. 3205 Upon success, a 2.05 (Content) response code SHOULD be returned. The 3206 payload of the response MUST be a representation of the target HTTP 3207 resource, and the Content-Format Option be set accordingly. The 3208 response MUST indicate a Max-Age value that is no greater than the 3209 remaining time the representation can be considered fresh. If the 3210 HTTP entity has an entity tag, the proxy SHOULD include an ETag 3211 Option in the response and process ETag Options in requests as 3212 described below. 3214 A client can influence the processing of a GET request by including 3215 the following option: 3217 Accept: The request MAY include one or more Accept Options, 3218 identifying the preferred response content-format. 3220 ETag: The request MAY include one or more ETag Options, identifying 3221 responses that the client has stored. This requests the proxy to 3222 send a 2.03 (Valid) response whenever it would send a 2.05 3223 (Content) response with an entity tag in the requested set 3224 otherwise. Note that CoAP ETags are always strong ETags in the 3225 HTTP sense; CoAP does not have the equivalent of HTTP weak ETags, 3226 and there is no good way to make use of these in a cross-proxy. 3228 10.1.2. PUT 3230 The PUT method requests the proxy to update or create the HTTP 3231 resource identified by the request URI with the enclosed 3232 representation. 3234 If a new resource is created at the request URI, a 2.01 (Created) 3235 response MUST be returned to the client. If an existing resource is 3236 modified, a 2.04 (Changed) response MUST be returned to indicate 3237 successful completion of the request. 3239 10.1.3. DELETE 3241 The DELETE method requests the proxy to delete the HTTP resource 3242 identified by the request URI at the HTTP origin server. 3244 A 2.02 (Deleted) response MUST be returned to client upon success or 3245 if the resource does not exist at the time of the request. 3247 10.1.4. POST 3249 The POST method requests the proxy to have the representation 3250 enclosed in the request be processed by the HTTP origin server. The 3251 actual function performed by the POST method is determined by the 3252 origin server and dependent on the resource identified by the request 3253 URI. 3255 If the action performed by the POST method does not result in a 3256 resource that can be identified by a URI, a 2.04 (Changed) response 3257 MUST be returned to the client. If a resource has been created on 3258 the origin server, a 2.01 (Created) response MUST be returned. 3260 10.2. HTTP-CoAP Proxying 3262 If an HTTP request contains a Request-URI with a 'coap' or 'coaps' 3263 URI, then the receiving HTTP endpoint (called "the proxy" henceforth) 3264 is requested to perform the operation specified by the request method 3265 on the indicated CoAP resource and return the result to the client. 3267 This section specifies for any HTTP request the HTTP response that 3268 the proxy should return to the client. How the proxy actually 3269 satisfies the request is an implementation detail, although the 3270 typical case is expected to be the proxy translating and forwarding 3271 the request to a CoAP origin server. The meanings of the individual 3272 HTTP methods when performed on CoAP resources are explained below. 3274 If the proxy is unable or unwilling to service a request with a CoAP 3275 URI, a 501 (Not Implemented) response SHOULD be returned to the 3276 client. If the proxy services the request by interacting with a 3277 third party (such as the CoAP origin server) and is unable to obtain 3278 a result within a reasonable time frame, a 504 (Gateway Timeout) 3279 response SHOULD be returned; if a result can be obtained but is not 3280 understood, a 502 (Bad Gateway) response SHOULD be returned. 3282 10.2.1. OPTIONS and TRACE 3284 As the OPTIONS and TRACE methods are not supported in CoAP a 501 (Not 3285 Implemented) error MUST be returned to the client. 3287 10.2.2. GET 3289 The GET method requests the proxy to return a representation of the 3290 CoAP resource identified by the Request-URI. 3292 Upon success, a 200 (OK) response SHOULD be returned. The payload of 3293 the response MUST be a representation of the target CoAP resource, 3294 and the Content-Type and Content-Encoding header fields be set 3295 accordingly. The response MUST indicate a max-age directive that 3296 indicates a value no greater than the remaining time the 3297 representation can be considered fresh. If the CoAP response has an 3298 ETag option, the proxy SHOULD include an ETag header field in the 3299 response. 3301 A client can influence the processing of a GET request by including 3302 the following options: 3304 Accept: Each individual Media-type of the HTTP Accept header in a 3305 request is mapped to a CoAP Accept option. HTTP Accept Media-type 3306 ranges, parameters and extensions are not supported by the CoAP 3307 Accept option. If the proxy cannot send a response which is 3308 acceptable according to the combined Accept field value, then the 3309 proxy SHOULD send a 406 (not acceptable) response. 3311 Conditional GETs: Conditional HTTP GET requests that include an "If- 3312 Match" or "If-None-Match" request-header field can be mapped to a 3313 corresponding CoAP request. The "If-Modified-Since" and "If- 3314 Unmodified-Since" request-header fields are not directly supported 3315 by CoAP, but SHOULD be implemented locally by a caching proxy. 3317 10.2.3. HEAD 3319 The HEAD method is identical to GET except that the server MUST NOT 3320 return a message-body in the response. 3322 Although there is no direct equivalent of HTTP's HEAD method in CoAP, 3323 an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and 3324 the HTTP headers are returned without a message-body. 3326 Implementation Note: An HTTP-CoAP proxy may want to try using a 3327 block-wise transfer [I-D.ietf-core-block] option to minimize the 3328 amount of data actually transferred, but needs to be prepared for 3329 the case that the origin server does not support block-wise 3330 transfers. 3332 10.2.4. POST 3334 The POST method requests the proxy to have the representation 3335 enclosed in the request be processed by the CoAP origin server. The 3336 actual function performed by the POST method is determined by the 3337 origin server and dependent on the resource identified by the request 3338 URI. 3340 If the action performed by the POST method does not result in a 3341 resource that can be identified by a URI, a 200 (OK) or 204 (No 3342 Content) response MUST be returned to the client. If a resource has 3343 been created on the origin server, a 201 (Created) response MUST be 3344 returned. 3346 If any of the Location-* Options are present in the CoAP response, a 3347 Location header field constructed from the values of these options 3348 SHOULD be returned. 3350 10.2.5. PUT 3352 The PUT method requests the proxy to update or create the CoAP 3353 resource identified by the Request-URI with the enclosed 3354 representation. 3356 If a new resource is created at the Request-URI, a 201 (Created) 3357 response MUST be returned to the client. If an existing resource is 3358 modified, either the 200 (OK) or 204 (No Content) response codes 3359 SHOULD be sent to indicate successful completion of the request. 3361 10.2.6. DELETE 3363 The DELETE method requests the proxy to delete the CoAP resource 3364 identified by the Request-URI at the CoAP origin server. 3366 A successful response SHOULD be 200 (OK) if the response includes an 3367 entity describing the status or 204 (No Content) if the action has 3368 been enacted but the response does not include an entity. 3370 10.2.7. CONNECT 3372 This method can not currently be satisfied by an HTTP-CoAP proxy 3373 function as TLS to DTLS tunneling has not yet been specified. For 3374 now, a 501 (Not Implemented) error SHOULD be returned to the client. 3376 11. Security Considerations 3378 This section analyzes the possible threats to the protocol. It is 3379 meant to inform protocol and application developers about the 3380 security limitations of CoAP as described in this document. As CoAP 3381 realizes a subset of the features in HTTP/1.1, the security 3382 considerations in Section 15 of [RFC2616] are also pertinent to CoAP. 3383 This section concentrates on describing limitations specific to CoAP. 3385 11.1. Protocol Parsing, Processing URIs 3387 A network-facing application can exhibit vulnerabilities in its 3388 processing logic for incoming packets. Complex parsers are well- 3389 known as a likely source of such vulnerabilities, such as the ability 3390 to remotely crash a node, or even remotely execute arbitrary code on 3391 it. CoAP attempts to narrow the opportunities for introducing such 3392 vulnerabilities by reducing parser complexity, by giving the entire 3393 range of encodable values a meaning where possible, and by 3394 aggressively reducing complexity that is often caused by unnecessary 3395 choice between multiple representations that mean the same thing. 3396 Much of the URI processing has been moved to the clients, further 3397 reducing the opportunities for introducing vulnerabilities into the 3398 servers. Even so, the URI processing code in CoAP implementations is 3399 likely to be a large source of remaining vulnerabilities and should 3400 be implemented with special care. The most complex parser remaining 3401 could be the one for the CoRE Link Format, although this also has 3402 been designed with a goal of reduced implementation complexity 3403 [RFC6690]. (See also section 15.2 of [RFC2616].) 3405 11.2. Proxying and Caching 3407 As mentioned in 15.7 of [RFC2616], proxies are by their very nature 3408 men-in-the-middle, breaking any IPsec or DTLS protection that a 3409 direct CoAP message exchange might have. They are therefore 3410 interesting targets for breaking confidentiality or integrity of CoAP 3411 message exchanges. As noted in [RFC2616], they are also interesting 3412 targets for breaking availability. 3414 The threat to confidentiality and integrity of request/response data 3415 is amplified where proxies also cache. Note that CoAP does not 3416 define any of the cache-suppressing Cache-Control options that 3417 HTTP/1.1 provides to better protect sensitive data. 3419 For a caching implementation, any access control considerations that 3420 would apply to making the request that generated the cache entry also 3421 need to be applied to the value in the cache. This is relevant for 3422 clients that implement multiple security domains, as well as for 3423 proxies that may serve multiple clients. Also, a caching proxy MUST 3424 NOT make cached values available to requests that have lesser 3425 transport security properties than to which it would make available 3426 the process of forwarding the request in the first place. 3428 Finally, a proxy that fans out Separate Responses (as opposed to 3429 Piggy-backed Responses) to multiple original requesters may provide 3430 additional amplification (see below). 3432 11.3. Risk of amplification 3434 CoAP servers generally reply to a request packet with a response 3435 packet. This response packet may be significantly larger than the 3436 request packet. An attacker might use CoAP nodes to turn a small 3437 attack packet into a larger attack packet, an approach known as 3438 amplification. There is therefore a danger that CoAP nodes could 3439 become implicated in denial of service (DoS) attacks by using the 3440 amplifying properties of the protocol: An attacker that is attempting 3441 to overload a victim but is limited in the amount of traffic it can 3442 generate, can use amplification to generate a larger amount of 3443 traffic. 3445 This is particularly a problem in nodes that enable NoSec access, 3446 that are accessible from an attacker and can access potential victims 3447 (e.g. on the general Internet), as the UDP protocol provides no way 3448 to verify the source address given in the request packet. An 3449 attacker need only place the IP address of the victim in the source 3450 address of a suitable request packet to generate a larger packet 3451 directed at the victim. 3453 As a mitigating factor, many constrained networks will only be able 3454 to generate a small amount of traffic, which may make CoAP nodes less 3455 attractive for this attack. However, the limited capacity of the 3456 constrained network makes the network itself a likely victim of an 3457 amplification attack. 3459 A CoAP server can reduce the amount of amplification it provides to 3460 an attacker by using slicing/blocking modes of CoAP 3461 [I-D.ietf-core-block] and offering large resource representations 3462 only in relatively small slices. E.g., for a 1000 byte resource, a 3463 10-byte request might result in an 80-byte response (with a 64-byte 3464 block) instead of a 1016-byte response, considerably reducing the 3465 amplification provided. 3467 CoAP also supports the use of multicast IP addresses in requests, an 3468 important requirement for M2M. Multicast CoAP requests may be the 3469 source of accidental or deliberate denial of service attacks, 3470 especially over constrained networks. This specification attempts to 3471 reduce the amplification effects of multicast requests by limiting 3472 when a response is returned. To limit the possibility of malicious 3473 use, CoAP servers SHOULD NOT accept multicast requests that can not 3474 be authenticated. If possible a CoAP server SHOULD limit the support 3475 for multicast requests to specific resources where the feature is 3476 required. 3478 On some general purpose operating systems providing a Posix-style 3479 API, it is not straightforward to find out whether a packet received 3480 was addressed to a multicast address. While many implementations 3481 will know whether they have joined a multicast group, this creates a 3482 problem for packets addressed to multicast addresses of the form 3483 FF0x::1, which are received by every IPv6 node. Implementations 3484 SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 3485 available, to make this determination. 3487 11.4. IP Address Spoofing Attacks 3489 Due to the lack of a handshake in UDP, a rogue endpoint which is free 3490 to read and write messages carried by the constrained network (i.e. 3491 NoSec or PreSharedKey deployments with nodes/key ratio > 1:1), may 3492 easily attack a single endpoint, a group of endpoints, as well as the 3493 whole network e.g. by: 3495 1. spoofing RST in response to a CON or NON message, thus making an 3496 endpoint "deaf"; or 3498 2. spoofing the entire response with forged payload/options (this 3499 has different levels of impact: from single response disruption, 3500 to much bolder attacks on the supporting infrastructure, e.g. 3501 poisoning proxy caches, or tricking validation / lookup 3502 interfaces in resource directories and, more generally, any 3503 component that stores global network state and uses CoAP as the 3504 messaging facility to handle state set/update's is a potential 3505 target.); or 3507 3. spoofing a multicast request for a target node which may result 3508 in both network congestion/collapse and victim DoS'ing / forced 3509 wakeup from sleeping; or 3511 4. spoofing observe messages, etc. 3513 In principle, spoofing can be detected by CoAP only in case CON 3514 semantics is used, because of unexpected ACK/RSTs coming from the 3515 deceived endpoint. But this imposes keeping track of the used 3516 Message IDs which is not always possible, and moreover detection 3517 becomes available usually after the damage is already done. This 3518 kind of attack can be prevented using security modes other than 3519 NoSec. 3521 11.5. Cross-Protocol Attacks 3523 The ability to incite a CoAP endpoint to send packets to a fake 3524 source address can be used not only for amplification, but also for 3525 cross-protocol attacks against a victim listening to UDP packets at a 3526 given address (IP address and port): 3528 o the attacker sends a message to a CoAP endpoint with the given 3529 address as the fake source address, 3531 o the CoAP endpoint replies with a message to the given source 3532 address, 3534 o the victim at the given address receives a UDP packet that it 3535 interprets according to the rules of a different protocol. 3537 This may be used to circumvent firewall rules that prevent direct 3538 communication from the attacker to the victim, but happen to allow 3539 communication from the CoAP endpoint (which may also host a valid 3540 role in the other protocol) to the victim. 3542 Also, CoAP endpoints may be the victim of a cross-protocol attack 3543 generated through an endpoint of another UDP-based protocol such as 3544 DNS. In both cases, attacks are possible if the security properties 3545 of the endpoints rely on checking IP addresses (and firewalling off 3546 direct attacks sent from outside using fake IP addresses). In 3547 general, because of their lack of context, UDP-based protocols are 3548 relatively easy targets for cross-protocol attacks. 3550 Finally, CoAP URIs transported by other means could be used to incite 3551 clients to send messages to endpoints of other protocols. 3553 One mitigation against cross-protocol attacks is strict checking of 3554 the syntax of packets received, combined with sufficient difference 3555 in syntax. As an example, it might help if it were difficult to 3556 incite a DNS server to send a DNS response that would pass the checks 3557 of a CoAP endpoint. Unfortunately, the first two bytes of a DNS 3558 reply are an ID that can be chosen by the attacker, which map into 3559 the interesting part of the CoAP header, and the next two bytes are 3560 then interpreted as CoAP's Message ID (i.e., any value is 3561 acceptable). The DNS count words may be interpreted as multiple 3562 instances of a (non-existent, but elective) CoAP option 0. The 3563 echoed query finally may be manufactured by the attacker to achieve a 3564 desired effect on the CoAP endpoint; the response added by the server 3565 (if any) might then just be interpreted as added payload. 3567 1 1 1 1 1 1 3568 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 3569 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3570 | ID | T, OC, code 3571 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3572 |QR| Opcode |AA|TC|RD|RA| Z | RCODE | message id 3573 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3574 | QDCOUNT | (options 0) 3575 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3576 | ANCOUNT | (options 0) 3577 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3578 | NSCOUNT | (options 0) 3579 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3580 | ARCOUNT | (options 0) 3581 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3583 Figure 15: DNS Header vs. CoAP Message 3585 In general, for any pair of protocols, one of the protocols can very 3586 well have been designed in a way that enables an attacker to cause 3587 the generation of replies that look like messages of the other 3588 protocol. It is often much harder to ensure or prove the absence of 3589 viable attacks than to generate examples that may not yet completely 3590 enable an attack but might be further developed by more creative 3591 minds. Cross-protocol attacks can therefore only be completely 3592 mitigated if endpoints don't authorize actions desired by an attacker 3593 just based on trusting the source IP address of a packet. 3594 Conversely, a NoSec environment that completely relies on a firewall 3595 for CoAP security not only needs to firewall off the CoAP endpoints 3596 but also all other endpoints that might be incited to send UDP 3597 messages to CoAP endpoints using some other UDP-based protocol. 3599 In addition to the considerations above, the security considerations 3600 for DTLS with respect to cross-protocol attacks apply. E.g., if the 3601 same DTLS security association ("connection") is used to carry data 3602 of multiple protocols, DTLS no longer provides protection against 3603 cross-protocol attacks between these protocols. 3605 12. IANA Considerations 3607 12.1. CoAP Code Registry 3609 This document defines a registry for the values of the Code field in 3610 the CoAP header. The name of the registry is "CoAP Codes". 3612 All values are assigned by sub-registries according to the following 3613 ranges: 3615 0 Indicates an empty message (see Section 4.1). 3617 1-31 Indicates a request. Values in this range are assigned by 3618 the "CoAP Method Codes" sub-registry (see Section 12.1.1). 3620 32-63 Reserved 3622 64-191 Indicates a response. Values in this range are assigned by 3623 the "CoAP Response Codes" sub-registry (see 3624 Section 12.1.2). 3626 192-255 Reserved 3628 12.1.1. Method Codes 3630 The name of the sub-registry is "CoAP Method Codes". 3632 Each entry in the sub-registry must include the Method Code in the 3633 range 1-31, the name of the method, and a reference to the method's 3634 documentation. 3636 Initial entries in this sub-registry are as follows: 3638 +------+--------+-----------+ 3639 | Code | Name | Reference | 3640 +------+--------+-----------+ 3641 | 1 | GET | [RFCXXXX] | 3642 | 2 | POST | [RFCXXXX] | 3643 | 3 | PUT | [RFCXXXX] | 3644 | 4 | DELETE | [RFCXXXX] | 3645 +------+--------+-----------+ 3647 Table 2: CoAP Method Codes 3649 All other Method Codes are Unassigned. 3651 The IANA policy for future additions to this registry is "IETF 3652 Review" as described in [RFC5226]. 3654 The documentation of a method code should specify the semantics of a 3655 request with that code, including the following properties: 3657 o The response codes the method returns in the success case. 3659 o Whether the method is idempotent, safe, or both. 3661 12.1.2. Response Codes 3663 The name of the sub-registry is "CoAP Response Codes". 3665 Each entry in the sub-registry must include the Response Code in the 3666 range 64-191, a description of the Response Code, and a reference to 3667 the Response Code's documentation. 3669 Initial entries in this sub-registry are as follows: 3671 +------+---------------------------------+-----------+ 3672 | Code | Description | Reference | 3673 +------+---------------------------------+-----------+ 3674 | 65 | 2.01 Created | [RFCXXXX] | 3675 | 66 | 2.02 Deleted | [RFCXXXX] | 3676 | 67 | 2.03 Valid | [RFCXXXX] | 3677 | 68 | 2.04 Changed | [RFCXXXX] | 3678 | 69 | 2.05 Content | [RFCXXXX] | 3679 | 128 | 4.00 Bad Request | [RFCXXXX] | 3680 | 129 | 4.01 Unauthorized | [RFCXXXX] | 3681 | 130 | 4.02 Bad Option | [RFCXXXX] | 3682 | 131 | 4.03 Forbidden | [RFCXXXX] | 3683 | 132 | 4.04 Not Found | [RFCXXXX] | 3684 | 133 | 4.05 Method Not Allowed | [RFCXXXX] | 3685 | 134 | 4.06 Not Acceptable | [RFCXXXX] | 3686 | 140 | 4.12 Precondition Failed | [RFCXXXX] | 3687 | 141 | 4.13 Request Entity Too Large | [RFCXXXX] | 3688 | 143 | 4.15 Unsupported Content-Format | [RFCXXXX] | 3689 | 160 | 5.00 Internal Server Error | [RFCXXXX] | 3690 | 161 | 5.01 Not Implemented | [RFCXXXX] | 3691 | 162 | 5.02 Bad Gateway | [RFCXXXX] | 3692 | 163 | 5.03 Service Unavailable | [RFCXXXX] | 3693 | 164 | 5.04 Gateway Timeout | [RFCXXXX] | 3694 | 165 | 5.05 Proxying Not Supported | [RFCXXXX] | 3695 +------+---------------------------------+-----------+ 3697 Table 3: CoAP Response Codes 3699 The Response Codes 96-127 are Reserved for future use. All other 3700 Response Codes are Unassigned. 3702 The IANA policy for future additions to this registry is "IETF 3703 Review" as described in [RFC5226]. 3705 The documentation of a response code should specify the semantics of 3706 a response with that code, including the following properties: 3708 o The methods the response code applies to. 3710 o Whether payload is required, optional or not allowed. 3712 o The semantics of the payload. For example, the payload of a 2.05 3713 (Content) response is a representation of the target resource; the 3714 payload in an error response is a human-readable diagnostic 3715 message. 3717 o The format of the payload. For example, the format in a 2.05 3718 (Content) response is indicated by the Content-Format Option; the 3719 format of the payload in an error response is always Net-Unicode 3720 text. 3722 o Whether the response is cacheable according to the freshness 3723 model. 3725 o Whether the response is validatable according to the validation 3726 model. 3728 o Whether the response causes a cache to mark responses stored for 3729 the request URI as not fresh. 3731 12.2. Option Number Registry 3733 This document defines a registry for the Option Numbers used in CoAP 3734 options. The name of the registry is "CoAP Option Numbers". 3736 Each entry in the registry must include the Option Number, the name 3737 of the option and a reference to the option's documentation. 3739 Initial entries in this registry are as follows: 3741 +--------+----------------+-----------+ 3742 | Number | Name | Reference | 3743 +--------+----------------+-----------+ 3744 | 0 | (Reserved) | | 3745 | 1 | If-Match | [RFCXXXX] | 3746 | 3 | Uri-Host | [RFCXXXX] | 3747 | 4 | ETag | [RFCXXXX] | 3748 | 5 | If-None-Match | [RFCXXXX] | 3749 | 7 | Uri-Port | [RFCXXXX] | 3750 | 8 | Location-Path | [RFCXXXX] | 3751 | 11 | Uri-Path | [RFCXXXX] | 3752 | 12 | Content-Format | [RFCXXXX] | 3753 | 14 | Max-Age | [RFCXXXX] | 3754 | 15 | Uri-Query | [RFCXXXX] | 3755 | 16 | Accept | [RFCXXXX] | 3756 | 19 | Token | [RFCXXXX] | 3757 | 20 | Location-Query | [RFCXXXX] | 3758 | 35 | Proxy-Uri | [RFCXXXX] | 3759 | 128 | (Reserved) | [RFCXXXX] | 3760 | 132 | (Reserved) | [RFCXXXX] | 3761 | 136 | (Reserved) | [RFCXXXX] | 3762 +--------+----------------+-----------+ 3764 Table 4: CoAP Option Numbers 3766 The IANA policy for future additions to this registry is split into 3767 three tiers as follows. The range of 0..255 is reserved for options 3768 defined by the IETF (IETF Review). The range of 256..2047 is 3769 reserved for commonly used options with public specifications 3770 (Specification Required). The range of 2048..65535 is for all other 3771 options including private or vendor specific ones, which undergo a 3772 Designated Expert review to help ensure that the option semantics are 3773 defined correctly. 3775 +---------------+------------------------+ 3776 | Option Number | Policy [RFC5226] | 3777 +---------------+------------------------+ 3778 | 0..255 | IETF Review | 3779 | 256..2047 | Specification Required | 3780 | 2048..65535 | Designated Expert | 3781 +---------------+------------------------+ 3783 The documentation of an Option Number should specify the semantics of 3784 an option with that number, including the following properties: 3786 o The meaning of the option in a request. 3788 o The meaning of the option in a response. 3790 o Whether the option is critical or elective, as determined by the 3791 Option Number. 3793 o Whether the option is Safe, and whether it is part of the Cache- 3794 Key, as determined by the Option Number (see Section 5.4.2). 3796 o The format and length of the option's value. 3798 o Whether the option must occur at most once or whether it can occur 3799 multiple times. 3801 o The default value, if any. For a critical option with a default 3802 value, a discussion on how the default value enables processing by 3803 implementations not implementing the critical option 3804 (Section 5.4.4). 3806 12.3. Content-Format Registry 3808 Internet media types are identified by a string, such as 3809 "application/xml" [RFC2046]. In order to minimize the overhead of 3810 using these media types to indicate the format of payloads, this 3811 document defines a registry for a subset of Internet media types to 3812 be used in CoAP and assigns each, in combination with a content- 3813 coding, a numeric identifier. The name of the registry is "CoAP 3814 Content-Formats". 3816 Each entry in the registry must include the media type registered 3817 with IANA, the numeric identifier in the range 0-65535 to be used for 3818 that media type in CoAP, the content-coding associated with this 3819 identifier, and a reference to a document describing what a payload 3820 with that media type means semantically. 3822 CoAP does not include a way to convey content-encoding information 3823 with a request or response, and for that reason the content-encoding 3824 is also specified for each identifier (if any). If multiple content- 3825 encodings will be used with a media type, then a separate Content- 3826 Format identifier for each is to be registered. Similarly, other 3827 parameters related to an Internet media type, such as level, can be 3828 defined for a CoAP Content-Format entry. 3830 Initial entries in this registry are as follows: 3832 +--------------------+----------+-----+-----------------------------+ 3833 | Media type | Encoding | Id. | Reference | 3834 +--------------------+----------+-----+-----------------------------+ 3835 | text/plain; | - | 0 | [RFC2046][RFC3676][RFC5147] | 3836 | charset=utf-8 | | | | 3837 | application/ | - | 40 | [RFC6690] | 3838 | link-format | | | | 3839 | application/xml | - | 41 | [RFC3023] | 3840 | application/ | - | 42 | [RFC2045][RFC2046] | 3841 | octet-stream | | | | 3842 | application/exi | - | 47 | [EXIMIME] | 3843 | application/json | - | 50 | [RFC4627] | 3844 +--------------------+----------+-----+-----------------------------+ 3846 Table 5: CoAP Content-Formats 3848 The identifiers between 201 and 255 inclusive are reserved for 3849 Private Use. All other identifiers are Unassigned. 3851 Because the name space of single-byte identifiers is so small, the 3852 IANA policy for future additions in the range 0-200 inclusive to the 3853 registry is "Expert Review" as described in [RFC5226]. The IANA 3854 policy for additions in the range 256-65535 inclusive is "First Come 3855 First Served" as described in [RFC5226]. 3857 In machine to machine applications, it is not expected that generic 3858 Internet media types such as text/plain, application/xml or 3859 application/octet-stream are useful for real applications in the long 3860 term. It is recommended that M2M applications making use of CoAP 3861 will request new Internet media types from IANA indicating semantic 3862 information about how to create or parse a payload. For example, a 3863 Smart Energy application payload carried as XML might request a more 3864 specific type like application/se+xml or application/se-exi. 3866 12.4. URI Scheme Registration 3868 This document requests the registration of the Uniform Resource 3869 Identifier (URI) scheme "coap". The registration request complies 3870 with [RFC4395]. 3872 URI scheme name. 3873 coap 3875 Status. 3876 Permanent. 3878 URI scheme syntax. 3879 Defined in Section 6.1 of [RFCXXXX]. 3881 URI scheme semantics. 3882 The "coap" URI scheme provides a way to identify resources that 3883 are potentially accessible over the Constrained Application 3884 Protocol (CoAP). The resources can be located by contacting the 3885 governing CoAP server and operated on by sending CoAP requests to 3886 the server. This scheme can thus be compared to the "http" URI 3887 scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of 3888 operation. 3890 Encoding considerations. 3891 The scheme encoding conforms to the encoding rules established for 3892 URIs in [RFC3986], i.e. internationalized and reserved characters 3893 are expressed using UTF-8-based percent-encoding. 3895 Applications/protocols that use this URI scheme name. 3896 The scheme is used by CoAP endpoints to access CoAP resources. 3898 Interoperability considerations. 3899 None. 3901 Security considerations. 3902 See Section 11.1 of [RFCXXXX]. 3904 Contact. 3905 IETF Chair 3907 Author/Change controller. 3908 IESG 3910 References. 3911 [RFCXXXX] 3913 12.5. Secure URI Scheme Registration 3915 This document requests the registration of the Uniform Resource 3916 Identifier (URI) scheme "coaps". The registration request complies 3917 with [RFC4395]. 3919 URI scheme name. 3920 coaps 3922 Status. 3923 Permanent. 3925 URI scheme syntax. 3926 Defined in Section 6.2 of [RFCXXXX]. 3928 URI scheme semantics. 3929 The "coaps" URI scheme provides a way to identify resources that 3930 are potentially accessible over the Constrained Application 3931 Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for 3932 transport security. The resources can be located by contacting 3933 the governing CoAP server and operated on by sending CoAP requests 3934 to the server. This scheme can thus be compared to the "https" 3935 URI scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details 3936 of operation. 3938 Encoding considerations. 3939 The scheme encoding conforms to the encoding rules established for 3940 URIs in [RFC3986], i.e. internationalized and reserved characters 3941 are expressed using UTF-8-based percent-encoding. 3943 Applications/protocols that use this URI scheme name. 3944 The scheme is used by CoAP endpoints to access CoAP resources 3945 using DTLS. 3947 Interoperability considerations. 3948 None. 3950 Security considerations. 3951 See Section 11.1 of [RFCXXXX]. 3953 Contact. 3954 IETF Chair 3956 Author/Change controller. 3957 IESG 3959 References. 3960 [RFCXXXX] 3962 12.6. Service Name and Port Number Registration 3964 One of the functions of CoAP is resource discovery: a CoAP client can 3965 ask a CoAP server about the resources offered by it (see Section 7). 3966 To enable resource discovery just based on the knowledge of an IP 3967 address, the CoAP port for resource discovery needs to be 3968 standardized. 3970 IANA has assigned the port number 5683 and the service name "coap", 3971 in accordance with [RFC6335]. 3973 Besides unicast, CoAP can be used with both multicast and anycast. 3975 Service Name. 3976 coap 3978 Transport Protocol. 3979 UDP 3981 Assignee. 3982 IESG 3984 Contact. 3985 IETF Chair 3987 Description. 3988 Constrained Application Protocol (CoAP) 3990 Reference. 3991 [RFCXXXX] 3993 Port Number. 3994 5683 3996 12.7. Secure Service Name and Port Number Registration 3998 CoAP resource discovery may also be provided using the DTLS-secured 3999 CoAP "coaps" scheme. Thus the CoAP port for secure resource 4000 discovery needs to be standardized. 4002 This document requests the assignment of the port number 4003 [IANA_TBD_PORT] and the service name "coaps", in accordance with 4004 [RFC6335]. 4006 Besides unicast, DTLS-secured CoAP can be used with anycast. 4008 Service Name. 4009 coaps 4011 Transport Protocol. 4012 UDP 4014 Assignee. 4015 IESG 4017 Contact. 4018 IETF Chair 4020 Description. 4021 DTLS-secured CoAP 4023 Reference. 4024 [RFCXXXX] 4026 Port Number. 4027 [IANA_TBD_PORT] 4029 12.8. Multicast Address Registration 4031 Section 8, "Multicast CoAP", defines the use of multicast. This 4032 document requests the assignment of the following multicast addresses 4033 for use by CoAP nodes: 4035 IPv4 -- "All CoAP Nodes" address [TBD1], from the IPv4 Multicast 4036 Address Space Registry. As the address is used for discovery that 4037 may span beyond a single network, it should come from the 4038 Internetwork Control Block (224.0.1.x, RFC 5771). 4040 IPv6 -- "All CoAP Nodes" address [TBD2], from the IPv6 Multicast 4041 Address Space Registry, in the Variable Scope Multicast Addresses 4042 space (RFC3307). Note that there is a distinct multicast address 4043 for each scope that interested CoAP nodes should listen to. 4045 [The explanatory text to be removed upon allocation of the addresses, 4046 except for the note about the distinct multicast addresses.] 4048 13. Acknowledgements 4050 Special thanks to Peter Bigot, Esko Dijk and Cullen Jennings for 4051 substantial contributions to the ideas and text in the document, 4052 along with countless detailed reviews and discussions. 4054 Thanks to Ed Beroset, Angelo P. Castellani, Gilbert Clark, Robert 4055 Cragie, Esko Dijk, Lisa Dussealt, Thomas Fossati, Tom Herbst, Richard 4056 Kelsey, Ari Keranen, Matthias Kovatsch, Salvatore Loreto, Kerry Lynn, 4057 Alexey Melnikov, Guido Moritz, Petri Mutka, Colin O'Flynn, Charles 4058 Palmer, Adriano Pezzuto, Robert Quattlebaum, Akbar Rahman, Eric 4059 Rescorla, David Ryan, Szymon Sasin, Michael Scharf, Dale Seed, Robby 4060 Simpson, Peter van der Stok, Michael Stuber, Linyi Tian, Gilman 4061 Tolle, Matthieu Vial and Alper Yegin for helpful comments and 4062 discussions that have shaped the document. 4064 Some of the text has been borrowed from the working documents of the 4065 IETF httpbis working group. 4067 14. References 4069 14.1. Normative References 4071 [I-D.farrell-decade-ni] 4072 Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 4073 Keranen, A., and P. Hallam-Baker, "Naming Things with 4074 Hashes", draft-farrell-decade-ni-10 (work in progress), 4075 August 2012. 4077 [I-D.ietf-tls-oob-pubkey] 4078 Wouters, P., Gilmore, J., Weiler, S., Kivinen, T., and H. 4079 Tschofenig, "Out-of-Band Public Key Validation for 4080 Transport Layer Security", draft-ietf-tls-oob-pubkey-04 4081 (work in progress), July 2012. 4083 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4084 Extensions (MIME) Part One: Format of Internet Message 4085 Bodies", RFC 2045, November 1996. 4087 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4088 Extensions (MIME) Part Two: Media Types", RFC 2046, 4089 November 1996. 4091 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4092 Requirement Levels", BCP 14, RFC 2119, March 1997. 4094 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 4095 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 4096 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 4098 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 4099 Types", RFC 3023, January 2001. 4101 [RFC3602] Frankel, S., Glenn, R., and S. Kelly, "The AES-CBC Cipher 4102 Algorithm and Its Use with IPsec", RFC 3602, 4103 September 2003. 4105 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 4106 10646", STD 63, RFC 3629, November 2003. 4108 [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", 4109 RFC 3676, February 2004. 4111 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4112 Resource Identifier (URI): Generic Syntax", STD 66, 4113 RFC 3986, January 2005. 4115 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 4116 for Transport Layer Security (TLS)", RFC 4279, 4117 December 2005. 4119 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 4120 RFC 4303, December 2005. 4122 [RFC4309] Housley, R., "Using Advanced Encryption Standard (AES) CCM 4123 Mode with IPsec Encapsulating Security Payload (ESP)", 4124 RFC 4309, December 2005. 4126 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 4127 Registration Procedures for New URI Schemes", BCP 35, 4128 RFC 4395, February 2006. 4130 [RFC4835] Manral, V., "Cryptographic Algorithm Implementation 4131 Requirements for Encapsulating Security Payload (ESP) and 4132 Authentication Header (AH)", RFC 4835, April 2007. 4134 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 4135 text/plain Media Type", RFC 5147, April 2008. 4137 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 4138 Interchange", RFC 5198, March 2008. 4140 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4141 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 4142 May 2008. 4144 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 4145 Specifications: ABNF", STD 68, RFC 5234, January 2008. 4147 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4148 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 4150 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4151 Housley, R., and W. Polk, "Internet X.509 Public Key 4152 Infrastructure Certificate and Certificate Revocation List 4153 (CRL) Profile", RFC 5280, May 2008. 4155 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4156 Uniform Resource Identifiers (URIs)", RFC 5785, 4157 April 2010. 4159 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 4160 Address Text Representation", RFC 5952, August 2010. 4162 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 4164 [RFC5996] Kaufman, C., Hoffman, P., Nir, Y., and P. Eronen, 4165 "Internet Key Exchange Protocol Version 2 (IKEv2)", 4166 RFC 5996, September 2010. 4168 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 4169 Extension Definitions", RFC 6066, January 2011. 4171 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4172 Security Version 1.2", RFC 6347, January 2012. 4174 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 4175 Format", RFC 6690, August 2012. 4177 14.2. Informative References 4179 [EUI64] "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) 4180 REGISTRATION AUTHORITY", April 2010, . 4183 [EXIMIME] "Efficient XML Interchange (EXI) Format 1.0", 4184 December 2009, . 4187 [I-D.allman-tcpm-rto-consider] 4188 Allman, M., "Retransmission Timeout Considerations", 4189 draft-allman-tcpm-rto-consider-01 (work in progress), 4190 May 2012. 4192 [I-D.ietf-core-block] 4193 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 4194 draft-ietf-core-block-09 (work in progress), August 2012. 4196 [I-D.ietf-core-observe] 4197 Hartke, K., "Observing Resources in CoAP", 4198 draft-ietf-core-observe-06 (work in progress), 4199 September 2012. 4201 [I-D.kivinen-ipsecme-ikev2-minimal] 4202 Kivinen, T., "Minimal IKEv2", 4203 draft-kivinen-ipsecme-ikev2-minimal-00 (work in progress), 4204 February 2011. 4206 [I-D.mcgrew-tls-aes-ccm-ecc] 4207 McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 4208 CCM ECC Cipher Suites for TLS", 4209 draft-mcgrew-tls-aes-ccm-ecc-05 (work in progress), 4210 July 2012. 4212 [REST] Fielding, R., "Architectural Styles and the Design of 4213 Network-based Software Architectures", Ph.D. Dissertation, 4214 University of California, Irvine, 2000, . 4218 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4219 RFC 793, September 1981. 4221 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 4223 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 4224 with Session Description Protocol (SDP)", RFC 3264, 4225 June 2002. 4227 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4228 "Advanced Sockets Application Program Interface (API) for 4229 IPv6", RFC 3542, May 2003. 4231 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 4232 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 4233 for Transport Layer Security (TLS)", RFC 4492, May 2006. 4235 [RFC4627] Crockford, D., "The application/json Media Type for 4236 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 4238 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 4239 "Transmission of IPv6 Packets over IEEE 802.15.4 4240 Networks", RFC 4944, September 2007. 4242 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 4243 for Application Designers", BCP 145, RFC 5405, 4244 November 2008. 4246 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 4247 Protocol (XMPP): Core", RFC 6120, March 2011. 4249 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 4250 Cheshire, "Internet Assigned Numbers Authority (IANA) 4251 Procedures for the Management of the Service Name and 4252 Transport Protocol Port Number Registry", BCP 165, 4253 RFC 6335, August 2011. 4255 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 4256 Transport Layer Security (TLS)", RFC 6655, July 2012. 4258 Appendix A. Examples 4260 This section gives a number of short examples with message flows for 4261 GET requests. These examples demonstrate the basic operation, the 4262 operation in the presence of retransmissions, and multicast. 4264 Figure 16 shows a basic GET request causing a piggy-backed response: 4265 The client sends a Confirmable GET request for the resource 4266 coap://server/temperature to the server with a Message ID of 0x7d34. 4267 The request includes one Uri-Path Option (Delta 0 + 11 = 11, Length 4268 11, Value "temperature"); the Token is left at its default value 4269 (empty). This request is a total of 16 bytes long. A 2.05 (Content) 4270 response is returned in the Acknowledgement message that acknowledges 4271 the Confirmable request, echoing both the Message ID 0x7d34 and the 4272 (implicitly empty) Token value. The response includes a Payload of 4273 "22.3 C" and is 10 bytes long. 4275 Client Server 4276 | | 4277 | | 4278 +----->| Header: GET (T=CON, Code=1, MID=0x7d34) 4279 | GET | Uri-Path: "temperature" 4280 | | 4281 | | 4282 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d34) 4283 | 2.05 | Payload: "22.3 C" 4284 | | 4286 0 1 2 3 4287 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 4288 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4289 | 1 | 0 | 1 | GET=1 | MID=0x7d34 | 4290 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4291 | 11 | 11 | "temperature" (11 B) ... 4292 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4294 0 1 2 3 4295 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 4296 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4297 | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | 4298 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4299 | "22.3 C" (6 B) ... 4300 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4302 Figure 16: Confirmable request; piggy-backed response 4304 Figure 17 shows a similar example, but with the inclusion of an 4305 explicit Token Option (Delta 11 + 8 = 19, Length 1, Value 0x20) in 4306 the request and (Jump 15 + 4 = 19) in the response, increasing the 4307 sizes to 18 and 12 bytes, respectively. 4309 Client Server 4310 | | 4311 | | 4312 +----->| Header: GET (T=CON, Code=1, MID=0x7d35) 4313 | GET | Token: 0x20 4314 | | Uri-Path: "temperature" 4315 | | 4316 | | 4317 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d35) 4318 | 2.05 | Token: 0x20 4319 | | Payload: "22.3 C" 4320 | | 4322 0 1 2 3 4323 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 4324 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4325 | 1 | 0 | 2 | GET=1 | MID=0x7d35 | 4326 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4327 | 11 | 11 | "temperature" (11 B) ... 4328 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4329 | 8 | 1 | 0x20 | 4330 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4332 0 1 2 3 4333 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 4334 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4335 | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | 4336 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4337 |Jump 15 = 0xf1 | 4 | 1 | 0x20 | "22.3 C" (6 B) ... 4338 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4340 Figure 17: Confirmable request; piggy-backed response 4342 In Figure 18, the Confirmable GET request is lost. After ACK_TIMEOUT 4343 seconds, the client retransmits the request, resulting in a piggy- 4344 backed response as in the previous example. 4346 Client Server 4347 | | 4348 | | 4349 +----X | Header: GET (T=CON, Code=1, MID=0x7d36) 4350 | GET | Token: 0x31 4351 | | Uri-Path: "temperature" 4352 TIMEOUT | 4353 | | 4354 +----->| Header: GET (T=CON, Code=1, MID=0x7d36) 4355 | GET | Token: 0x31 4356 | | Uri-Path: "temperature" 4357 | | 4358 | | 4359 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d36) 4360 | 2.05 | Token: 0x31 4361 | | Payload: "22.3 C" 4362 | | 4364 Figure 18: Confirmable request (retransmitted); piggy-backed response 4366 In Figure 19, the first Acknowledgement message from the server to 4367 the client is lost. After ACK_TIMEOUT seconds, the client 4368 retransmits the request. 4370 Client Server 4371 | | 4372 | | 4373 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 4374 | GET | Token: 0x42 4375 | | Uri-Path: "temperature" 4376 | | 4377 | | 4378 | X----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 4379 | 2.05 | Token: 0x42 4380 | | Payload: "22.3 C" 4381 TIMEOUT | 4382 | | 4383 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 4384 | GET | Token: 0x42 4385 | | Uri-Path: "temperature" 4386 | | 4387 | | 4388 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 4389 | 2.05 | Token: 0x42 4390 | | Payload: "22.3 C" 4391 | | 4393 Figure 19: Confirmable request; piggy-backed response (retransmitted) 4394 In Figure 20, the server acknowledges the Confirmable request and 4395 sends a 2.05 (Content) response separately in a Confirmable message. 4396 Note that the Acknowledgement message and the Confirmable response do 4397 not necessarily arrive in the same order as they were sent. The 4398 client acknowledges the Confirmable response. 4400 Client Server 4401 | | 4402 | | 4403 +----->| Header: GET (T=CON, Code=1, MID=0x7d38) 4404 | GET | Token: 0x53 4405 | | Uri-Path: "temperature" 4406 | | 4407 | | 4408 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d38) 4409 | | 4410 | | 4411 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7b) 4412 | 2.05 | Token: 0x53 4413 | | Payload: "22.3 C" 4414 | | 4415 | | 4416 +- - ->| Header: (T=ACK, Code=0, MID=0xad7b) 4417 | | 4419 Figure 20: Confirmable request; separate response 4421 Figure 21 shows an example where the client loses its state (e.g., 4422 crashes and is rebooted) right after sending a Confirmable request, 4423 so the separate response arriving some time later comes unexpected. 4424 In this case, the client rejects the Confirmable response with a 4425 Reset message. Note that the unexpected ACK is silently ignored. 4427 Client Server 4428 | | 4429 | | 4430 +----->| Header: GET (T=CON, Code=1, MID=0x7d39) 4431 | GET | Token: 0x64 4432 | | Uri-Path: "temperature" 4433 CRASH | 4434 | | 4435 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d39) 4436 | | 4437 | | 4438 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7c) 4439 | 2.05 | Token: 0x64 4440 | | Payload: "22.3 C" 4441 | | 4442 | | 4443 +- - ->| Header: (T=RST, Code=0, MID=0xad7c) 4444 | | 4446 Figure 21: Confirmable request; separate response (unexpected) 4448 Figure 22 shows a basic GET request where the request and the 4449 response are non-confirmable, so both may be lost without notice. 4451 Client Server 4452 | | 4453 | | 4454 +----->| Header: GET (T=NON, Code=1, MID=0x7d40) 4455 | GET | Token: 0x75 4456 | | Uri-Path: "temperature" 4457 | | 4458 | | 4459 |<-----+ Header: 2.05 Content (T=NON, Code=69, MID=0xad7d) 4460 | 2.05 | Token: 0x75 4461 | | Payload: "22.3 C" 4462 | | 4464 Figure 22: Non-confirmable request; Non-confirmable response 4466 In Figure 23, the client sends a Non-confirmable GET request to a 4467 multicast address: all nodes in link-local scope. There are 3 4468 servers on the link: A, B and C. Servers A and B have a matching 4469 resource, therefore they send back a Non-confirmable 2.05 (Content) 4470 response. The response sent by B is lost. C does not have matching 4471 response, therefore it sends a Non-confirmable 4.04 (Not Found) 4472 response. 4474 Client ff02::1 A B C 4475 | | | | | 4476 | | | | | 4477 +------>| | | | Header: GET (T=NON, Code=1, MID=0x7d41) 4478 | GET | | | | Token: 0x86 4479 | | | | Uri-Path: "temperature" 4480 | | | | 4481 | | | | 4482 |<------------+ | | Header: 2.05 (T=NON, Code=69, MID=0x60b1) 4483 | 2.05 | | | Token: 0x86 4484 | | | | Payload: "22.3 C" 4485 | | | | 4486 | | | | 4487 | X------------+ | Header: 2.05 (T=NON, Code=69, MID=0x01a0) 4488 | 2.05 | | | Token: 0x86 4489 | | | | Payload: "20.9 C" 4490 | | | | 4491 | | | | 4492 |<------------------+ Header: 4.04 (T=NON, Code=132, MID=0x952a) 4493 | 4.04 | | | Token: 0x86 4494 | | | | 4496 Figure 23: Non-confirmable request (multicast); Non-confirmable 4497 response 4499 Appendix B. URI Examples 4501 The following examples demonstrate different sets of Uri options, and 4502 the result after constructing an URI from them. 4504 o coap://[2001:db8::2:1]/ 4506 Destination IP Address = [2001:db8::2:1] 4508 Destination UDP Port = 5683 4510 o coap://example.net/ 4512 Destination IP Address = [2001:db8::2:1] 4514 Destination UDP Port = 5683 4516 Uri-Host = "example.net" 4518 o coap://example.net/.well-known/core 4519 Destination IP Address = [2001:db8::2:1] 4521 Destination UDP Port = 5683 4523 Uri-Host = "example.net" 4525 Uri-Path = ".well-known" 4527 Uri-Path = "core" 4529 o coap:// 4530 xn--18j4d.example/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF 4532 Destination IP Address = [2001:db8::2:1] 4534 Destination UDP Port = 5683 4536 Uri-Host = "xn--18j4d.example" 4538 Uri-Path = the string composed of the Unicode characters U+3053 4539 U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as 4540 E38193E38293E381ABE381A1E381AF hexadecimal 4542 o coap://198.51.100.1:61616//%2F//?%2F%2F&?%26 4544 Destination IP Address = 198.51.100.1 4546 Destination UDP Port = 61616 4548 Uri-Path = "" 4550 Uri-Path = "/" 4552 Uri-Path = "" 4554 Uri-Path = "" 4556 Uri-Query = "//" 4558 Uri-Query = "?&" 4560 Appendix C. Changelog 4562 Changed from ietf-11 to ietf-12: 4564 o Extended options to support lengths of up to 1034 bytes (#202). 4566 o Added new Jump mechanism for options and removed Fenceposting 4567 (#214). 4569 o Added new IANA option number registration policy (#214). 4571 o Added Proxy Unsafe/Safe and Cache-Key masking to option numbers 4572 (#241). 4574 o Re-numbered option numbers to use Unsafe/Safe and Cache-Key 4575 compliant numbers (#241). 4577 o Defined NSTART and restricted the value to 1 with a MUST (#215). 4579 o Defined PROBING_RATE and set it to 1 Byte/second (#215). 4581 o Defined DEFAULT_LEISURE (#246). 4583 o Renamed Content-Type into Content-Format, and Media Type registry 4584 into Content-Format registry. 4586 o A large number of small editorial changes, clarifications and 4587 improvements have been made. 4589 Changed from ietf-10 to ietf-11: 4591 o Expanded section 4.8 on Transmission Parameters, and used the 4592 derived values defined there (#201). Changed parameter names to 4593 be shorter and more to the point. 4595 o Several more small editorial changes, clarifications and 4596 improvements have been made. 4598 Changed from ietf-09 to ietf-10: 4600 o Option deltas are restricted to 0 to 14; the option delta 15 is 4601 used exclusively for the end-of-options marker (#239). 4603 o Option numbers that are a multiple of 14 are not reserved, but are 4604 required to have an empty default value (#212). 4606 o Fixed misleading language that was introduced in 5.10.2 in coap-07 4607 re Uri-Host and Uri-Port (#208). 4609 o Segments and arguments can have a length of zero characters 4610 (#213). 4612 o The Location-* options describe together describe one location. 4613 The location is a relative URI, not an "absolute path URI" (#218). 4615 o The value of the Location-Path Option must not be '.' or '..' 4616 (#218). 4618 o Added a sentence on constructing URIs from Location-* options 4619 (#231). 4621 o Reserved option numbers for future Location-* options (#230). 4623 o Fixed response codes with payload inconsistency (#233). 4625 o Added advice on default values for critical options (#207). 4627 o Clarified use of identifiers in RawPublicKey Mode Provisioning 4628 (#222). 4630 o Moved "Securing CoAP" out of the "Security Considerations" (#229). 4632 o Added "All CoAP Nodes" multicast addresses to "IANA 4633 Considerations" (#216). 4635 o Over 100 small editorial changes, clarifications and improvements 4636 have been made. 4638 Changed from ietf-08 to ietf-09: 4640 o Improved consistency of statements about RST on NON: RST is a 4641 valid response to a NON message (#183). 4643 o Clarified that the protocol constants can be configured for 4644 specific application environments. 4646 o Added implementation note recommending piggy-backing whenever 4647 possible (#182). 4649 o Added a content-encoding column to the media type registry (#181). 4651 o Minor improvements to Appendix D. 4653 o Added text about multicast response suppression (#177). 4655 o Included the new End-of-options Marker (#176). 4657 o Added a reference to draft-ietf-tls-oob-pubkey and updated the RPK 4658 text accordingly. 4660 Changed from ietf-07 to ietf-08: 4662 o Clarified matching rules for messages (#175) 4664 o Fixed a bug in Section 8.2.2 on Etags (#168) 4666 o Added an IP address spoofing threat analysis contribution (#167) 4668 o Re-focused the security section on raw public keys (#166) 4670 o Added an 4.06 error to Accept (#165) 4672 Changed from ietf-06 to ietf-07: 4674 o application/link-format added to Media types registration (#160) 4676 o Moved content-type attribute to the document from link-format. 4678 o Added coaps scheme and DTLS-secured CoAP default port (#154) 4680 o Allowed 0-length Content-type options (#150) 4682 o Added congestion control recommendations (#153) 4684 o Improved text on PUT/POST response payloads (#149) 4686 o Added an Accept option for content-negotiation (#163) 4688 o Added If-Match and If-None-Match options (#155) 4690 o Improved Token Option explanation (#147) 4692 o Clarified mandatory to implement security (#156) 4694 o Added first come first server policy for 2-byte Media type codes 4695 (#161) 4697 o Clarify matching rules for messages and tokens (#151) 4699 o Changed OPTIONS and TRACE to always return 501 in HTTP-CoAP 4700 mapping (#164) 4702 Changed from ietf-05 to ietf-06: 4704 o HTTP mapping section improved with the minimal protocol standard 4705 text for CoAP-HTTP and HTTP-CoAP forward proxying (#137). 4707 o Eradicated percent-encoding by including one Uri-Query Option per 4708 &-delimited argument in a query. 4710 o Allowed RST message in reply to a NON message with unexpected 4711 token (#135). 4713 o Cache Invalidation only happens upon successful responses (#134). 4715 o 50% jitter added to the initial retransmit timer (#142). 4717 o DTLS cipher suites aligned with ZigBee IP, DTLS clarified as 4718 default CoAP security mechanism (#138, #139) 4720 o Added a minimal reference to draft-kivinen-ipsecme-ikev2-minimal 4721 (#140). 4723 o Clarified the comparison of UTF-8s (#136). 4725 o Minimized the initial media type registry (#101). 4727 Changed from ietf-04 to ietf-05: 4729 o Renamed Immediate into Piggy-backed and Deferred into Separate -- 4730 should finally end the confusion on what this is about. 4732 o GET requests now return a 2.05 (Content) response instead of 2.00 4733 (OK) response (#104). 4735 o Added text to allow 2.02 (Deleted) responses in reply to POST 4736 requests (#105). 4738 o Improved message deduplication rules (#106). 4740 o Section added on message size implementation considerations 4741 (#103). 4743 o Clarification made on human readable error payloads (#109). 4745 o Definition of CoAP methods improved (#108). 4747 o Max-Age removed from requests (#107). 4749 o Clarified uniqueness of tokens (#112). 4751 o Location-Query Option added (#113). 4753 o ETag length set to 1-8 bytes (#123). 4755 o Clarified relation between elective/critical and option numbers 4756 (#110). 4758 o Defined when to update Version header field (#111). 4760 o URI scheme registration improved (#102). 4762 o Added review guidelines for new CoAP codes and numbers. 4764 Changes from ietf-03 to ietf-04: 4766 o Major document reorganization (#51, #63, #71, #81). 4768 o Max-age length set to 0-4 bytes (#30). 4770 o Added variable unsigned integer definition (#31). 4772 o Clarification made on human readable error payloads (#50). 4774 o Definition of POST improved (#52). 4776 o Token length changed to 0-8 bytes (#53). 4778 o Section added on multiplexing CoAP, DTLS and STUN (#56). 4780 o Added cross-protocol attack considerations (#61). 4782 o Used new Immediate/Deferred response definitions (#73). 4784 o Improved request/response matching rules (#74). 4786 o Removed unnecessary media types and added recommendations for 4787 their use in M2M (#76). 4789 o Response codes changed to base 32 coding, new Y.XX naming (#77). 4791 o References updated as per AD review (#79). 4793 o IANA section completed (#80). 4795 o Proxy-Uri Option added to disambiguate between proxy and non-proxy 4796 requests (#82). 4798 o Added text on critical options in cached states (#83). 4800 o HTTP mapping sections improved (#88). 4802 o Added text on reverse proxies (#72). 4804 o Some security text on multicast added (#54). 4806 o Trust model text added to introduction (#58, #60). 4808 o AES-CCM vs. AES-CCB text added (#55). 4810 o Text added about device capabilities (#59). 4812 o DTLS section improvements (#87). 4814 o Caching semantics aligned with RFC2616 (#78). 4816 o Uri-Path Option split into multiple path segments. 4818 o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. 4820 Changes from ietf-02 to ietf-03: 4822 o Token Option and related use in asynchronous requests added (#25). 4824 o CoAP specific error codes added (#26). 4826 o Erroring out on unknown critical options changed to a MUST (#27). 4828 o Uri-Query Option added. 4830 o Terminology and definitions of URIs improved. 4832 o Security section completed (#22). 4834 Changes from ietf-01 to ietf-02: 4836 o Sending an error on a critical option clarified (#18). 4838 o Clarification on behavior of PUT and idempotent operations (#19). 4840 o Use of Uri-Authority clarified along with server processing rules; 4841 Uri-Scheme Option removed (#20, #23). 4843 o Resource discovery section removed to a separate CoRE Link Format 4844 draft (#21). 4846 o Initial security section outline added. 4848 Changes from ietf-00 to ietf-01: 4850 o New cleaner transaction message model and header (#5). 4852 o Removed subscription while being designed (#1). 4854 o Section 2 re-written (#3). 4856 o Text added about use of short URIs (#4). 4858 o Improved header option scheme (#5, #14). 4860 o Date option removed whiled being designed (#6). 4862 o New text for CoAP default port (#7). 4864 o Completed proxying section (#8). 4866 o Completed resource discovery section (#9). 4868 o Completed HTTP mapping section (#10). 4870 o Several new examples added (#11). 4872 o URI split into 3 options (#12). 4874 o MIME type defined for link-format (#13, #16). 4876 o New text on maximum message size (#15). 4878 o Location Option added. 4880 Changes from shelby-01 to ietf-00: 4882 o Removed the TCP binding section, left open for the future. 4884 o Fixed a bug in the example. 4886 o Marked current Sub/Notify as (Experimental) while under WG 4887 discussion. 4889 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 4890 CoAP-CoAP proxying to work). 4892 o Temporarily removed the Magic Byte header as TCP is no longer 4893 included as a binding. 4895 o Removed the Uri-code Option as different URI encoding schemes are 4896 being discussed. 4898 o Changed the rel= field to desc= for resource discovery. 4900 o Changed the maximum message size to 1024 bytes to allow for IP/UDP 4901 headers. 4903 o Made the URI slash optimization and method idempotence MUSTs 4905 o Minor editing and bug fixing. 4907 Changes from shelby-00 to shelby-01: 4909 o Unified the message header and added a notify message type. 4911 o Renamed methods with HTTP names and removed the NOTIFY method. 4913 o Added a number of options field to the header. 4915 o Combines the Option Type and Length into an 8-bit field. 4917 o Added the magic byte header. 4919 o Added new ETag Option. 4921 o Added new Date Option. 4923 o Added new Subscription Option. 4925 o Completed the HTTP Code - CoAP Code mapping table appendix. 4927 o Completed the Content-type Identifier appendix and tables. 4929 o Added more simplifications for URI support. 4931 o Initial subscription and discovery sections. 4933 o A Flag requirements simplified. 4935 Authors' Addresses 4937 Zach Shelby 4938 Sensinode 4939 Kidekuja 2 4940 Vuokatti 88600 4941 Finland 4943 Phone: +358407796297 4944 Email: zach@sensinode.com 4945 Klaus Hartke 4946 Universitaet Bremen TZI 4947 Postfach 330440 4948 Bremen D-28359 4949 Germany 4951 Phone: +49-421-218-63905 4952 Email: hartke@tzi.org 4954 Carsten Bormann 4955 Universitaet Bremen TZI 4956 Postfach 330440 4957 Bremen D-28359 4958 Germany 4960 Phone: +49-421-218-63921 4961 Email: cabo@tzi.org 4963 Brian Frank 4964 SkyFoundry 4965 Richmond, VA 4966 USA 4968 Phone: 4969 Email: brian@skyfoundry.com