idnits 2.17.1 draft-ietf-core-coap-13.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 4500 has weird spacing: '... Client ff02:...' -- The document date (December 6, 2012) is 4159 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 486, but not defined == Missing Reference: '0x01a0' is mentioned on line 501, but not defined == Missing Reference: '0xbc90' is mentioned on line 543, but not defined == Missing Reference: '0xbc91' is mentioned on line 543, but not defined == Missing Reference: '0x7a10' is mentioned on line 567, but not defined == Missing Reference: '0x23bb' is mentioned on line 578, but not defined == Missing Reference: '0x7a11' is mentioned on line 591, but not defined == Missing Reference: '0x23bc' is mentioned on line 596, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 4050, but not defined == Missing Reference: 'TBD1' is mentioned on line 4061, but not defined == Missing Reference: 'TBD2' is mentioned on line 4066, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-tls-oob-pubkey-06 ** 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 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 6347 (Obsoleted by RFC 9147) == Outdated reference: A later version (-03) exists of draft-allman-tcpm-rto-consider-01 == Outdated reference: A later version (-27) exists of draft-bormann-coap-misc-21 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-10 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-07 == 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: 8 errors (**), 0 flaws (~~), 19 warnings (==), 7 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: June 9, 2013 C. Bormann 6 Universitaet Bremen TZI 7 B. Frank 8 SkyFoundry 9 December 6, 2012 11 Constrained Application Protocol (CoAP) 12 draft-ietf-core-coap-13 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 June 9, 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 . . . . . . . . . . . . . . . . . . . . . . . 16 76 3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 17 77 3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 19 78 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 20 79 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20 80 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 21 81 4.3. Messages Transmitted Without Reliability . . . . . . . . 22 82 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 22 83 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 23 84 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 24 85 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 25 86 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 26 87 4.8.1. Changing The Parameters . . . . . . . . . . . . . . . 26 88 4.8.2. Time Values derived from Transmission Parameters . . 27 89 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 29 90 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 29 91 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 29 92 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 30 93 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 31 94 5.2.3. Non-Confirmable . . . . . . . . . . . . . . . . . . . 32 95 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 32 96 5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 32 97 5.3.2. Request/Response Matching Rules . . . . . . . . . . . 33 98 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 33 99 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 34 100 5.4.2. Proxy Unsafe/Safe and Cache-Key . . . . . . . . . . . 35 101 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 35 102 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 36 103 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 36 104 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 36 105 5.5. Payloads and Representations . . . . . . . . . . . . . . 37 106 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 37 107 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 38 108 5.5.3. Selected Representation . . . . . . . . . . . . . . . 38 109 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 38 110 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 39 111 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 39 112 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 40 113 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 40 114 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 41 115 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 42 116 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 43 117 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 43 118 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 43 119 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 44 120 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 44 121 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 44 122 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 45 123 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 45 124 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 46 125 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 47 126 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 48 127 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 49 128 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 50 129 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 51 130 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 51 131 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . . 51 132 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 52 133 5.10.7. Location-Path and Location-Query . . . . . . . . . . 53 134 5.10.8. Conditional Request Options . . . . . . . . . . . . . 53 135 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 55 136 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 55 137 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 56 138 6.3. Normalization and Comparison Rules . . . . . . . . . . . 56 139 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 57 140 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 58 141 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 59 142 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 59 143 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 60 144 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 60 146 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 61 147 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 61 148 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 61 149 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 62 150 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 63 151 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 63 152 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 64 153 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 65 154 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 66 155 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 66 156 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 68 157 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 69 158 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 69 159 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 70 160 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 70 161 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 70 162 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 71 163 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . . 71 164 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . . 71 165 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 72 166 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 72 167 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 73 168 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 73 169 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 73 170 11. Security Considerations . . . . . . . . . . . . . . . . . . . 73 171 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . . 73 172 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 74 173 11.3. Risk of amplification . . . . . . . . . . . . . . . . . . 75 174 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . . 76 175 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 76 176 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 177 12.1. CoAP Code Registry . . . . . . . . . . . . . . . . . . . 78 178 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 79 179 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 80 180 12.2. Option Number Registry . . . . . . . . . . . . . . . . . 81 181 12.3. Content-Format Registry . . . . . . . . . . . . . . . . . 83 182 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 84 183 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 85 184 12.6. Service Name and Port Number Registration . . . . . . . . 86 185 12.7. Secure Service Name and Port Number Registration . . . . 87 186 12.8. Multicast Address Registration . . . . . . . . . . . . . 88 187 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 88 188 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 89 189 14.1. Normative References . . . . . . . . . . . . . . . . . . 89 190 14.2. Informative References . . . . . . . . . . . . . . . . . 91 191 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 93 192 Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 98 193 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 99 194 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 108 196 1. Introduction 198 The use of web services on the Internet has become ubiquitous in most 199 applications, and depends on the fundamental Representational State 200 Transfer [REST] architecture of the web. 202 The Constrained RESTful Environments (CoRE) work aims at realizing 203 the REST architecture in a suitable form for the most constrained 204 nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and 205 networks (e.g. 6LoWPAN, [RFC4944]). Constrained networks like 206 6LoWPAN support the expensive fragmentation of IPv6 packets into 207 small link-layer frames. One design goal of CoAP has been to keep 208 message overhead small, thus limiting the use of fragmentation. 210 One of the main goals of CoAP is to design a generic web protocol for 211 the special requirements of this constrained environment, especially 212 considering energy, building automation and other machine-to-machine 213 (M2M) applications. The goal of CoAP is not to blindly compress HTTP 214 [RFC2616], but rather to realize a subset of REST common with HTTP 215 but optimized for M2M applications. Although CoAP could be used for 216 compressing simple HTTP interfaces, it more importantly also offers 217 features for M2M such as built-in discovery, multicast support and 218 asynchronous message exchanges. 220 This document specifies the Constrained Application Protocol (CoAP), 221 which easily translates to HTTP for integration with the existing web 222 while meeting specialized requirements such as multicast support, 223 very low overhead and simplicity for constrained environments and M2M 224 applications. 226 1.1. Features 228 CoAP has the following main features: 230 o Constrained web protocol fulfilling M2M requirements. 232 o UDP binding with optional reliability supporting unicast and 233 multicast requests. 235 o Asynchronous message exchanges. 237 o Low header overhead and parsing complexity. 239 o URI and Content-type support. 241 o Simple proxy and caching capabilities. 243 o A stateless HTTP mapping, allowing proxies to be built providing 244 access to CoAP resources via HTTP in a uniform way or for HTTP 245 simple interfaces to be realized alternatively over CoAP. 247 o Security binding to Datagram Transport Layer Security (DTLS). 249 1.2. Terminology 251 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 252 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 253 "OPTIONAL" in this document are to be interpreted as described in 254 [RFC2119] when they appear in ALL CAPS. These words may also appear 255 in this document in lower case as plain English words, absent their 256 normative meanings. 258 This specification requires readers to be familiar with all the terms 259 and concepts that are discussed in [RFC2616]. In addition, this 260 specification defines the following terminology: 262 Endpoint 263 An entity participating in the CoAP protocol. Colloquially, an 264 endpoint lives on a "Node", although "Host" would be more 265 consistent with Internet standards usage, and is further 266 identified by transport layer multiplexing information that can 267 include a UDP port number and a security association 268 (Section 4.1). 270 Sender 271 The originating endpoint of a message. When the aspect of 272 identification of the specific sender is in focus, also "source 273 endpoint". 275 Recipient 276 The destination endpoint of a message. When the aspect of 277 identification of the specific recipient is in focus, also 278 "destination endpoint". 280 Client 281 The originating endpoint of a request; the destination endpoint of 282 a response. 284 Server 285 The destination endpoint of a request; the originating endpoint of 286 a response. 288 Origin Server 289 The server on which a given resource resides or is to be created. 291 Intermediary 292 A CoAP endpoint that acts both as a server and as a client towards 293 (possibly via further intermediaries) an origin server. A common 294 form of an intermediary is a proxy; several classes of such 295 proxies are discussed in this specification. 297 Proxy 298 An intermediary that mainly is concerned with forwarding requests 299 and relaying back responses, possibly performing caching, 300 namespace translation, or protocol translation in the process. As 301 opposed to intermediaries in the general sense, proxies generally 302 do not implement specific application semantics. Based on the 303 position in the overall structure of the request forwarding, there 304 are two common forms of proxy: forward-proxy and reverse-proxy. 305 In some cases, a single endpoint might act as an origin server, 306 forward-proxy, or reverse-proxy, switching behavior based on the 307 nature of each request. 309 Forward-Proxy 310 A "forward-proxy" is an endpoint selected by a client, usually via 311 local configuration rules, to perform requests on behalf of the 312 client, doing any necessary translations. Some translations are 313 minimal, such as for proxy requests for "coap" URIs, whereas other 314 requests might require translation to and from entirely different 315 application-layer protocols. 317 Reverse-Proxy 318 A "reverse-proxy" is an endpoint that stands in for one or more 319 other server(s) and satisfies requests on behalf of these, doing 320 any necessary translations. Unlike a forward-proxy, the client 321 may not be aware that it is communicating with a reverse-proxy; a 322 reverse-proxy receives requests as if it was the origin server for 323 the target resource. 325 Cross-Proxy 326 A cross-protocol proxy, or "cross-proxy" for short, is a proxy 327 that translates between different protocols, such as a CoAP-to- 328 HTTP proxy or an HTTP-to-CoAP proxy. While this specification 329 makes very specific demands of CoAP-to-CoAP proxies, there is more 330 variation possible in cross-proxies. 332 Confirmable Message 333 Some messages require an acknowledgement. These messages are 334 called "Confirmable". When no packets are lost, each confirmable 335 message elicits exactly one return message of type Acknowledgement 336 or type Reset. 338 Non-Confirmable Message 339 Some other messages do not require an acknowledgement. This is 340 particularly true for messages that are repeated regularly for 341 application requirements, such as repeated readings from a sensor 342 where eventual success is sufficient. 344 Acknowledgement Message 345 An Acknowledgement message acknowledges that a specific 346 Confirmable Message arrived. It does not indicate success or 347 failure of any encapsulated request. 349 Reset Message 350 A Reset message indicates that a specific message (confirmable or 351 non-confirmable) was received, but some context is missing to 352 properly process it. This condition is usually caused when the 353 receiving node has rebooted and has forgotten some state that 354 would be required to interpret the message. Provoking a Reset 355 message (e.g., by sending an empty Confirmable message) is also 356 useful as an inexpensive check of the liveness of an endpoint 357 ("CoAP ping"). 359 Piggy-backed Response 360 A Piggy-backed Response is included right in a CoAP 361 Acknowledgement (ACK) message that is sent to acknowledge receipt 362 of the Request for this Response (Section 5.2.1). 364 Separate Response 365 When a Confirmable message carrying a Request is acknowledged with 366 an empty message (e.g., because the server doesn't have the answer 367 right away), a Separate Response is sent in a separate message 368 exchange (Section 5.2.2). 370 Critical Option 371 An option that would need to be understood by the endpoint 372 receiving the message in order to properly process the message 373 (Section 5.4.1). Note that the implementation of critical options 374 is, as the name "Option" implies, generally optional: unsupported 375 critical options lead to an error response or summary rejection of 376 the message. 378 Elective Option 379 An option that is intended to be ignored by an endpoint that does 380 not understand it. Processing the message even without 381 understanding the option is acceptable (Section 5.4.1). 383 Unsafe Option 384 An option that would need to be understood by a proxy receiving 385 the message in order to safely forward the message 386 (Section 5.4.2). 388 Safe Option 389 An option that is intended to be safe for forwarding by a proxy 390 that does not understand it. Forwarding the message even without 391 understanding the option is acceptable (Section 5.4.2). 393 Resource Discovery 394 The process where a CoAP client queries a server for its list of 395 hosted resources (i.e., links, Section 7). 397 Content-Format 398 The combination of an Internet media type, potentially with 399 specific parameters given, and a content-coding (which is often 400 the identity content-coding), identified by a numeric identifier 401 defined by the CoAP Content-Format registry. When the focus is 402 less on the numeric identifier than on the combination of these 403 characteristics of a resource representation, this is also called 404 "representation format". 406 In this specification, the term "byte" is used in its now customary 407 sense as a synonym for "octet". 409 All multi-byte integers in this protocol are interpreted in network 410 byte order. 412 Where arithmetic is used, this specification uses the notation 413 familiar from the programming language C, except that the operator 414 "**" stands for exponentiation. 416 2. Constrained Application Protocol 418 The interaction model of CoAP is similar to the client/server model 419 of HTTP. However, machine-to-machine interactions typically result 420 in a CoAP implementation acting in both client and server roles. A 421 CoAP request is equivalent to that of HTTP, and is sent by a client 422 to request an action (using a method code) on a resource (identified 423 by a URI) on a server. The server then sends a response with a 424 response code; this response may include a resource representation. 426 Unlike HTTP, CoAP deals with these interchanges asynchronously over a 427 datagram-oriented transport such as UDP. This is done logically 428 using a layer of messages that supports optional reliability (with 429 exponential back-off). CoAP defines four types of messages: 431 Confirmable, Non-Confirmable, Acknowledgement, Reset; method codes 432 and response codes included in some of these messages make them carry 433 requests or responses. The basic exchanges of the four types of 434 messages are somewhat orthogonal to the request/response 435 interactions; requests can be carried in Confirmable and Non- 436 Confirmable messages, and responses can be carried in these as well 437 as piggy-backed in Acknowledgement messages. 439 One could think of CoAP logically as using a two-layer approach, a 440 CoAP messaging layer used to deal with UDP and the asynchronous 441 nature of the interactions, and the request/response interactions 442 using Method and Response codes (see Figure 1). CoAP is however a 443 single protocol, with messaging and request/response just features of 444 the CoAP header. 446 +----------------------+ 447 | Application | 448 +----------------------+ 449 +----------------------+ \ 450 | Requests/Responses | | 451 |----------------------| | CoAP 452 | Messages | | 453 +----------------------+ / 454 +----------------------+ 455 | UDP | 456 +----------------------+ 458 Figure 1: Abstract layering of CoAP 460 2.1. Messaging Model 462 The CoAP messaging model is based on the exchange of messages over 463 UDP between endpoints. 465 CoAP uses a short fixed-length binary header (4 bytes) that may be 466 followed by compact binary options and a payload. This message 467 format is shared by requests and responses. The CoAP message format 468 is specified in Section 3. Each message contains a Message ID used 469 to detect duplicates and for optional reliability. 471 Reliability is provided by marking a message as Confirmable (CON). A 472 Confirmable message is retransmitted using a default timeout and 473 exponential back-off between retransmissions, until the recipient 474 sends an Acknowledgement message (ACK) with the same Message ID (for 475 example, 0x7d34) from the corresponding endpoint; see Figure 2. When 476 a recipient is not at all able to process a Confirmable message 477 (i.e., not even able to provide a suitable error response), it 478 replies with a Reset message (RST) instead of an Acknowledgement 479 (ACK). 481 Client Server 482 | | 483 | CON [0x7d34] | 484 +----------------->| 485 | | 486 | ACK [0x7d34] | 487 |<-----------------+ 488 | | 490 Figure 2: Reliable message transmission 492 A message that does not require reliable transmission, for example 493 each single measurement out of a stream of sensor data, can be sent 494 as a Non-confirmable message (NON). These are not acknowledged, but 495 still have a Message ID for duplicate detection; see Figure 3. When 496 a recipient is not able to process a Non-confirmable message, it may 497 reply with a Reset message (RST). 499 Client Server 500 | | 501 | NON [0x01a0] | 502 +----------------->| 503 | | 505 Figure 3: Unreliable message transmission 507 See Section 4 for details of CoAP messages. 509 As CoAP is based on UDP, it also supports the use of multicast IP 510 destination addresses, enabling multicast CoAP requests. Section 8 511 discusses the proper use of CoAP messages with multicast addresses 512 and precautions for avoiding response congestion. 514 Several security modes are defined for CoAP in Section 9 ranging from 515 no security to certificate-based security. This document specifies a 516 binding to DTLS for securing the protocol; the use of IPsec with CoAP 517 is discussed in [I-D.bormann-core-ipsec-for-coap]. 519 2.2. Request/Response Model 521 CoAP request and response semantics are carried in CoAP messages, 522 which include either a Method code or Response code, respectively. 523 Optional (or default) request and response information, such as the 524 URI and payload media type are carried as CoAP options. A Token is 525 used to match responses to requests independently from the underlying 526 messages (Section 5.3). 528 A request is carried in a Confirmable (CON) or Non-confirmable (NON) 529 message, and if immediately available, the response to a request 530 carried in a Confirmable message is carried in the resulting 531 Acknowledgement (ACK) message. This is called a piggy-backed 532 response, detailed in Section 5.2.1. Two examples for a basic GET 533 request with piggy-backed response are shown in Figure 4, one 534 successful, one resulting in a 4.04 (Not Found) response. 536 Client Server Client Server 537 | | | | 538 | CON [0xbc90] | | CON [0xbc91] | 539 | GET /temperature | | GET /temperature | 540 | (Token 0x71) | | (Token 0x72) | 541 +----------------->| +----------------->| 542 | | | | 543 | ACK [0xbc90] | | ACK [0xbc91] | 544 | 2.05 Content | | 4.04 Not Found | 545 | (Token 0x71) | | (Token 0x72) | 546 | "22.5 C" | | "Not found" | 547 |<-----------------+ |<-----------------+ 548 | | | | 550 Figure 4: Two GET requests with piggy-backed responses 552 If the server is not able to respond immediately to a request carried 553 in a Confirmable message, it simply responds with an empty 554 Acknowledgement message so that the client can stop retransmitting 555 the request. When the response is ready, the server sends it in a 556 new Confirmable message (which then in turn needs to be acknowledged 557 by the client). This is called a separate response, as illustrated 558 in Figure 5 and described in more detail in Section 5.2.2. 560 Client Server 561 | | 562 | CON [0x7a10] | 563 | GET /temperature | 564 | (Token 0x73) | 565 +----------------->| 566 | | 567 | ACK [0x7a10] | 568 |<-----------------+ 569 | | 570 ... Time Passes ... 571 | | 572 | CON [0x23bb] | 573 | 2.05 Content | 574 | (Token 0x73) | 575 | "22.5 C" | 576 |<-----------------+ 577 | | 578 | ACK [0x23bb] | 579 +----------------->| 580 | | 582 Figure 5: A GET request with a separate response 584 Likewise, if a request is sent in a Non-Confirmable message, then the 585 response is usually sent using a new Non-Confirmable message, 586 although the server may send a Confirmable message. This type of 587 exchange is illustrated in Figure 6. 589 Client Server 590 | | 591 | NON [0x7a11] | 592 | GET /temperature | 593 | (Token 0x74) | 594 +----------------->| 595 | | 596 | NON [0x23bc] | 597 | 2.05 Content | 598 | (Token 0x74) | 599 | "22.5 C" | 600 |<-----------------+ 601 | | 603 Figure 6: A NON request and response 605 CoAP makes use of GET, PUT, POST and DELETE methods in a similar 606 manner to HTTP, with the semantics specified in Section 5.8. (Note 607 that the detailed semantics of CoAP methods are "almost, but not 608 entirely unlike" those of HTTP methods: Intuition taken from HTTP 609 experience generally does apply well, but there are enough 610 differences that make it worthwhile to actually read the present 611 specification.) 613 URI support in a server is simplified as the client already parses 614 the URI and splits it into host, port, path and query components, 615 making use of default values for efficiency. Response codes 616 correspond to a small subset of HTTP response codes with a few CoAP 617 specific codes added, as defined in Section 5.9. 619 2.3. Intermediaries and Caching 621 The protocol supports the caching of responses in order to 622 efficiently fulfill requests. Simple caching is enabled using 623 freshness and validity information carried with CoAP responses. A 624 cache could be located in an endpoint or an intermediary. Caching 625 functionality is specified in Section 5.6. 627 Proxying is useful in constrained networks for several reasons, 628 including network traffic limiting, to improve performance, to access 629 resources of sleeping devices or for security reasons. The proxying 630 of requests on behalf of another CoAP endpoint is supported in the 631 protocol. When using a proxy, the URI of the resource to request is 632 included in the request, while the destination IP address is set to 633 the address of the proxy. See Section 5.7 for more information on 634 proxy functionality. 636 As CoAP was designed according to the REST architecture and thus 637 exhibits functionality similar to that of the HTTP protocol, it is 638 quite straightforward to map from CoAP to HTTP and from HTTP to CoAP. 639 Such a mapping may be used to realize an HTTP REST interface using 640 CoAP, or for converting between HTTP and CoAP. This conversion can 641 be carried out by a cross-protocol proxy ("cross-proxy"), which 642 converts the method or response code, media type, and options to the 643 corresponding HTTP feature. Section 10 provides more detail about 644 HTTP mapping. 646 2.4. Resource Discovery 648 Resource discovery is important for machine-to-machine interactions, 649 and is supported using the CoRE Link Format [RFC6690] as discussed in 650 Section 7. 652 3. Message Format 654 CoAP is based on the exchange of short messages which, by default, 655 are transported over UDP (i.e. each CoAP message occupies the data 656 section of one UDP datagram). CoAP may also be used over Datagram 657 Transport Layer Security (DTLS) (see Section 9.1). It could also be 658 used over other transports such as SMS, TCP or SCTP, the 659 specification of which is out of this document's scope. 661 CoAP messages are encoded in a simple binary format. The message 662 format starts with a fixed-size 4-byte header. This is followed by a 663 variable-length Token value which can be between 0 and 8 bytes long. 664 Following the Token value comes a sequence of zero or more CoAP 665 Options in Type-Length-Value (TLV) format, optionally followed by a 666 payload which takes up the rest of the datagram. 668 0 1 2 3 669 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 670 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 671 |Ver| T | TKL | Code | Message ID | 672 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 673 | Token (if any, TKL bytes) ... 674 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 675 | Options (if any) ... 676 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 677 |1 1 1 1 1 1 1 1| Payload (if any) ... 678 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 680 Figure 7: Message Format 682 The fields in the header are defined as follows: 684 Version (Ver): 2-bit unsigned integer. Indicates the CoAP version 685 number. Implementations of this specification MUST set this field 686 to 1. Other values are reserved for future versions. 688 Type (T): 2-bit unsigned integer. Indicates if this message is of 689 type Confirmable (0), Non-Confirmable (1), Acknowledgement (2) or 690 Reset (3). The semantics of these message types are defined in 691 Section 4. 693 Token Length (TKL): 4-bit unsigned integer. Indicates the length of 694 the variable-length Token field (0-8 bytes). Lengths 9-15 are 695 reserved, MUST NOT be sent, and MUST be processed as a message 696 format error. 698 Code: 8-bit unsigned integer. Indicates if the message carries a 699 request (1-31) or a response (64-191), or is empty (0). (All 700 other code values are reserved.) In case of a request, the Code 701 field indicates the Request Method; in case of a response a 702 Response Code. Possible values are maintained in the CoAP Code 703 Registry (Section 12.1). The semantics of requests and responses 704 are defined in Section 5. 706 Message ID: 16-bit unsigned integer in network byte order. Used for 707 the detection of message duplication, and to match messages of 708 type Acknowledgement/Reset to messages of type Confirmable/ 709 Non-confirmable. The rules for generating a Message ID and 710 matching messages are defined in Section 4. 712 The header is followed by the Token value, which may be 0 to 8 bytes, 713 as given by the Token Length field. The Token value is used to 714 correlate requests and responses. The rules for generating a Token 715 and correlating requests and responses are defined in Section 5.3.1. 717 Header and Token are followed by zero or more Options (Section 3.1). 718 An Option can be followed by the end of the message, by another 719 Option, or by the Payload Marker and the payload. 721 Following the header, token, and options, if any, comes the optional 722 payload. If present and of non-zero length, it is prefixed by a 723 fixed, one-byte Payload Marker (0xFF) which indicates the end of 724 options and the start of the payload. The payload data extends from 725 after the marker to the end of the UDP datagram, i.e., the Payload 726 Length is calculated from the datagram size. The absence of the 727 Payload Marker denotes a zero-length payload. The presence of a 728 marker followed by a zero-length payload MUST be processed as a 729 message format error. 731 3.1. Option Format 733 CoAP defines a number of options which can be included in a message. 734 Each option instance in a message specifies the Option Number of the 735 defined CoAP option, the length of the Option Value and the Option 736 Value itself. 738 Instead of specifying the Option Number directly, the instances MUST 739 appear in order of their Option Numbers and a delta encoding is used 740 between them: The Option Number for each instance is calculated as 741 the sum of its delta and the Option Number of the preceding instance 742 in the message. For the first instance in a message, a preceding 743 option instance with Option Number zero is assumed. Multiple 744 instances of the same option can be included by using a delta of 745 zero. 747 Option Numbers are maintained in the CoAP Option Number Registry 748 (Section 12.2). See Section 5.4 for the semantics of the options 749 defined in this document. 751 0 1 2 3 4 5 6 7 752 +---------------+---------------+ 753 | | | 754 | Option Delta | Option Length | 1 byte 755 | | | 756 +---------------+---------------+ 757 \ \ 758 / Option Delta / 0-2 bytes 759 \ (extended) \ 760 +-------------------------------+ 761 \ \ 762 / Option Length / 0-2 bytes 763 \ (extended) \ 764 +-------------------------------+ 765 \ \ 766 / / 767 \ \ 768 / Option Value / 0 or more bytes 769 \ \ 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. A value between 0 and 12 779 indicates the Option Delta. Three values are reserved for special 780 constructs: 782 13: An 8-bit unsigned integer follows the initial byte and 783 indicates the Option Delta minus 13. 785 14: A 16-bit unsigned integer in network byte order follows the 786 initial byte and indicates the Option Delta minus 269. 788 15: Reserved for the Payload Marker. If the field is set to this 789 value but the entire byte is not the payload marker, this MUST 790 be processed as a message format error. 792 The resulting Option Delta is used as the difference between the 793 Option Number of this option and that of the previous option (or 794 zero for the first option). In other words, the Option Number is 795 calculated by simply summing the Option Delta values of this and 796 all previous options before it. 798 Option Length: 4-bit unsigned integer. A value between 0 and 12 799 indicates the length of the Option Value, in bytes. Three values 800 are reserved for special constructs: 802 13: An 8-bit unsigned integer precedes the Option Value and 803 indicates the Option Length minus 13. 805 14: A 16-bit unsigned integer in network byte order precedes the 806 Option Value and indicates the Option Length minus 269. 808 15: Reserved for future use. If the field is set to this value, 809 it MUST be processed as a message format error. 811 Value: A sequence of exactly Option Length bytes. The length and 812 format of the Option Value depend on the respective option, which 813 MAY define variable length values. See Section 3.2 for the 814 formats used in this document; options defined in other documents 815 MAY make use of other option value formats. 817 3.2. Option Value Formats 819 The options defined in this document make use of the following option 820 value formats. 822 empty: A zero-length sequence of bytes. 824 opaque: An opaque sequence of bytes. 826 uint: A non-negative integer which is represented in network byte 827 order using the number of bytes given by the Option Length 828 field. 830 An option definition may specify a range of permissible 831 numbers of bytes; if it has a choice, a sender SHOULD 832 represent the integer with as few bytes as possible, i.e., 833 without leading zeros. A recipient MUST be prepared to 834 process values with leading zeros. 836 Implementation Note: The exceptional behavior permitted 837 for the sender is intended for highly 838 constrained, templated implementations (e.g., 839 hardware implementations) that use fixed size 840 options in the templates. 842 string: A Unicode string which is encoded using UTF-8 [RFC3629] in 843 Net-Unicode form [RFC5198]. 845 Note that here and in all other places where UTF-8 encoding 846 is used in the CoAP protocol, the intention is that the 847 encoded strings can be directly used and compared as opaque 848 byte strings by CoAP protocol implementations. There is no 849 expectation and no need to perform normalization within a 850 CoAP implementation (except where Unicode strings that are 851 not known to be normalized are imported from sources 852 outside the CoAP protocol). Note also that ASCII strings 853 (that do not make use of special control characters) are 854 always valid UTF-8 Net-Unicode strings. 856 4. Message Transmission 858 CoAP messages are exchanged asynchronously between CoAP endpoints. 859 They are used to transport CoAP requests and responses, the semantics 860 of which are defined in Section 5. 862 As CoAP is bound to non-reliable transports such as UDP, CoAP 863 messages may arrive out of order, appear duplicated, or go missing 864 without notice. For this reason, CoAP implements a lightweight 865 reliability mechanism, without trying to re-create the full feature 866 set of a transport like TCP. It has the following features: 868 o Simple stop-and-wait retransmission reliability with exponential 869 back-off for Confirmable messages. 871 o Duplicate detection for both Confirmable and Non-Confirmable 872 messages. 874 4.1. Messages and Endpoints 876 A CoAP endpoint is the source or destination of a CoAP message. It 877 is identified depending on the security mode used (see Section 9): 878 With no security, the endpoint is solely identified by an IP address 879 and a UDP port number. With other security modes, the endpoint is 880 identified as defined by the security mode. 882 There are different types of messages. The type of a message is 883 specified by the Type field of the CoAP Header. 885 Separate from the message type, a message may carry a request, a 886 response, or be empty. This is signaled by the Request/Response Code 887 field in the CoAP Header and is relevant to the request/response 888 model. Possible values for the field are maintained in the CoAP Code 889 Registry (Section 12.1). 891 An empty message has the Code field set to 0. The Token Length field 892 MUST be set to 0 and no bytes MUST be present after the Message ID 893 field. If there are any bytes, they MUST be processed as a message 894 format error. 896 4.2. Messages Transmitted Reliably 898 The reliable transmission of a message is initiated by marking the 899 message as Confirmable in the CoAP header. A Confirmable message 900 always carries either a request or response and MUST NOT be empty. A 901 recipient MUST acknowledge such a message with an Acknowledgement 902 message or, if it lacks context to process the message properly 903 (including the case where the message is empty or has a message 904 format error), MUST reject it; rejecting a Confirmable message is 905 effected by sending a matching Reset message and otherwise ignoring 906 it. The Acknowledgement message MUST echo the Message ID of the 907 Confirmable message, and MUST carry a response or be empty (see 908 Section 5.2.1 and Section 5.2.2). The Reset message MUST echo the 909 Message ID of the confirmable message, and MUST be empty. Rejecting 910 an Acknowledgement or Reset message is effected by silently ignoring 911 it. 913 The sender retransmits the Confirmable message at exponentially 914 increasing intervals, until it receives an acknowledgement (or Reset 915 message), or runs out of attempts. 917 Retransmission is controlled by two things that a CoAP endpoint MUST 918 keep track of for each Confirmable message it sends while waiting for 919 an acknowledgement (or reset): a timeout and a retransmission 920 counter. For a new Confirmable message, the initial timeout is set 921 to a random number between ACK_TIMEOUT and (ACK_TIMEOUT * 922 ACK_RANDOM_FACTOR) (see Section 4.8), and the retransmission counter 923 is set to 0. When the timeout is triggered and the retransmission 924 counter is less than MAX_RETRANSMIT, the message is retransmitted, 925 the retransmission counter is incremented, and the timeout is 926 doubled. If the retransmission counter reaches MAX_RETRANSMIT on a 927 timeout, or if the endpoint receives a Reset message, then the 928 attempt to transmit the message is canceled and the application 929 process informed of failure. On the other hand, if the endpoint 930 receives an acknowledgement message in time, transmission is 931 considered successful. 933 A CoAP endpoint that sent a Confirmable message MAY give up in 934 attempting to obtain an ACK even before the MAX_RETRANSMIT counter 935 value is reached: E.g., the application has canceled the request as 936 it no longer needs a response, or there is some other indication that 937 the CON message did arrive. In particular, a CoAP request message 938 may have elicited a separate response, in which case it is clear to 939 the requester that only the ACK was lost and a retransmission of the 940 request would serve no purpose. However, a responder MUST NOT in 941 turn rely on this cross-layer behavior from a requester, i.e. it 942 SHOULD retain the state to create the ACK for the request, if needed, 943 even if a Confirmable response was already acknowledged by the 944 requester. 946 4.3. Messages Transmitted Without Reliability 948 Some messages do not require an acknowledgement. This is 949 particularly true for messages that are repeated regularly for 950 application requirements, such as repeated readings from a sensor 951 where eventual success is sufficient. 953 As a more lightweight alternative, a message can be transmitted less 954 reliably by marking the message as Non-confirmable. A Non- 955 confirmable message always carries either a request or response and 956 MUST NOT be empty. A Non-confirmable message MUST NOT be 957 acknowledged by the recipient. If a recipient lacks context to 958 process the message properly (including the case where the message is 959 empty or has a message format error), it MUST reject the message; 960 rejecting a Non-Confirmable message MAY involve sending a matching 961 Reset message, and apart from the Reset message the rejected message 962 MUST be silently ignored. 964 At the CoAP level, there is no way for the sender to detect if a Non- 965 confirmable message was received or not. A sender MAY choose to 966 transmit multiple copies of a Non-confirmable message within 967 MAX_TRANSMIT_SPAN, or the network may duplicate the message in 968 transit. To enable the receiver to act only once on the message, 969 Non-confirmable messages specify a Message ID as well. (This Message 970 ID is drawn from the same number space as the Message IDs for 971 Confirmable messages.) 973 4.4. Message Correlation 975 An Acknowledgement or Reset message is related to a Confirmable 976 message or Non-confirmable message by means of a Message ID along 977 with additional address information of the corresponding endpoint. 978 The Message ID is a 16-bit unsigned integer that is generated by the 979 sender of a Confirmable or Non-confirmable message and included in 980 the CoAP header. The Message ID MUST be echoed in the 981 Acknowledgement or Reset message by the recipient. 983 The same Message ID MUST NOT be re-used (in communicating with the 984 same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2). 986 Implementation Note: Several implementation strategies can be 987 employed for generating Message IDs. In the simplest case a CoAP 988 endpoint generates Message IDs by keeping a single Message ID 989 variable, which is changed each time a new confirmable or non- 990 confirmable message is sent regardless of the destination address 991 or port. Endpoints dealing with large numbers of transactions 992 could keep multiple Message ID variables, for example per prefix 993 or destination address. The initial variable value should be 994 randomized. 996 For an Acknowledgement or Reset message to match a Confirmable or 997 Non-confirmable message, the Message ID and source endpoint of the 998 Acknowledgement or Reset message MUST match the Message ID and 999 destination endpoint of the Confirmable or Non-confirmable message. 1001 4.5. Message Deduplication 1003 A recipient MUST be prepared to receive the same Confirmable message 1004 (as indicated by the Message ID and source endpoint) multiple times 1005 within the EXCHANGE_LIFETIME (Section 4.8.2), for example, when its 1006 Acknowledgement went missing or didn't reach the original sender 1007 before the first timeout. The recipient SHOULD acknowledge each 1008 duplicate copy of a Confirmable message using the same 1009 Acknowledgement or Reset message, but SHOULD process any request or 1010 response in the message only once. This rule MAY be relaxed in case 1011 the Confirmable message transports a request that is idempotent (see 1012 Section 5.1) or can be handled in an idempotent fashion. Examples 1013 for relaxed message deduplication: 1015 o A server MAY relax the requirement to answer all retransmissions 1016 of an idempotent request with the same response (Section 4.2), so 1017 that it does not have to maintain state for Message IDs. For 1018 example, an implementation might want to process duplicate 1019 transmissions of a GET, PUT or DELETE request as separate requests 1020 if the effort incurred by duplicate processing is less expensive 1021 than keeping track of previous responses would be. 1023 o A constrained server MAY even want to relax this requirement for 1024 certain non-idempotent requests if the application semantics make 1025 this trade-off favorable. For example, if the result of a POST 1026 request is just the creation of some short-lived state at the 1027 server, it may be less expensive to incur this effort multiple 1028 times for a request than keeping track of whether a previous 1029 transmission of the same request already was processed. 1031 A recipient MUST be prepared to receive the same Non-confirmable 1032 message (as indicated by the Message ID and source endpoint) multiple 1033 times within NON_LIFETIME (Section 4.8.2). As a general rule that 1034 MAY be relaxed based on the specific semantics of a message, the 1035 recipient SHOULD silently ignore any duplicated Non-confirmable 1036 message, and SHOULD process any request or response in the message 1037 only once. 1039 4.6. Message Size 1041 While specific link layers make it beneficial to keep CoAP messages 1042 small enough to fit into their link layer packets (see Section 1), 1043 this is a matter of implementation quality. The CoAP specification 1044 itself provides only an upper bound to the message size. Messages 1045 larger than an IP fragment result in undesired packet fragmentation. 1046 A CoAP message, appropriately encapsulated, SHOULD fit within a 1047 single IP packet (i.e., avoid IP fragmentation) and (by fitting into 1048 one UDP payload) obviously MUST fit within a single IP datagram. If 1049 the Path MTU is not known for a destination, an IP MTU of 1280 bytes 1050 SHOULD be assumed; if nothing is known about the size of the headers, 1051 good upper bounds are 1152 bytes for the message size and 1024 bytes 1052 for the payload size. 1054 Implementation Note: CoAP's choice of message size parameters works 1055 well with IPv6 and with most of today's IPv4 paths. (However, 1056 with IPv4, it is harder to absolutely ensure that there is no IP 1057 fragmentation. If IPv4 support on unusual networks is a 1058 consideration, implementations may want to limit themselves to 1059 more conservative IPv4 datagram sizes such as 576 bytes; worse, 1060 the absolute minimum value of the IP MTU for IPv4 is as low as 68 1061 bytes, which would leave only 40 bytes minus security overhead for 1062 a UDP payload. Implementations extremely focused on this problem 1063 set might also set the IPv4 DF bit and perform some form of path 1064 MTU discovery; this should generally be unnecessary in most 1065 realistic use cases for CoAP, however.) A more important kind of 1066 fragmentation in many constrained networks is that on the 1067 adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 1068 bytes including various overheads); this may motivate 1069 implementations to be frugal in their packet sizes and to move to 1070 block-wise transfers [I-D.ietf-core-block] when approaching three- 1071 digit message sizes. 1073 Message sizes are also of considerable importance to 1074 implementations on constrained nodes. Many implementations will 1075 need to allocate a buffer for incoming messages. If an 1076 implementation is too constrained to allow for allocating the 1077 above-mentioned upper bound, it could apply the following 1078 implementation strategy: Implementations receiving a datagram into 1079 a buffer that is too small are usually able to determine if the 1080 trailing portion of a datagram was discarded and to retrieve the 1081 initial portion. So, if not all of the payload, at least the CoAP 1082 header and options are likely to fit within the buffer. A server 1083 can thus fully interpret a request and return a 4.13 (Request 1084 Entity Too Large) response code if the payload was truncated. A 1085 client sending an idempotent request and receiving a response 1086 larger than would fit in the buffer can repeat the request with a 1087 suitable value for the Block Option [I-D.ietf-core-block]. 1089 4.7. Congestion Control 1091 Basic congestion control for CoAP is provided by the exponential 1092 back-off mechanism in Section 4.2. 1094 In order not to cause congestion, Clients (including proxies) MUST 1095 strictly limit the number of simultaneous outstanding interactions 1096 that they maintain to a given server (including proxies) to NSTART. 1097 An outstanding interaction is either a CON for which an ACK has not 1098 yet been received but is still expected (message layer) or a request 1099 for which neither a response nor an Acknowledgment message has yet 1100 been received but is still expected (which may both occur at the same 1101 time, counting as one outstanding interaction). The default value of 1102 NSTART for this specification is 1. 1104 Further congestion control optimizations and considerations are 1105 expected in the future, which may for example provide automatic 1106 initialization of the CoAP transmission parameters defined in 1107 Section 4.8, and thus may allow a value for NSTART greater than one. 1109 A client stops expecting a response to a Confirmable request for 1110 which no acknowledgment message was received, after 1111 EXCHANGE_LIFETIME. The specific algorithm by which a client stops to 1112 "expect" a response to a Confirmable request that was acknowledged, 1113 or to a Non-confirmable request, is not defined. Unless this is 1114 modified by additional congestion control optimizations, it MUST be 1115 chosen in such a way that an endpoint does not exceed an average data 1116 rate of PROBING_RATE in sending to another endpoint that does not 1117 respond. 1119 Note: CoAP places the onus of congestion control mostly on the 1120 clients. However, clients may malfunction or actually be 1121 attackers, e.g. to perform amplification attacks (Section 11.3). 1122 To limit the damage (to the network and to its own energy 1123 resources), a server SHOULD implement some rate limiting for its 1124 response transmission based on reasonable assumptions about 1125 application requirements. This is most helpful if the rate limit 1126 can be made effective for the misbehaving endpoints, only. 1128 4.8. Transmission Parameters 1130 Message transmission is controlled by the following parameters: 1132 +-------------------+---------------+ 1133 | name | default value | 1134 +-------------------+---------------+ 1135 | ACK_TIMEOUT | 2 seconds | 1136 | ACK_RANDOM_FACTOR | 1.5 | 1137 | MAX_RETRANSMIT | 4 | 1138 | NSTART | 1 | 1139 | DEFAULT_LEISURE | 5 seconds | 1140 | PROBING_RATE | 1 Byte/second | 1141 +-------------------+---------------+ 1143 4.8.1. Changing The Parameters 1145 The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT, 1146 NSTART, DEFAULT_LEISURE, and PROBING_RATE may be configured to values 1147 specific to the application environment (including dynamically 1148 adjusted values), however the configuration method is out of scope of 1149 this document. It is recommended that an application environment use 1150 consistent values for these parameters. 1152 The transmission parameters have been chosen to achieve a behavior in 1153 the presence of congestion that is safe in the Internet. If a 1154 configuration desires to use different values, the onus is on the 1155 configuration to ensure these congestion control properties are not 1156 violated. In particular, a decrease of ACK_TIMEOUT below 1 second 1157 would violate the guidelines of [RFC5405]. 1158 ([I-D.allman-tcpm-rto-consider] provides some additional background.) 1159 CoAP was designed to enable implementations that do not maintain 1160 round-trip-time (RTT) measurements. However, where it is desired to 1161 decrease the ACK_TIMEOUT significantly or increase NSTART, this can 1162 only be done safely when maintaining such measurements. 1163 Configurations MUST NOT decrease ACK_TIMEOUT or increase NSTART 1164 without using mechanisms that ensure congestion control safety, 1165 either defined in the configuration or in future standards documents. 1167 ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have 1168 a value that is sufficiently different from 1.0 to provide some 1169 protection from synchronization effects. 1171 MAX_RETRANSMIT can be freely adjusted, but a too small value will 1172 reduce the probability that a confirmable message is actually 1173 received, while a larger value than given here will require further 1174 adjustments in the time values (see discussion below). 1176 If the choice of transmission parameters leads to an increase of 1177 derived time values (see below), the configuration mechanism MUST 1178 ensure the adjusted value is also available to all the endpoints in 1179 communicating with which these adjusted values are to be used. 1181 4.8.2. Time Values derived from Transmission Parameters 1183 The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR and MAX_RETRANSMIT 1184 influences the timing of retransmissions, which in turn influences 1185 how long certain information items need to be kept by an 1186 implementation. To be able to unambiguously reference these derived 1187 time values, we give them names as follows: 1189 o MAX_TRANSMIT_SPAN is the maximum time from the first transmission 1190 of a confirmable message to its last retransmission. For the 1191 default transmission parameters, the value is (2+4+8+16)*1.5 = 45 1192 seconds, or more generally: 1194 ACK_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * ACK_RANDOM_FACTOR 1196 o MAX_TRANSMIT_WAIT is the maximum time from the first transmission 1197 of a confirmable message to the time when the sender gives up on 1198 receiving an acknowledgement or reset. For the default 1199 transmission parameters, the value is (2+4+8+16+32)*1.5 = 93 1200 seconds, or more generally: 1202 ACK_TIMEOUT * (2 ** (MAX_RETRANSMIT + 1) - 1) * 1203 ACK_RANDOM_FACTOR 1205 In addition, some assumptions need to be made on the characteristics 1206 of the network and the nodes. 1208 o MAX_LATENCY is the maximum time a datagram is expected to take 1209 from the start of its transmission to the completion of its 1210 reception. This constant is related to the MSL (Maximum Segment 1211 Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 1212 minutes" ([RFC0793] glossary, page 81). Note that this is not 1213 necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not 1214 intended to describe a situation when the protocol works well, but 1215 the worst case situation against which the protocol has to guard. 1216 We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart 1217 from being reasonably realistic for the bulk of configurations as 1218 well as close to the historic choice for TCP, this value also 1219 allows message ID lifetime timers to be represented in 8 bits 1220 (when measured in seconds). In these calculations, there is no 1221 assumption that the direction of the transmission is irrelevant 1222 (i.e. that the network is symmetric), just that the same value can 1223 reasonably be used as a maximum value for both directions. If 1224 that is not the case, the following calculations become only 1225 slightly more complex. 1227 o PROCESSING_DELAY is the time a node takes to turn around a 1228 confirmable message into an acknowledgement. We assume the node 1229 will attempt to send an ACK before having the sender time out, so 1230 as a conservative assumption we set it equal to ACK_TIMEOUT. 1232 o MAX_RTT is the maximum round-trip time, or: 1234 2 * MAX_LATENCY + PROCESSING_DELAY 1236 From these values, we can derive the following values relevant to the 1237 protocol operation: 1239 o EXCHANGE_LIFETIME is the time from starting to send a confirmable 1240 message to the time when an acknowledgement is no longer expected, 1241 i.e. message layer information about the message exchange can be 1242 purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a 1243 MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the 1244 way back. Note that there is no need to consider 1245 MAX_TRANSMIT_WAIT if the configuration is chosen such that the 1246 last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the 1247 difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is 1248 less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY 1249 is a worst case value unlikely to be met in the real world. In 1250 this case, EXCHANGE_LIFETIME simplifies to: 1252 (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * ACK_RANDOM_FACTOR) + 1253 (2 * MAX_LATENCY) + PROCESSING_DELAY 1255 or 248 seconds with the default transmission parameters. 1257 o NON_LIFETIME is the time from sending a non-confirmable message to 1258 the time its message-ID can be safely reused. If multiple 1259 transmission of a NON message is not used, its value is 1260 MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a 1261 NON message multiple times, in particular for multicast 1262 applications. While the period of re-use is not bounded by the 1263 specification, an expectation of reliable detection of duplication 1264 at the receiver is in the timescales of MAX_TRANSMIT_SPAN. 1265 Therefore, for this purpose, it is safer to use the value: 1267 MAX_TRANSMIT_SPAN + MAX_LATENCY 1269 or 145 seconds with the default transmission parameters; however, 1270 an implementation that just wants to use a single timeout value 1271 for retiring message-IDs can safely use the larger value for 1272 EXCHANGE_LIFETIME. 1274 5. Request/Response Semantics 1276 CoAP operates under a similar request/response model as HTTP: a CoAP 1277 endpoint in the role of a "client" sends one or more CoAP requests to 1278 a "server", which services the requests by sending CoAP responses. 1279 Unlike HTTP, requests and responses are not sent over a previously 1280 established connection, but exchanged asynchronously over CoAP 1281 messages. 1283 5.1. Requests 1285 A CoAP request consists of the method to be applied to the resource, 1286 the identifier of the resource, a payload and Internet media type (if 1287 any), and optional meta-data about the request. 1289 CoAP supports the basic methods of GET, POST, PUT, DELETE, which are 1290 easily mapped to HTTP. They have the same properties of safe (only 1291 retrieval) and idempotent (you can invoke it multiple times with the 1292 same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method 1293 is safe, therefore it MUST NOT take any other action on a resource 1294 other than retrieval. The GET, PUT and DELETE methods MUST be 1295 performed in such a way that they are idempotent. POST is not 1296 idempotent, because its effect is determined by the origin server and 1297 dependent on the target resource; it usually results in a new 1298 resource being created or the target resource being updated. 1300 A request is initiated by setting the Code field in the CoAP header 1301 of a Confirmable or a Non-confirmable message to a Method Code and 1302 including request information. 1304 The methods used in requests are described in detail in Section 5.8. 1306 5.2. Responses 1308 After receiving and interpreting a request, a server responds with a 1309 CoAP response, which is matched to the request by means of a client- 1310 generated token. 1312 A response is identified by the Code field in the CoAP header being 1313 set to a Response Code. Similar to the HTTP Status Code, the CoAP 1314 Response Code indicates the result of the attempt to understand and 1315 satisfy the request. These codes are fully defined in Section 5.9. 1316 The Response Code numbers to be set in the Code field of the CoAP 1317 header are maintained in the CoAP Response Code Registry 1318 (Section 12.1.2). 1320 0 1321 0 1 2 3 4 5 6 7 1322 +-+-+-+-+-+-+-+-+ 1323 |class| detail | 1324 +-+-+-+-+-+-+-+-+ 1326 Figure 9: Structure of a Response Code 1328 The upper three bits of the 8-bit Response Code number define the 1329 class of response. The lower five bits do not have any 1330 categorization role; they give additional detail to the overall class 1331 (Figure 9). There are 3 classes: 1333 2 - Success: The request was successfully received, understood, and 1334 accepted. 1336 4 - Client Error: The request contains bad syntax or cannot be 1337 fulfilled. 1339 5 - Server Error: The server failed to fulfill an apparently valid 1340 request. 1342 The response codes are designed to be extensible: Response Codes in 1343 the Client Error and Server Error class that are unrecognized by an 1344 endpoint MUST be treated as being equivalent to the generic Response 1345 Code of that class (4.00 and 5.00, respectively). However, there is 1346 no generic Response Code indicating success, so a Response Code in 1347 the Success class that is unrecognized by an endpoint can only be 1348 used to determine that the request was successful without any further 1349 details. 1351 As a human readable notation for specifications and protocol 1352 diagnostics, the numeric value of a response code is indicated by 1353 giving the upper three bits in decimal, followed by a dot and then 1354 the lower five bits in a two-digit decimal. E.g., "Not Found" is 1355 written as 4.04 -- indicating a value of hexadecimal 0x84 or decimal 1356 132. In other words, the dot "." functions as a short-cut for 1357 "*32+". 1359 The possible response codes are described in detail in Section 5.9. 1361 Responses can be sent in multiple ways, which are defined below. 1363 5.2.1. Piggy-backed 1365 In the most basic case, the response is carried directly in the 1366 Acknowledgement message that acknowledges the request (which requires 1367 that the request was carried in a Confirmable message). This is 1368 called a "Piggy-backed" Response. 1370 The response is returned in the Acknowledgement message independent 1371 of whether the response indicates success or failure. In effect, the 1372 response is piggy-backed on the Acknowledgement message, so no 1373 separate message is required to both acknowledge that the request was 1374 received and return the response. 1376 Implementation Note: The protocol leaves the decision whether to 1377 piggy-back a response or not (i.e., send a separate response) to 1378 the server. The client MUST be prepared to receive either. On 1379 the quality of implementation level, there is a strong expectation 1380 that servers will implement code to piggy-back whenever possible 1381 -- saving resources in the network and both at the client and at 1382 the server. 1384 5.2.2. Separate 1386 It may not be possible to return a piggy-backed response in all 1387 cases. For example, a server might need longer to obtain the 1388 representation of the resource requested than it can wait sending 1389 back the Acknowledgement message, without risking the client to 1390 repeatedly retransmit the request message. Responses to requests 1391 carried in a Non-Confirmable message are always sent separately (as 1392 there is no Acknowledgement message). 1394 The server maybe initiates the attempt to obtain the resource 1395 representation and times out an acknowledgement timer, or it 1396 immediately sends an acknowledgement knowing in advance that there 1397 will be no piggy-backed response. The acknowledgement effectively is 1398 a promise that the request will be acted upon. 1400 When the server finally has obtained the resource representation, it 1401 sends the response. When it is desired that this message is not 1402 lost, it is sent as a Confirmable message from the server to the 1403 client and answered by the client with an Acknowledgement, echoing 1404 the new Message ID chosen by the server. (It may also be sent as a 1405 Non-Confirmable message; see Section 5.2.3.) 1407 Implementation Notes: Note that, as the underlying datagram 1408 transport may not be sequence-preserving, the Confirmable message 1409 carrying the response may actually arrive before or after the 1410 acknowledgement message for the request. Note also that, while 1411 the CoAP protocol itself does not make any specific demands here, 1412 there is an expectation that the response will come within a time 1413 frame that is reasonable from an application point of view; as 1414 there is no underlying transport protocol that could be instructed 1415 to run a keep-alive mechanism, the requester MAY want to set up a 1416 timeout that is unrelated to CoAP's retransmission timers in case 1417 the server is destroyed or otherwise unable to send the response.) 1419 An exchange is separate by definition when the Acknowledgement to the 1420 Confirmable request is an empty message. The Acknowledgement to the 1421 Confirmable response MUST also be an empty message, i.e. one that 1422 carries neither a request nor a response. However, a server MUST 1423 stop retransmitting its response on any matching Acknowledgement 1424 (silently ignoring any response code or payload) or Reset message. 1426 5.2.3. Non-Confirmable 1428 If the request message is Non-confirmable, then the response SHOULD 1429 be returned in a Non-confirmable message as well. However, an 1430 endpoint MUST be prepared to receive a Non-confirmable response 1431 (preceded or followed by an empty acknowledgement message) in reply 1432 to a Confirmable request, or a Confirmable response in reply to a 1433 Non-confirmable request. 1435 5.3. Request/Response Matching 1437 Regardless of how a response is sent, it is matched to the request by 1438 means of a token that is included by the client in the request, along 1439 with additional address information of the corresponding endpoint. 1441 5.3.1. Token 1443 The Token is used to match a response with a request. The token 1444 value is a sequence of 0 to 8 bytes. (Note that every message 1445 carries a token, even if it is of zero length.) Every request 1446 carries a client-generated token, which the server MUST echo in any 1447 resulting response without modification. 1449 A token is intended for use as a client-local identifier for 1450 differentiating between concurrent requests (see Section 5.3); it 1451 could have been called a "request ID". 1453 The client SHOULD generate tokens in such a way that tokens currently 1454 in use for a given source/destination endpoint pair are unique. 1455 (Note that a client implementation can use the same token for any 1456 request if it uses a different endpoint each time, e.g. a different 1457 source port number.) An empty token value is appropriate e.g. when 1458 no other tokens are in use to a destination, or when requests are 1459 made serially per destination and receive piggy-backed responses. 1460 There are however multiple possible implementation strategies to 1461 fulfill this. 1463 An endpoint receiving a token it did not generate MUST treat it as 1464 opaque and make no assumptions about its format. 1466 5.3.2. Request/Response Matching Rules 1468 The exact rules for matching a response to a request are as follows: 1470 1. The source endpoint of the response MUST be the same as the 1471 destination endpoint of the original request. 1473 2. In a piggy-backed response, both the Message ID of the 1474 Confirmable request and the Acknowledgement, and the token of the 1475 response and original request MUST match. In a separate 1476 response, just the token of the response and original request 1477 MUST match. 1479 In case a message carrying a response is unexpected (i.e. the client 1480 is not waiting for a response at the endpoint addressed and/or with 1481 the given token), the response is rejected (Section 4.2, 1482 Section 4.3). 1484 Implementation Note: A client that receives a response in a CON 1485 message may want to clean up the message state right after sending 1486 the ACK. If that ACK is lost and the server retransmits the CON, 1487 the client may no longer have any state to correlate this response 1488 to, making the retransmission an unexpected message; the client 1489 may send a Reset message so it does not receive any more 1490 retransmissions. This behavior is normal and not an indication of 1491 an error. (Clients that are not aggressively optimized in their 1492 state memory usage will still have message state that will 1493 identify the second CON as a retransmission. Clients that 1494 actually expect more messages from the server 1495 [I-D.ietf-core-observe] will have to keep state in any case.) 1497 5.4. Options 1499 Both requests and responses may include a list of one or more 1500 options. For example, the URI in a request is transported in several 1501 options, and meta-data that would be carried in an HTTP header in 1502 HTTP is supplied as options as well. 1504 CoAP defines a single set of options that are used in both requests 1505 and responses: 1507 o Content-Format 1509 o ETag 1510 o Location-Path 1512 o Location-Query 1514 o Max-Age 1516 o Proxy-Uri 1518 o Proxy-Scheme 1520 o Uri-Host 1522 o Uri-Path 1524 o Uri-Port 1526 o Uri-Query 1528 o Accept 1530 o If-Match 1532 o If-None-Match 1534 The semantics of these options along with their properties are 1535 defined in detail in Section 5.10. 1537 Not all options are defined for use with all methods and response 1538 codes. The possible options for methods and response codes are 1539 defined in Section 5.8 and Section 5.9 respectively. In case an 1540 option is not defined for a method or response code, it MUST NOT be 1541 included by a sender and MUST be treated like an unrecognized option 1542 by a recipient. 1544 5.4.1. Critical/Elective 1546 Options fall into one of two classes: "critical" or "elective". The 1547 difference between these is how an option unrecognized by an endpoint 1548 is handled: 1550 o Upon reception, unrecognized options of class "elective" MUST be 1551 silently ignored. 1553 o Unrecognized options of class "critical" that occur in a 1554 confirmable request MUST cause the return of a 4.02 (Bad Option) 1555 response. This response SHOULD include a diagnostic payload 1556 describing the unrecognized option(s) (see Section 5.5.2). 1558 o Unrecognized options of class "critical" that occur in a 1559 confirmable response, or piggy-backed in an acknowledgement, MUST 1560 cause the response to be rejected (Section 4.2). 1562 o Unrecognized options of class "critical" that occur in a non- 1563 confirmable message MUST cause the message to be rejected 1564 (Section 4.3). 1566 Note that, whether critical or elective, an option is never 1567 "mandatory" (it is always optional): These rules are defined in order 1568 to enable implementations to stop processing options they do not 1569 understand or implement. 1571 Critical/Elective rules apply to non-proxying endpoints. A proxy 1572 processes options based on Unsafe/Safe classes as defined in 1573 Section 5.7. 1575 5.4.2. Proxy Unsafe/Safe and Cache-Key 1577 In addition to an option being marked as Critical or Elective, 1578 options are also classified based on how a proxy is to deal with the 1579 option if it does not recognize it. For this purpose, an option can 1580 either be considered Unsafe to Forward (UnSafe is set) or Safe to 1581 Forward (UnSafe is clear). 1583 In addition, for options that are marked Safe to Forward, the option 1584 indicates whether it is intended to be part of the Cache-Key in a 1585 request (NoCacheKey is not all set) or not (NoCacheKey is set). 1587 Note: The Cache-Key indication is relevant only for proxies that do 1588 not implement the given option as a request option and instead 1589 rely on the Safe/Unsafe indication only. E.g., for ETag, actually 1590 using the request option as a cache key is grossly inefficient, 1591 but it is the best thing one can do if ETag is not implemented by 1592 a proxy, as the response is going to differ based on the presence 1593 of the request option. A more useful proxy that does implement 1594 the ETag request option is not using ETag as a cache key. 1596 Proxy behavior with regard to these classes is defined in 1597 Section 5.7. 1599 5.4.3. Length 1601 Option values are defined to have a specific length, often in the 1602 form of an upper and lower bound. If the length of an option value 1603 in a request is outside the defined range, that option MUST be 1604 treated like an unrecognized option (see Section 5.4.1). 1606 5.4.4. Default Values 1608 Options may be defined to have a default value. If the value of 1609 option is intended to be this default value, the option SHOULD NOT be 1610 included in the message. If the option is not present, the default 1611 value MUST be assumed. 1613 Where a critical option has a default value, this is chosen in such a 1614 way that the absence of the option in a message can be processed 1615 properly both by implementations unaware of the critical option and 1616 by implementations that interpret this absence as the presence of the 1617 default value for the option. 1619 5.4.5. Repeatable Options 1621 The definition of an option MAY specify the option to be repeatable. 1622 An option that is repeatable MAY be included one or more times in a 1623 message. An option that is not repeatable MUST NOT be included more 1624 than once in a message. 1626 If a message includes an option with more occurrences than the option 1627 is defined for, the additional option occurrences MUST be treated 1628 like an unrecognized option (see Section 5.4.1). 1630 5.4.6. Option Numbers 1632 An Option is identified by an option number, which also provides some 1633 additional semantics information: e.g., odd numbers indicate a 1634 critical option, while even numbers indicate an elective option. 1635 Note that this is not just a convention, it is a feature of the 1636 protocol: Whether an option is elective or critical is entirely 1637 determined by whether its option number is even or odd. 1639 More generally speaking, an Option number is constructed with a bit 1640 mask to indicate if an option is Critical/Elective, Unsafe/Safe and 1641 in the case of Safe, also a Cache-Key indication as shown by the 1642 following figure. When bit 7 (the least significant bit) is 1, an 1643 option is Critical (and likewise Elective when 0). When bit 6 is 1, 1644 an option is Unsafe (and likewise Safe when 0). When bit 6 is 0, 1645 i.e., the option is not Unsafe, it is not a Cache-Key (NoCacheKey) if 1646 and only if bits 3-5 are all set to 1; all other bit combinations 1647 mean that it indeed is a Cache-Key. These classes of options are 1648 explained in the next sections. 1650 0 1 2 3 4 5 6 7 1651 +---+---+---+---+---+---+---+---+ 1652 | | NoCacheKey| U | C | 1653 +---+---+---+---+---+---+---+---+ 1655 Figure 10: Option Number Mask 1657 An endpoint may use an equivalent of the C code in Figure 11 to 1658 derive the characteristics of an option number "onum". 1660 Critical = (onum & 1); 1661 UnSafe = (onum & 2); 1662 NoCacheKey = ((onum & 0x1e) == 0x1c); 1664 Figure 11: Determining Characteristics from an Option Number 1666 The option numbers for the options defined in this document are 1667 listed in the CoAP Option Number Registry (Section 12.2). 1669 5.5. Payloads and Representations 1671 Both requests and responses may include a payload, depending on the 1672 method or response code respectively. If a method or response code 1673 is not defined to have a payload, then a sender MUST NOT include one, 1674 and a recipient MUST ignore it. 1676 5.5.1. Representation 1678 The payload of requests or of responses indicating success is 1679 typically a representation of a resource or the result of the 1680 requested action. Its format is specified by the Internet media type 1681 and content coding given by the Content-Format Option. In the 1682 absence of this option, no default value is assumed and the format 1683 will need to be inferred by the application (e.g., from the 1684 application context or by "sniffing" the payload). 1686 Implementation Note: On a quality of implementation level, there is 1687 a strong expectation that a Content-Format indication will be 1688 provided with resource representations whenever possible. This is 1689 not a "SHOULD"-level requirement solely because it is not a 1690 protocol requirement, and it also would be difficult to outline 1691 exactly in what cases this expectation can be violated. 1693 For responses indicating a client or server error, the payload is 1694 considered a representation of the result of the requested action 1695 only if a Content-Format Option is given. In the absence of this 1696 option, the payload is a Diagnostic Payload ({{diagnostic-message- 1697 payload}}). 1699 5.5.2. Diagnostic Payload 1701 If no Content-Format option is given, the payload of responses 1702 indicating a client or server error is a brief human-readable 1703 diagnostic message, explaining the error situation. This diagnostic 1704 message MUST be encoded using UTF-8 [RFC3629], more specifically 1705 using Net-Unicode form [RFC5198]. 1707 The message is similar to the Reason-Phrase on an HTTP status line. 1708 It is not intended for end-users but for software engineers that 1709 during debugging need to interpret it in the context of the present, 1710 English-language specification; therefore no mechanism for language 1711 tagging is needed or provided. In contrast to what is usual in HTTP, 1712 the payload SHOULD be empty if there is no additional information 1713 beyond the response code. 1715 5.5.3. Selected Representation 1717 Not all responses carry a payload that provides a representation of 1718 the resource addressed by the request. It is, however, sometimes 1719 useful to be able to refer to such a representation in relation to a 1720 response, independent of whether it actually was enclosed. 1722 We use the term "selected representation"" to refer to the current 1723 representation of a target resource that would have been selected in 1724 a successful response if the corresponding request had used the 1725 method GET and excluded any conditional request options 1726 (Section 5.10.8). 1728 Certain response options provide metadata about the selected 1729 representation, which might differ from the representation included 1730 in the message for responses to some state-changing methods. Of the 1731 response options defined in this specification, only the ETag 1732 response option (Section 5.10.6) is defined as selected 1733 representation metadata. 1735 5.5.4. Content Negotiation 1737 A server may be able to supply a representation for a resource in one 1738 of multiple representation formats. Without further information from 1739 the client, it will provide the representation in the format it 1740 prefers. 1742 By using one or more instances of the Accept Option (Section 5.10.4) 1743 in a request, the client can indicate which content-formats it 1744 prefers to receive and provide a preference ranking between these 1745 content-formats. 1747 5.6. Caching 1749 CoAP endpoints MAY cache responses in order to reduce the response 1750 time and network bandwidth consumption on future, equivalent 1751 requests. 1753 The goal of caching in CoAP is to reuse a prior response message to 1754 satisfy a current request. In some cases, a stored response can be 1755 reused without the need for a network request, reducing latency and 1756 network round-trips; a "freshness" mechanism is used for this purpose 1757 (see Section 5.6.1). Even when a new request is required, it is 1758 often possible to reuse the payload of a prior response to satisfy 1759 the request, thereby reducing network bandwidth usage; a "validation" 1760 mechanism is used for this purpose (see Section 5.6.2). 1762 Unlike HTTP, the cacheability of CoAP responses does not depend on 1763 the request method, but the Response Code. The cacheability of each 1764 Response Code is defined along the Response Code definitions in 1765 Section 5.9. Response Codes that indicate success and are 1766 unrecognized by an endpoint MUST NOT be cached. 1768 For a presented request, a CoAP endpoint MUST NOT use a stored 1769 response, unless: 1771 o the presented request method and that used to obtain the stored 1772 response match, 1774 o all options match between those in the presented request and those 1775 of the request used to obtain the stored response (which includes 1776 the request URI), except that there is no need for a match of any 1777 request options marked as NoCacheKey (Section 5.4) or recognized 1778 by the Cache and fully interpreted with respect to its specified 1779 cache behavior (such as the ETag request option, Section 5.10.6, 1780 see also Section 5.4.2), and 1782 o the stored response is either fresh or successfully validated as 1783 defined below. 1785 5.6.1. Freshness Model 1787 When a response is "fresh" in the cache, it can be used to satisfy 1788 subsequent requests without contacting the origin server, thereby 1789 improving efficiency. 1791 The mechanism for determining freshness is for an origin server to 1792 provide an explicit expiration time in the future, using the Max-Age 1793 Option (see Section 5.10.5). The Max-Age Option indicates that the 1794 response is to be considered not fresh after its age is greater than 1795 the specified number of seconds. 1797 The Max-Age Option defaults to a value of 60. Thus, if it is not 1798 present in a cacheable response, then the response is considered not 1799 fresh after its age is greater than 60 seconds. If an origin server 1800 wishes to prevent caching, it MUST explicitly include a Max-Age 1801 Option with a value of zero seconds. 1803 If a client has a fresh stored response and makes a new request 1804 matching the request for that stored response, the new response 1805 invalidates the old response. 1807 5.6.2. Validation Model 1809 When an endpoint has one or more stored responses for a GET request, 1810 but cannot use any of them (e.g., because they are not fresh), it can 1811 use the ETag Option (Section 5.10.6) in the GET request to give the 1812 origin server an opportunity to both select a stored response to be 1813 used, and to update its freshness. This process is known as 1814 "validating" or "revalidating" the stored response. 1816 When sending such a request, the endpoint SHOULD add an ETag Option 1817 specifying the entity-tag of each stored response that is applicable. 1819 A 2.03 (Valid) response indicates the stored response identified by 1820 the entity-tag given in the response's ETag Option can be reused, 1821 after updating its freshness with the value of the Max-Age Option 1822 that is included (explicitly, or implicitly as a default value) with 1823 the response (see Section 5.9.1.3). 1825 Any other response code indicates that none of the stored responses 1826 nominated in the request is suitable. Instead, the response SHOULD 1827 be used to satisfy the request and MAY replace the stored response. 1829 5.7. Proxying 1831 A proxy is a CoAP endpoint that can be tasked by CoAP clients to 1832 perform requests on their behalf. This may be useful, for example, 1833 when the request could otherwise not be made, or to service the 1834 response from a cache in order to reduce response time and network 1835 bandwidth or energy consumption. 1837 In an overall architecture for a Constrained RESTful Environment, 1838 proxies can serve quite different purposes. Proxies can be 1839 explicitly selected by clients, a role that we term "forward-proxy". 1840 Proxies can also be inserted to stand in for origin servers, a role 1841 that we term "reverse-proxy". Orthogonal to this distinction, a 1842 proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP 1843 proxy) or translate from or to a different protocol ("cross-proxy"). 1844 Full definitions of these terms are provided in Section 1.2. 1846 Notes: The terminology in this specification has been selected to be 1847 culturally compatible with the terminology used in the wider Web 1848 application environments, without necessarily matching it in every 1849 detail (which may not even be relevant to Constrained RESTful 1850 Environments). Not too much semantics should be ascribed to the 1851 components of the terms (such as "forward", "reverse", or 1852 "cross"). 1854 HTTP proxies, besides acting as HTTP proxies, often offer a 1855 transport protocol proxying function ("CONNECT") to enable end-to- 1856 end transport layer security through the proxy. No such function 1857 is defined for CoAP-to-CoAP proxies in this specification, as 1858 forwarding of UDP packets is unlikely to be of much value in 1859 Constrained RESTful environments. See also Section 10.2.7 for the 1860 cross-proxy case. 1862 5.7.1. Proxy Operation 1864 A proxy generally needs a way to determine potential request 1865 parameters for a request to a destination based on the request it 1866 received. This way is fully specified for a forward-proxy, but may 1867 depend on the specific configuration for a reverse-proxy. In 1868 particular, the client of a reverse-proxy generally does not indicate 1869 a locator for the destination, necessitating some form of namespace 1870 translation in the reverse-proxy. However, some aspects of the 1871 operation of proxies are common to all its forms. 1873 If a proxy does not employ a cache, then it simply forwards the 1874 translated request to the determined destination. Otherwise, if it 1875 does employ a cache but does not have a stored response that matches 1876 the translated request and is considered fresh, then it needs to 1877 refresh its cache according to Section 5.6. For options in the 1878 request that the proxy recognizes, it knows whether the option is 1879 intended to act as part of the key used in looking up the cached 1880 value or not. E.g., since requests for different Uri-Path values 1881 address different resources, Uri-Path values are always parts of the 1882 cache key, while, e.g., Token values are never part of the cache key. 1883 For options that the proxy does not recognize but that are marked 1884 Safe in the option number, the option also indicates whether it is to 1885 be included in the cache key (NoCacheKey is not all set) or not 1886 (NoCacheKey is all set). (Options that are unrecognized and marked 1887 Unsafe lead to 4.02 Bad Option.) 1889 If the request to the destination times out, then a 5.04 (Gateway 1890 Timeout) response MUST be returned. If the request to the 1891 destination returns a response that cannot be processed by the proxy 1892 (e.g, due to unrecognized critical options, message format errors), 1893 then a 5.02 (Bad Gateway) response MUST be returned. Otherwise, the 1894 proxy returns the response to the client. 1896 If a response is generated out of a cache, it MUST be generated with 1897 a Max-Age Option that does not extend the max-age originally set by 1898 the server, considering the time the resource representation spent in 1899 the cache. E.g., the Max-Age Option could be adjusted by the proxy 1900 for each response using the formula: 1902 proxy-max-age = original-max-age - cache-age 1904 For example if a request is made to a proxied resource that was 1905 refreshed 20 seconds ago and had an original Max-Age of 60 seconds, 1906 then that resource's proxied max-age is now 40 seconds. Considering 1907 potential network delays on the way from the origin server, a proxy 1908 SHOULD be conservative in the max-age values offered. 1910 All options present in a proxy request MUST be processed at the 1911 proxy. Unsafe options in a request that are not recognized by the 1912 proxy MUST lead to a 4.02 (Bad Option) response being returned by the 1913 proxy. A CoAP-to-CoAP proxy MUST forward to the origin server all 1914 Safe options that it does not recognize. Similarly, Unsafe options 1915 in a response that are not recognized by the CoAP-to-CoAP proxy 1916 server MUST lead to a 5.02 (Bad Gateway) response. Again, Safe 1917 options that are not recognized MUST be forwarded. 1919 Additional considerations for cross-protocol proxying between CoAP 1920 and HTTP are discussed in Section 10. 1922 5.7.2. Forward-Proxies 1924 CoAP distinguishes between requests made (as if) to an origin server 1925 and a request made through a forward-proxy. CoAP requests to a 1926 forward-proxy are made as normal confirmable or non-confirmable 1927 requests to the forward-proxy endpoint, but specify the request URI 1928 in a different way: The request URI in a proxy request is specified 1929 as a string in the Proxy-Uri Option (see Section 5.10.2), while the 1930 request URI in a request to an origin server is split into the Uri- 1931 Host, Uri-Port, Uri-Path and Uri-Query Options (see Section 5.10.1); 1932 alternatively the URI in a proxy request can be assembled from a 1933 Proxy-Scheme option and the split options mentioned. 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.2), 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 or 1950 Proxy-Scheme option, which is therefore not forwarded to the origin 1951 server. 1953 5.7.3. Reverse-Proxies 1955 Reverse-proxies do not make use of the Proxy-Uri or Proxy-Scheme 1956 options, but need to determine the destination (next hop) of a 1957 request from information in the request and information in their 1958 configuration. E.g., a reverse-proxy might offer various resources 1959 the existence of which it has learned through resource discovery as 1960 if they were its own resources. The reverse-proxy is free to build a 1961 namespace for the URIs that identify these resources. A reverse- 1962 proxy may also build a namespace that gives the client more control 1963 over where the request goes, e.g. by embedding host identifiers and 1964 port numbers into the URI path of the resources offered. 1966 In processing the response, a reverse-proxy has to be careful about 1967 namespacing the ETag option. In many cases, it can be forwarded 1968 unchanged. If the mapping from a resource offered by the reverse- 1969 proxy to resources offered by its various origin servers is not 1970 unique, the reverse-proxy may need to generate a new ETag, making 1971 sure the semantics of this option are properly preserved. 1973 5.8. Method Definitions 1975 In this section each method is defined along with its behavior. A 1976 request with an unrecognized or unsupported Method Code MUST generate 1977 a 4.05 (Method Not Allowed) piggy-backed response. 1979 5.8.1. GET 1981 The GET method retrieves a representation for the information that 1982 currently corresponds to the resource identified by the request URI. 1983 If the request includes one or more Accept Options, they indicate the 1984 preferred content-format of a response. If the request includes an 1985 ETag Option, the GET method requests that ETag be validated and that 1986 the representation be transferred only if validation failed. Upon 1987 success a 2.05 (Content) or 2.03 (Valid) response code SHOULD be 1988 present in the response. 1990 The GET method is safe and idempotent. 1992 5.8.2. POST 1994 The POST method requests that the representation enclosed in the 1995 request be processed. The actual function performed by the POST 1996 method is determined by the origin server and dependent on the target 1997 resource. It usually results in a new resource being created or the 1998 target resource being updated. 2000 If a resource has been created on the server, the response returned 2001 by the server SHOULD have a 2.01 (Created) response code and SHOULD 2002 include the URI of the new resource in a sequence of one or more 2003 Location-Path and/or Location-Query Options (Section 5.10.7). If the 2004 POST succeeds but does not result in a new resource being created on 2005 the server, the response SHOULD have a 2.04 (Changed) response code. 2006 If the POST succeeds and results in the target resource being 2007 deleted, the response SHOULD have a 2.02 (Deleted) response code. 2009 POST is neither safe nor idempotent. 2011 5.8.3. PUT 2013 The PUT method requests that the resource identified by the request 2014 URI be updated or created with the enclosed representation. The 2015 representation format is specified by the media type and content 2016 coding given in the Content-Format Option, if provided. 2018 If a resource exists at the request URI the enclosed representation 2019 SHOULD be considered a modified version of that resource, and a 2.04 2020 (Changed) response code SHOULD be returned. If no resource exists 2021 then the server MAY create a new resource with that URI, resulting in 2022 a 2.01 (Created) response code. If the resource could not be created 2023 or modified, then an appropriate error response code SHOULD be sent. 2025 Further restrictions to a PUT can be made by including the If-Match 2026 (see Section 5.10.8.1) or If-None-Match (see Section 5.10.8.2) 2027 options in the request. 2029 PUT is not safe, but is idempotent. 2031 5.8.4. DELETE 2033 The DELETE method requests that the resource identified by the 2034 request URI be deleted. A 2.02 (Deleted) response code SHOULD be 2035 used on success or in case the resource did not exist before the 2036 request. 2038 DELETE is not safe, but is idempotent. 2040 5.9. Response Code Definitions 2042 Each response code is described below, including any options required 2043 in the response. Where appropriate, some of the codes will be 2044 specified in regards to related response codes in HTTP [RFC2616]; 2045 this does not mean that any such relationship modifies the HTTP 2046 mapping specified in Section 10. 2048 5.9.1. Success 2.xx 2050 This class of status code indicates that the clients request was 2051 successfully received, understood, and accepted. 2053 5.9.1.1. 2.01 Created 2055 Like HTTP 201 "Created", but only used in response to POST and PUT 2056 requests. The payload returned with the response, if any, is a 2057 representation of the action result. 2059 If the response includes one or more Location-Path and/or Location- 2060 Query Options, the values of these options specify the location at 2061 which the resource was created. Otherwise, the resource was created 2062 at the request URI. A cache receiving this response MUST mark any 2063 stored response for the created resource as not fresh. 2065 This response is not cacheable. 2067 5.9.1.2. 2.02 Deleted 2069 Like HTTP 204 "No Content", but only used in response to DELETE 2070 requests. The payload returned with the response, if any, is a 2071 representation of the action result. 2073 This response is not cacheable. However, a cache MUST mark any 2074 stored response for the deleted resource as not fresh. 2076 5.9.1.3. 2.03 Valid 2078 Related to HTTP 304 "Not Modified", but only used to indicate that 2079 the response identified by the entity-tag identified by the included 2080 ETag Option is valid. Accordingly, the response MUST include an ETag 2081 Option, and MUST NOT include a payload. 2083 When a cache that recognizes and processes the ETag response option 2084 receives a 2.03 (Valid) response, it MUST update the stored response 2085 with the value of the Max-Age Option included in the response (see 2086 Section 5.6.2). 2088 5.9.1.4. 2.04 Changed 2090 Like HTTP 204 "No Content", but only used in response to POST and PUT 2091 requests. The payload returned with the response, if any, is a 2092 representation of the action result. 2094 This response is not cacheable. However, a cache MUST mark any 2095 stored response for the changed resource as not fresh. 2097 5.9.1.5. 2.05 Content 2099 Like HTTP 200 "OK", but only used in response to GET requests. 2101 The payload returned with the response is a representation of the 2102 target resource. 2104 This response is cacheable: Caches can use the Max-Age Option to 2105 determine freshness (see Section 5.6.1) and (if present) the ETag 2106 Option for validation (see Section 5.6.2). 2108 5.9.2. Client Error 4.xx 2110 This class of response code is intended for cases in which the client 2111 seems to have erred. These response codes are applicable to any 2112 request method. 2114 The server SHOULD include a diagnostic payload under the conditions 2115 detailed in Section 5.5.2. 2117 Responses of this class are cacheable: Caches can use the Max-Age 2118 Option to determine freshness (see Section 5.6.1). They cannot be 2119 validated. 2121 5.9.2.1. 4.00 Bad Request 2123 Like HTTP 400 "Bad Request". 2125 5.9.2.2. 4.01 Unauthorized 2127 The client is not authorized to perform the requested action. The 2128 client SHOULD NOT repeat the request without previously improving its 2129 authentication status to the server. Which specific mechanism can be 2130 used for this is outside this document's scope; see also Section 9. 2132 5.9.2.3. 4.02 Bad Option 2134 The request could not be understood by the server due to one or more 2135 unrecognized or malformed options. The client SHOULD NOT repeat the 2136 request without modification. 2138 5.9.2.4. 4.03 Forbidden 2140 Like HTTP 403 "Forbidden". 2142 5.9.2.5. 4.04 Not Found 2144 Like HTTP 404 "Not Found". 2146 5.9.2.6. 4.05 Method Not Allowed 2148 Like HTTP 405 "Method Not Allowed", but with no parallel to the 2149 "Allow" header field. 2151 5.9.2.7. 4.06 Not Acceptable 2153 Like HTTP 406 "Not Acceptable", but with no response entity. 2155 5.9.2.8. 4.12 Precondition Failed 2157 Like HTTP 412 "Precondition Failed". 2159 5.9.2.9. 4.13 Request Entity Too Large 2161 Like HTTP 413 "Request Entity Too Large". 2163 5.9.2.10. 4.15 Unsupported Content-Format 2165 Like HTTP 415 "Unsupported Media Type". 2167 5.9.3. Server Error 5.xx 2169 This class of response code indicates cases in which the server is 2170 aware that it has erred or is incapable of performing the request. 2171 These response codes are applicable to any request method. 2173 The server SHOULD include a diagnostic payload under the conditions 2174 detailed in Section 5.5.2. 2176 Responses of this class are cacheable: Caches can use the Max-Age 2177 Option to determine freshness (see Section 5.6.1). They cannot be 2178 validated. 2180 5.9.3.1. 5.00 Internal Server Error 2182 Like HTTP 500 "Internal Server Error". 2184 5.9.3.2. 5.01 Not Implemented 2186 Like HTTP 501 "Not Implemented". 2188 5.9.3.3. 5.02 Bad Gateway 2190 Like HTTP 502 "Bad Gateway". 2192 5.9.3.4. 5.03 Service Unavailable 2194 Like HTTP 503 "Service Unavailable", but using the Max-Age Option in 2195 place of the "Retry-After" header field to indicate the number of 2196 seconds after which to retry. 2198 5.9.3.5. 5.04 Gateway Timeout 2200 Like HTTP 504 "Gateway Timeout". 2202 5.9.3.6. 5.05 Proxying Not Supported 2204 The server is unable or unwilling to act as a forward-proxy for the 2205 URI specified in the Proxy-Uri Option or using Proxy-Scheme (see 2206 Section 5.10.2). 2208 5.10. Option Definitions 2210 The individual CoAP options are summarized in Table 1 and explained 2211 below. 2213 +-----+---+---+---+---+----------------+--------+--------+----------+ 2214 | No. | C | U | N | R | Name | Format | Length | Default | 2215 +-----+---+---+---+---+----------------+--------+--------+----------+ 2216 | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | 2217 | 3 | x | x | - | | Uri-Host | string | 1-255 | (see | 2218 | | | | | | | | | below) | 2219 | 4 | | | | x | ETag | opaque | 1-8 | (none) | 2220 | 5 | x | | | | If-None-Match | empty | 0 | (none) | 2221 | 7 | x | x | - | | Uri-Port | uint | 0-2 | (see | 2222 | | | | | | | | | below) | 2223 | 8 | | | | x | Location-Path | string | 0-255 | (none) | 2224 | 11 | x | x | - | x | Uri-Path | string | 0-255 | (none) | 2225 | 12 | | | | | Content-Format | uint | 0-2 | (none) | 2226 | 14 | | x | - | | Max-Age | uint | 0-4 | 60 | 2227 | 15 | x | x | - | x | Uri-Query | string | 0-255 | (none) | 2228 | 16 | | | | x | Accept | uint | 0-2 | (none) | 2229 | 20 | | | | x | Location-Query | string | 0-255 | (none) | 2230 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | (none) | 2231 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | (none) | 2232 +-----+---+---+---+---+----------------+--------+--------+----------+ 2234 C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable 2236 Table 1: Options 2238 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query 2240 The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to 2241 specify the target resource of a request to a CoAP origin server. 2242 The options encode the different components of the request URI in a 2243 way that no percent-encoding is visible in the option values and that 2244 the full URI can be reconstructed at any involved endpoint. The 2245 syntax of CoAP URIs is defined in Section 6. 2247 The steps for parsing URIs into options is defined in Section 6.4. 2248 These steps result in zero or more Uri-Host, Uri-Port, Uri-Path and 2249 Uri-Query Options being included in a request, where each option 2250 holds the following values: 2252 o the Uri-Host Option specifies the Internet host of the resource 2253 being requested, 2255 o the Uri-Port Option specifies the transport layer port number of 2256 the resource, 2258 o each Uri-Path Option specifies one segment of the absolute path to 2259 the resource, and 2261 o each Uri-Query Option specifies one argument parameterizing the 2262 resource. 2264 Note: Fragments ([RFC3986], Section 3.5) are not part of the request 2265 URI and thus will not be transmitted in a CoAP request. 2267 The default value of the Uri-Host Option is the IP literal 2268 representing the destination IP address of the request message. 2269 Likewise, the default value of the Uri-Port Option is the destination 2270 UDP port. The default values for the Uri-Host and Uri-Port Options 2271 are sufficient for requests to most servers. Explicit Uri-Host and 2272 Uri-Port Options are typically used when an endpoint hosts multiple 2273 virtual servers. 2275 The Uri-Path and Uri-Query Option can contain any character sequence. 2276 No percent-encoding is performed. The value of a Uri-Path Option 2277 MUST NOT be "." or ".." (as the request URI must be resolved before 2278 parsing it into options). 2280 The steps for constructing the request URI from the options are 2281 defined in Section 6.5. Note that an implementation does not 2282 necessarily have to construct the URI; it can simply look up the 2283 target resource by looking at the individual options. 2285 Examples can be found in Appendix B. 2287 5.10.2. Proxy-Uri and Proxy-Scheme 2289 The Proxy-Uri Option is used to make a request to a forward-proxy 2290 (see Section 5.7). The forward-proxy is requested to forward the 2291 request or service it from a valid cache, and return the response. 2293 The option value is an absolute-URI ([RFC3986], Section 4.3). 2295 Note that the forward-proxy MAY forward the request on to another 2296 proxy or directly to the server specified by the absolute-URI. In 2297 order to avoid request loops, a proxy MUST be able to recognize all 2298 of its server names, including any aliases, local variations, and the 2299 numeric IP addresses. 2301 An endpoint receiving a request with a Proxy-Uri Option that is 2302 unable or unwilling to act as a forward-proxy for the request MUST 2303 cause the return of a 5.05 (Proxying Not Supported) response. 2305 The Proxy-Uri Option MUST take precedence over any of the Uri-Host, 2306 Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included 2307 at the same time in a request containing the Proxy-Uri Option). 2309 As a special case to simplify many proxy clients, the absolute-URI 2310 can be constructed from the Uri-* options. When a Proxy-Scheme 2311 Option is present, the absolute-URI is constructed as follows: A CoAP 2312 URI is constructed from the Uri-* options as defined in Section 6.5. 2313 In the resulting URI, the initial scheme up to, but not including the 2314 following colon is then replaced by the content of the Proxy-Scheme 2315 Option. 2317 5.10.3. Content-Format 2319 The Content-Format Option indicates the representation format of the 2320 message payload. The representation format is given as a numeric 2321 content format identifier that is defined in the CoAP Content Format 2322 registry (Section 12.3). In the absence of the option, no default 2323 value is assumed, i.e. the representation format of any 2324 representation message payload is indeterminate (Section 5.5). 2326 5.10.4. Accept 2328 The CoAP Accept option indicates when included one or more times in a 2329 request, one or more Content-Formats, each of which is an acceptable 2330 Content-Format for the client, in the order of preference (most 2331 preferred first). The representation format is given as a numeric 2332 Content-Format identifier that is defined in the CoAP Content-Format 2333 registry (Section 12.3). If no Accept options are given, the client 2334 does not express a preference (thus no default value is assumed). 2335 The client prefers the representation returned by the server to be in 2336 one of the Content-Formats indicated. The server SHOULD return one 2337 of the preferred Content-Formats if available. If none of the 2338 preferred Content-Formats can be returned, then a 4.06 "Not 2339 Acceptable" SHOULD be sent as a response. 2341 Note that as a server might not support the Accept option (and thus 2342 would ignore it as it is elective), the client needs to be prepared 2343 to receive a representation in a different Content-Format. The 2344 client can simply discard a representation it can not make use of. 2346 5.10.5. Max-Age 2348 The Max-Age Option indicates the maximum time a response may be 2349 cached before it MUST be considered not fresh (see Section 5.6.1). 2351 The option value is an integer number of seconds between 0 and 2352 2**32-1 inclusive (about 136.1 years). A default value of 60 seconds 2353 is assumed in the absence of the option in a response. 2355 The value is intended to be current at the time of transmission. 2356 Servers that provide resources with strict tolerances on the value of 2357 Max-Age SHOULD update the value before each retransmission. (See 2358 also Section 5.7.1.) 2360 5.10.6. ETag 2362 An entity-tag is intended for use as a resource-local identifier for 2363 differentiating between representations of the same resource that 2364 vary over time. It is generated by the server providing the 2365 resource, which may generate it in any number of ways including a 2366 version, checksum, hash or time. An endpoint receiving an entity-tag 2367 MUST treat it as opaque and make no assumptions about its format. 2368 (Endpoints that generate an entity-tag are encouraged to use the most 2369 compact representation possible, in particular in regards to clients 2370 and intermediaries that may want to store multiple ETag values.) 2372 5.10.6.1. ETag as a Response Option 2374 The ETag Option in a response provides the current value (i.e., after 2375 the request was processed) of the entity-tag for the "tagged 2376 representation". If no Location-* options are present, the tagged 2377 representation is the selected representation (Section 5.5.3) of the 2378 target resource. If one or more Location-* options are present and 2379 thus a location URI is indicated (Section 5.10.7), the tagged 2380 representation is the representation that would be retried by a GET 2381 request to the location URI. 2383 An ETag response option can be included with any response for which 2384 there is a tagged representation (e.g., it would not be meaningful in 2385 a 4.04 or 4.00 response). The ETag Option MUST NOT occur more than 2386 once in a response. 2388 There is no default value for the ETag Option; if it is not present 2389 in a response, the server makes no statement about the entity-tag for 2390 the tagged representation. 2392 5.10.6.2. ETag as a Request Option 2394 In a GET request, an endpoint that has one or more representations 2395 previously obtained from the resource, and has obtained ETag response 2396 options with these, can specify an instance of the ETag Option for 2397 one or more of these stored responses. 2399 A server can issue a 2.03 Valid response (Section 5.9.1.3) in place 2400 of a 2.05 Content response if one of the ETags given is the entity- 2401 tag for the current representation, i.e. is valid; the 2.03 Valid 2402 response then echoes this specific ETag in a response option. 2404 In effect, a client can determine if any of the stored 2405 representations is current (see Section 5.6.2) without needing to 2406 transfer them again. 2408 The ETag Option MAY occur zero, one or more times in a request. 2410 5.10.7. Location-Path and Location-Query 2412 The Location-Path and Location-Query Options together indicate a 2413 relative URI that consists either of an absolute path, a query string 2414 or both. A combination of these options is included in a 2.01 2415 (Created) response to indicate the location of the resource created 2416 as the result of a POST request (see Section 5.8.2). The location is 2417 resolved relative to the request URI. 2419 If a response with one or more Location-Path and/or Location-Query 2420 Options passes through a cache that interprets these options and the 2421 implied URI identifies one or more currently stored responses, those 2422 entries MUST be marked as not fresh. 2424 Each Location-Path Option specifies one segment of the absolute path 2425 to the resource, and each Location-Query Option specifies one 2426 argument parameterizing the resource. The Location-Path and 2427 Location-Query Option can contain any character sequence. No 2428 percent-encoding is performed. The value of a Location-Path Option 2429 MUST NOT be "." or "..". 2431 The steps for constructing the location URI from the options are 2432 analogous to Section 6.5, except that the first five steps are 2433 skipped and the result is a relative URI-reference, which is then 2434 interpreted relative to the request URI. Note that the relative URI- 2435 reference constructed this way always includes an absolute-path 2436 (e.g., leaving out Location-Path but supplying Location-Query means 2437 the path component in the URI is "/"). 2439 The options that are used to compute the relative URI-reference are 2440 collectively called Location-* options. Beyond Location-Path and 2441 Location-Query, more Location-* options may be defined in the future, 2442 and have been reserved option numbers 128, 132, 136, and 140. If any 2443 of these reserved option numbers occurs in addition to Location-Path 2444 and/or Location-Query and are not supported, then a 4.02 (Bad Option) 2445 error MUST be returned. 2447 5.10.8. Conditional Request Options 2449 Conditional request options enable a client to ask the server to 2450 perform the request only if certain conditions specified by the 2451 option are fulfilled. 2453 For each of these options, if the condition given is not fulfilled, 2454 then the the server MUST NOT perform the requested method. Instead, 2455 the server MUST respond with the 4.12 (Precondition Failed) response 2456 code. 2458 If the condition is fulfilled, the server performs the request method 2459 as if the conditional request options were not present. 2461 If the request would, without the conditional request options, result 2462 in anything other than a 2.xx or 4.12 response code, then any 2463 conditional request options MAY be ignored. 2465 5.10.8.1. If-Match 2467 The If-Match Option MAY be used to make a request conditional on the 2468 current existence or value of an ETag for one or more representations 2469 of the target resource. If-Match is generally useful for resource 2470 update requests, such as PUT requests, as a means for protecting 2471 against accidental overwrites when multiple clients are acting in 2472 parallel on the same resource (i.e., the "lost update" problem). 2474 The value of an If-Match option is either an ETag or the empty 2475 string. An If-Match option with an ETag matches a representation 2476 with that exact ETag. An If-Match option with an empty value matches 2477 any existing representation (i.e., it places the precondition on the 2478 existence of any current representation for the target resource). 2480 The If-Match Option can occur multiple times. If any of the options 2481 match, then the condition is fulfilled. 2483 If there is one or more If-Match Option, but none of the options 2484 match, then the condition is not fulfilled. 2486 5.10.8.2. If-None-Match 2488 The If-None-Match Option MAY be used to make a request conditional on 2489 the non-existence of the target resource. If-None-Match is useful 2490 for resource creation requests, such as PUT requests, as a means for 2491 protecting against accidental overwrites when multiple clients are 2492 acting in parallel on the same resource. The If-None-Match Option 2493 carries no value. 2495 If the target resource does exist, then the condition is not 2496 fulfilled. 2498 6. CoAP URIs 2500 CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP 2501 resources and providing a means of locating the resource. Resources 2502 are organized hierarchically and governed by a potential CoAP origin 2503 server listening for CoAP requests ("coap") or DTLS-secured CoAP 2504 requests ("coaps") on a given UDP port. The CoAP server is 2505 identified via the generic syntax's authority component, which 2506 includes a host component and optional UDP port number. The 2507 remainder of the URI is considered to be identifying a resource which 2508 can be operated on by the methods defined by the CoAP protocol. The 2509 "coap" and "coaps" URI schemes can thus be compared to the "http" and 2510 "https" URI schemes respectively. 2512 The syntax of the "coap" and "coaps" URI schemes is specified below 2513 in Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 2514 "host", "port", "path-abempty", "query", "segment", "IP-literal", 2515 "IPv4address" and "reg-name" are adopted from [RFC3986]. 2517 Implementation Note: Unfortunately, over time the URI format has 2518 acquired significant complexity. Implementers are encouraged to 2519 examine [RFC3986] closely. E.g., the ABNF for IPv6 addresses is 2520 more complicated than maybe expected. Also, implementers should 2521 take care to perform the processing of percent decoding/encoding 2522 exactly once on the way from a URI to its decoded components or 2523 back. Percent encoding is crucial for data transparency, but may 2524 lead to unusual results such as a slash in a path component. 2526 6.1. coap URI Scheme 2528 coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] 2530 If the host component is provided as an IP-literal or IPv4address, 2531 then the CoAP server can be reached at that IP address. If host is a 2532 registered name, then that name is considered an indirect identifier 2533 and the endpoint might use a name resolution service, such as DNS, to 2534 find the address of that host. The host MUST NOT be empty; if a URI 2535 is received with a missing authority or an empty host, then it MUST 2536 be considered invalid. The port subcomponent indicates the UDP port 2537 at which the CoAP server is located. If it is empty or not given, 2538 then the default port 5683 is assumed. 2540 The path identifies a resource within the scope of the host and port. 2541 It consists of a sequence of path segments separated by a slash 2542 character (U+002F SOLIDUS "/"). 2544 The query serves to further parameterize the resource. It consists 2545 of a sequence of arguments separated by an ampersand character 2546 (U+0026 AMPERSAND "&"). An argument is often in the form of a 2547 "key=value" pair. 2549 The "coap" URI scheme supports the path prefix "/.well-known/" 2550 defined by [RFC5785] for "well-known locations" in the name-space of 2551 a host. This enables discovery of policy or other information about 2552 a host ("site-wide metadata"), such as hosted resources (see 2553 Section 7). 2555 Application designers are encouraged to make use of short, but 2556 descriptive URIs. As the environments that CoAP is used in are 2557 usually constrained for bandwidth and energy, the trade-off between 2558 these two qualities should lean towards the shortness, without 2559 ignoring descriptiveness. 2561 6.2. coaps URI Scheme 2563 coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty 2564 [ "?" query ] 2566 All of the requirements listed above for the "coap" scheme are also 2567 requirements for the "coaps" scheme, except that a default UDP port 2568 of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or 2569 not given, and the UDP datagrams MUST be secured for privacy through 2570 the use of DTLS as described in Section 9.1. 2572 Considerations for caching of responses to "coaps" identified 2573 requests are discussed in Section 11.2. 2575 Resources made available via the "coaps" scheme have no shared 2576 identity with the "coap" scheme even if their resource identifiers 2577 indicate the same authority (the same host listening to the same UDP 2578 port). They are distinct name spaces and are considered to be 2579 distinct origin servers. 2581 6.3. Normalization and Comparison Rules 2583 Since the "coap" and "coaps" schemes conform to the URI generic 2584 syntax, such URIs are normalized and compared according to the 2585 algorithm defined in [RFC3986], Section 6, using the defaults 2586 described above for each scheme. 2588 If the port is equal to the default port for a scheme, the normal 2589 form is to elide the port subcomponent. Likewise, an empty path 2590 component is equivalent to an absolute path of "/", so the normal 2591 form is to provide a path of "/" instead. The scheme and host are 2592 case-insensitive and normally provided in lowercase; IP-literals are 2593 in recommended form [RFC5952]; all other components are compared in a 2594 case-sensitive manner. Characters other than those in the "reserved" 2595 set are equivalent to their percent-encoded octets (see [RFC3986], 2596 Section 2.1): the normal form is to not encode them. 2598 For example, the following three URIs are equivalent, and cause the 2599 same options and option values to appear in the CoAP messages: 2601 coap://example.com:5683/~sensors/temp.xml 2602 coap://EXAMPLE.com/%7Esensors/temp.xml 2603 coap://EXAMPLE.com:/%7esensors/temp.xml 2605 6.4. Decomposing URIs into Options 2607 The steps to parse a request's options from a string /url/ are as 2608 follows. These steps either result in zero or more of the Uri-Host, 2609 Uri-Port, Uri-Path and Uri-Query Options being included in the 2610 request, or they fail. 2612 1. If the /url/ string is not an absolute URI ([RFC3986]), then fail 2613 this algorithm. 2615 2. Resolve the /url/ string using the process of reference 2616 resolution defined by [RFC3986], with the URL character encoding 2617 set to UTF-8 [RFC3629]. 2619 NOTE: It doesn't matter what it is resolved relative to, since we 2620 already know it is an absolute URL at this point. 2622 3. If /url/ does not have a component whose value, when 2623 converted to ASCII lowercase, is "coap" or "coaps", then fail 2624 this algorithm. 2626 4. If /url/ has a component, then fail this algorithm. 2628 5. If the component of /url/ does not represent the request's 2629 destination IP address as an IP-literal or IPv4address, include a 2630 Uri-Host Option and let that option's value be the value of the 2631 component of /url/, converted to ASCII lowercase, and then 2632 converting all percent-encodings ("%" followed by two hexadecimal 2633 digits) to the corresponding characters. 2635 NOTE: In the usual case where the request's destination IP 2636 address is derived from the host part, this ensures that a Uri- 2637 Host Option is only used for a component of the form reg- 2638 name. 2640 6. If /url/ has a component, then let /port/ be that 2641 component's value interpreted as a decimal integer; otherwise, 2642 let /port/ be the default port for the scheme. 2644 7. If /port/ does not equal the request's destination UDP port, 2645 include a Uri-Port Option and let that option's value be /port/. 2647 8. If the value of the component of /url/ is empty or 2648 consists of a single slash character (U+002F SOLIDUS "/"), then 2649 move to the next step. 2651 Otherwise, for each segment in the component, include a 2652 Uri-Path Option and let that option's value be the segment (not 2653 including the delimiting slash characters) after converting all 2654 percent-encodings ("%" followed by two hexadecimal digits) to the 2655 corresponding characters. 2657 9. If /url/ has a component, then, for each argument in the 2658 component, include a Uri-Query Option and let that 2659 option's value be the argument (not including the question mark 2660 and the delimiting ampersand characters) after converting all 2661 percent-encodings to the corresponding characters. 2663 Note that these rules completely resolve any percent-encoding. 2665 6.5. Composing URIs from Options 2667 The steps to construct a URI from a request's options are as follows. 2668 These steps either result in a URI, or they fail. In these steps, 2669 percent-encoding a character means replacing each of its (UTF-8 2670 encoded) bytes by a "%" character followed by two hexadecimal digits 2671 representing the byte, where the digits A-F are in upper case (as 2672 defined in [RFC3986] Section 2.1; to reduce variability, the 2673 hexadecimal notation for percent-encoding in CoAP URIs MUST use 2674 uppercase letters). The definitions of "unreserved" and "sub-delims" 2675 are adopted from [RFC3986]. 2677 1. If the request is secured using DTLS, let /url/ be the string 2678 "coaps://". Otherwise, let /url/ be the string "coap://". 2680 2. If the request includes a Uri-Host Option, let /host/ be that 2681 option's value, where any non-ASCII characters are replaced by 2682 their corresponding percent-encoding. If /host/ is not a valid 2683 reg-name or IP-literal or IPv4address, fail the algorithm. If 2684 the request does not include a Uri-Host Option, let /host/ be 2685 the IP-literal (making use of the conventions of [RFC5952]) or 2686 IPv4address representing the request's destination IP address. 2688 3. Append /host/ to /url/. 2690 4. If the request includes a Uri-Port Option, let /port/ be that 2691 option's value. Otherwise, let /port/ be the request's 2692 destination UDP port. 2694 5. If /port/ is not the default port for the scheme, then append a 2695 single U+003A COLON character (:) followed by the decimal 2696 representation of /port/ to /url/. 2698 6. Let /resource name/ be the empty string. For each Uri-Path 2699 Option in the request, append a single character U+002F SOLIDUS 2700 (/) followed by the option's value to /resource name/, after 2701 converting any character that is not either in the "unreserved" 2702 set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL 2703 AT (@) character, to its percent-encoded form. 2705 7. If /resource name/ is the empty string, set it to a single 2706 character U+002F SOLIDUS (/). 2708 8. For each Uri-Query Option in the request, append a single 2709 character U+003F QUESTION MARK (?) (first option) or U+0026 2710 AMPERSAND (&) (subsequent options) followed by the option's 2711 value to /resource name/, after converting any character that is 2712 not either in the "unreserved" set, "sub-delims" set (except 2713 U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT 2714 (@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, 2715 to its percent-encoded form. 2717 9. Append /resource name/ to /url/. 2719 10. Return /url/. 2721 Note that these steps have been designed to lead to a URI in normal 2722 form (see Section 6.3). 2724 7. Discovery 2726 7.1. Service Discovery 2728 A server is discovered by a client by the client knowing or learning 2729 a URI that references a resource in the namespace of the server. 2730 Alternatively, clients can use Multicast CoAP (see Section 8) and the 2731 "All CoAP Nodes" multicast address to find CoAP servers. 2733 Unless the port subcomponent in a "coap" or "coaps" URI indicates the 2734 UDP port at which the CoAP server is located, the server is assumed 2735 to be reachable at the default port. 2737 The CoAP default port number 5683 MUST be supported by a server that 2738 offers resources for resource discovery (see Section 7.2 below) and 2739 SHOULD be supported for providing access to other resources. The 2740 default port number [IANA_TBD_PORT] for DTLS-secured CoAP MAY be 2741 supported by a server for resource discovery and for providing access 2742 to other resources. In addition other endpoints may be hosted at 2743 other ports, e.g. in the dynamic port space. 2745 Implementation Note: When a CoAP server is hosted by a 6LoWPAN node, 2746 header compression efficiency is improved when it also supports a 2747 port number in the 61616-61631 compressed UDP port space defined 2748 in [RFC4944] (note that, as its UDP port differs from the default 2749 port, it is a different endpoint from the server at the default 2750 port). 2752 7.2. Resource Discovery 2754 The discovery of resources offered by a CoAP endpoint is extremely 2755 important in machine-to-machine applications where there are no 2756 humans in the loop and static interfaces result in fragility. A CoAP 2757 endpoint SHOULD support the CoRE Link Format of discoverable 2758 resources as described in [RFC6690]. It is up to the server which 2759 resources are made discoverable (if any). 2761 7.2.1. 'ct' Attribute 2763 This section defines a new Web Linking [RFC5988] attribute for use 2764 with [RFC6690]. The Content-Format code "ct" attribute provides a 2765 hint about the Content-Formats this resource returns. Note that this 2766 is only a hint, and does not override the Content-Format Option of a 2767 CoAP response obtained by actually requesting the representation of 2768 the resource. The value is in the CoAP identifier code format as a 2769 decimal ASCII integer and MUST be in the range of 0-65535 (16-bit 2770 unsigned integer). For example application/xml would be indicated as 2771 "ct=41". If no Content-Format code attribute is present then nothing 2772 about the type can be assumed. The Content-Format code attribute MAY 2773 include a space-separated sequence of Content-Format codes, 2774 indicating that multiple content-formats are available. The syntax 2775 of the attribute value is summarized in the production ct-value in 2776 Figure 12, where cardinal, SP and DQUOTE are defined as in [RFC6690]. 2778 ct-value = cardinal 2779 / DQUOTE cardinal *( 1*SP cardinal ) DQUOTE 2781 Figure 12 2783 8. Multicast CoAP 2785 CoAP supports making requests to a IP multicast group. This is 2786 defined by a series of deltas to Unicast CoAP. 2788 CoAP endpoints that offer services that they want other endpoints to 2789 be able to find using multicast service discovery, join one or more 2790 of the appropriate all-CoAP-nodes multicast addresses (Section 12.8) 2791 and listen on the default CoAP port. Note that an endpoint might 2792 receive multicast requests on other multicast addresses, including 2793 the all-nodes IPv6 address (or via broadcast on IPv4); an endpoint 2794 MUST therefore be prepared to receive such messages but MAY ignore 2795 them if multicast service discovery is not desired. 2797 8.1. Messaging Layer 2799 A multicast request is characterized by being transported in a CoAP 2800 message that is addressed to an IP multicast address instead of a 2801 CoAP endpoint. Such multicast requests MUST be Non-Confirmable. 2803 A server SHOULD be aware that a request arrived via multicast, e.g. 2804 by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 2805 available. 2807 When a server is aware that a request arrived via multicast, it MUST 2808 NOT return a RST in reply to NON. If it is not aware, it MAY return 2809 a RST in reply to NON as usual. Because such a Reset message will 2810 look identical to an RST for a unicast message from the sender, the 2811 sender MUST avoid using a Message ID that is also still active from 2812 this endpoint with any unicast endpoint that might receive the 2813 multicast message. 2815 8.2. Request/Response Layer 2817 When a server is aware that a request arrived via multicast, the 2818 server MAY always pretend it did not receive the request, in 2819 particular if it doesn't have anything useful to respond (e.g., if it 2820 only has an empty payload or an error response). The decision for 2821 this may depend on the application. (For example, in [RFC6690] query 2822 filtering, a server should not respond to a multicast request if the 2823 filter does not match.) 2825 If a server does decide to respond to a multicast request, it should 2826 not respond immediately. Instead, it should pick a duration for the 2827 period of time during which it intends to respond. For purposes of 2828 this exposition, we call the length of this period the Leisure. The 2829 specific value of this Leisure may depend on the application, or MAY 2830 be derived as described below. The server SHOULD then pick a random 2831 point of time within the chosen Leisure period to send back the 2832 unicast response to the multicast request. If further responses need 2833 to be sent based on the same multicast address membership, a new 2834 leisure period starts at the earliest after the previous one 2835 finishes. 2837 To compute a value for Leisure, the server should have a group size 2838 estimate G, a target data transfer rate R (which both should be 2839 chosen conservatively) and an estimated response size S; a rough 2840 lower bound for Leisure can then be computed as 2841 lb_Leisure = S * G / R 2843 E.g., for a multicast request with link-local scope on an 2.4 GHz 2844 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 2845 conservatively) set to 100, S to 100 bytes, and the target rate to a 2846 conservative 8 kbit/s = 1 kB/s. The resulting lower bound for the 2847 Leisure is 10 seconds. 2849 If a CoAP endpoint does not have suitable data to compute a value for 2850 Leisure, it MAY resort to DEFAULT_LEISURE. 2852 When matching a response to a multicast request, only the token MUST 2853 match; the source endpoint of the response does not need to (and will 2854 not) be the same as the destination endpoint of the original request. 2856 For the purposes of interpreting the Location-* options and any links 2857 embedded in the representation and, the request URI (base URI) 2858 relative to which the response is interpreted, is formed by replacing 2859 the multicast address in the Host component of the original request 2860 URI by the literal IP address of the endpoint actually responding. 2862 8.2.1. Caching 2864 When a client makes a multicast request, it always makes a new 2865 request to the multicast group (since there may be new group members 2866 that joined meanwhile or ones that did not get the previous request). 2867 It MAY update the cache with the received responses. Then it uses 2868 both cached-still-fresh and 'new' responses as the result of the 2869 request. 2871 A response received in reply to a GET request to a multicast group 2872 MAY be used to satisfy a subsequent request on the related unicast 2873 request URI. The unicast request URI is obtained by replacing the 2874 authority part of the request URI with the transport layer source 2875 address of the response message. 2877 A cache MAY revalidate a response by making a GET request on the 2878 related unicast request URI. 2880 A GET request to a multicast group MUST NOT contain an ETag option. 2881 A mechanism to suppress responses the client already has is left for 2882 further study. 2884 8.2.2. Proxying 2886 When a forward-proxy receives a request with a Proxy-Uri or URI 2887 constructed from Proxy-Scheme that indicates a multicast address, the 2888 proxy obtains a set of responses as described above and sends all 2889 responses (both cached-still-fresh and new) back to the original 2890 client. 2892 This specification does not provide a way to indicate the unicast- 2893 modified request URI (base URI) in responses thus forwarded. A 2894 proposal to address this can be found in section 3 of 2895 [I-D.bormann-coap-misc]. 2897 9. Securing CoAP 2899 This section defines the DTLS binding for CoAP. 2901 During the provisioning phase, a CoAP device is provided with the 2902 security information that it needs, including keying materials and 2903 access control lists. This specification defines provisioning for 2904 the RawPublicKey mode in Section 9.1.3.2.1. At the end of the 2905 provisioning phase, the device will be in one of four security modes 2906 with the following information for the given mode. The NoSec and 2907 RawPublicKey modes are mandatory to implement for this specification. 2909 NoSec: There is no protocol level security (DTLS is disabled). 2910 Alternative techniques to provide lower layer security SHOULD be 2911 used when appropriate. The use of IPsec is discussed in 2912 [I-D.bormann-core-ipsec-for-coap]. 2914 PreSharedKey: DTLS is enabled and there is a list of pre-shared keys 2915 [RFC4279] and each key includes a list of which nodes it can be 2916 used to communicate with as described in Section 9.1.3.1. At the 2917 extreme there may be one key for each node this CoAP node needs to 2918 communicate with (1:1 node/key ratio). 2920 RawPublicKey: DTLS is enabled and the device has an asymmetric key 2921 pair without a certificate (a raw public key) that is validated 2922 using an out-of-band mechanism [I-D.ietf-tls-oob-pubkey] as 2923 described in Section 9.1.3.2. The device also has an identity 2924 calculated from the public key and a list of identities of the 2925 nodes it can communicate with. 2927 Certificate: DTLS is enabled and the device has an asymmetric key 2928 pair with an X.509 certificate [RFC5280] that binds it to its 2929 Authority Name and is signed by some common trust root as 2930 described in Section 9.1.3.3. The device also has a list of root 2931 trust anchors that can be used for validating a certificate. 2933 In the "NoSec" mode, the system simply sends the packets over normal 2934 UDP over IP and is indicated by the "coap" scheme and the CoAP 2935 default port. The system is secured only by keeping attackers from 2936 being able to send or receive packets from the network with the CoAP 2937 nodes; see Section 11.5 for an additional complication with this 2938 approach. 2940 The other three security modes are achieved using DTLS and are 2941 indicated by the "coaps" scheme and DTLS-secured CoAP default port. 2942 The result is a security association that can be used to authenticate 2943 (within the limits of the security model) and, based on this 2944 authentication, authorize the communication partner. CoAP itself 2945 does not provide protocol primitives for authentication or 2946 authorization; where this is required, it can either be provided by 2947 communication security (i.e., IPsec or DTLS) or by object security 2948 (within the payload). Devices that require authorization for certain 2949 operations are expected to require one of these two forms of 2950 security. Necessarily, where an intermediary is involved, 2951 communication security only works when that intermediary is part of 2952 the trust relationships; CoAP does not provide a way to forward 2953 different levels of authorization that clients may have with an 2954 intermediary to further intermediaries or origin servers -- it 2955 therefore may be required to perform all authorization at the first 2956 intermediary. 2958 9.1. DTLS-secured CoAP 2960 Just as HTTP is secured using Transport Layer Security (TLS) over 2961 TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP 2962 (see Figure 13). This section defines the CoAP binding to DTLS, 2963 along with the minimal mandatory-to-implement configurations 2964 appropriate for constrained environments. The binding is defined by 2965 a series of deltas to Unicast CoAP. DTLS is in practice TLS with 2966 added features to deal with the unreliable nature of the UDP 2967 transport. 2969 +----------------------+ 2970 | Application | 2971 +----------------------+ 2972 +----------------------+ 2973 | Requests/Responses | 2974 |----------------------| CoAP 2975 | Messages | 2976 +----------------------+ 2977 +----------------------+ 2978 | DTLS | 2979 +----------------------+ 2980 +----------------------+ 2981 | UDP | 2982 +----------------------+ 2984 Figure 13: Abstract layering of DTLS-secured CoAP 2986 In some constrained nodes (limited flash and/or RAM) and networks 2987 (limited bandwidth or high scalability requirements), and depending 2988 on the specific cipher suites in use, all modes of DTLS may not be 2989 applicable. Some DTLS cipher suites can add significant 2990 implementation complexity as well as some initial handshake overhead 2991 needed when setting up the security association. Once the initial 2992 handshake is completed, DTLS adds a limited per-datagram overhead of 2993 approximately 13 bytes, not including any initialization vectors/ 2994 nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]), 2995 integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 2996 [RFC6655]) and padding required by the cipher suite. Whether and 2997 which mode of using DTLS is applicable for a CoAP-based application 2998 should be carefully weighed considering the specific cipher suites 2999 that may be applicable, and whether the session maintenance makes it 3000 compatible with application flows and sufficient resources are 3001 available on the constrained nodes and for the added network 3002 overhead. DTLS is not applicable to group keying (multicast 3003 communication); however, it may be a component in a future group key 3004 management protocol. 3006 9.1.1. Messaging Layer 3008 The endpoint acting as the CoAP client should also act as the DTLS 3009 client. It should initiate a session to the server on the 3010 appropriate port. When the DTLS handshake has finished, the client 3011 may initiate the first CoAP request. All CoAP messages MUST be sent 3012 as DTLS "application data". 3014 The following rules are added for matching an ACK or RST to a CON 3015 message or a RST to a NON message: The DTLS session MUST be the same 3016 and the epoch MUST be the same. 3018 A message is the same when it is sent within the same DTLS session 3019 and same epoch and has the same Message ID. 3021 Note: When a confirmable message is retransmitted, a new DTLS 3022 sequence_number is used for each attempt, even though the CoAP 3023 Message ID stays the same. So a recipient still has to perform 3024 deduplication as described in Section 4.5. Retransmissions MUST NOT 3025 be performed across epochs. 3027 DTLS connections in RawPublicKey and Certificate mode are set up 3028 using mutual authentication so they can remain up and be reused for 3029 future message exchanges in either direction. Devices can close a 3030 DTLS connection when they need to recover resources but in general 3031 they should keep the connection up for as long as possible. Closing 3032 the DTLS connection after every CoAP message exchange is very 3033 inefficient. 3035 9.1.2. Request/Response Layer 3037 The following rules are added for matching a response to a request: 3038 The DTLS session MUST be the same and the epoch MUST be the same. 3040 9.1.3. Endpoint Identity 3042 Devices SHOULD support the Server Name Indication (SNI) to indicate 3043 their Authority Name in the SNI HostName field as defined in Section 3044 3 of [RFC6066]. This is needed so that when a host that acts as a 3045 virtual server for multiple Authorities receives a new DTLS 3046 connection, it knows which keys to use for the DTLS session. 3048 9.1.3.1. Pre-Shared Keys 3050 When forming a connection to a new node, the system selects an 3051 appropriate key based on which nodes it is trying to reach and then 3052 forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. 3053 Implementations in these modes MUST support the mandatory to 3054 implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in 3055 [RFC6655]. 3057 The security considerations of [RFC4279] (Section 7) apply. In 3058 particular, applications should carefully weigh whether they need 3059 Perfect Forward Secrecy (PFS) or not and select an appropriate cipher 3060 suite (7.1). The entropy of the PSK must be sufficient to mitigate 3061 against brute-force and (where the PSK is not chosen randomly but by 3062 a human) dictionary attacks (7.2). The cleartext communication of 3063 client identities may leak data or compromise privacy (7.3). 3065 9.1.3.2. Raw Public Key Certificates 3067 In this mode the device has an asymmetric key pair but without an 3068 X.509 certificate (called a raw public key). A device MAY be 3069 configured with multiple raw public keys. The type and length of the 3070 raw public key depends on the cipher suite used. Implementations in 3071 RawPublicKey mode MUST support the mandatory to implement cipher 3072 suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in 3073 [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. The mechanism 3074 for using raw public keys with TLS is specified in 3075 [I-D.ietf-tls-oob-pubkey]. 3077 9.1.3.2.1. Provisioning 3079 The RawPublicKey mode was designed to be easily provisioned in M2M 3080 deployments. It is assumed that each device has an appropriate 3081 asymmetric public key pair installed. An identifier is calculated 3082 from the public key as described in Section 2 of 3083 [I-D.farrell-decade-ni]. All implementations that support checking 3084 RawPublicKey identities MUST support at least the sha-256-120 mode 3085 (SHA-256 truncated to 120 bits). Implementations SHOULD support also 3086 longer length identifiers and MAY support shorter lengths. Note that 3087 the shorter lengths provide less security against attacks and their 3088 use is NOT RECOMMENDED. 3090 Depending on how identifiers are given to the system that verifies 3091 them, support for URI, binary, and/or human-speakable format 3092 [I-D.farrell-decade-ni] needs to be implemented. All implementations 3093 SHOULD support the binary mode and implementations that have a user 3094 interface SHOULD also support the human-speakable format. 3096 During provisioning, the identifier of each node is collected, for 3097 example by reading a barcode on the outside of the device or by 3098 obtaining a pre-compiled list of the identifiers. These identifiers 3099 are then installed in the corresponding endpoint, for example an M2M 3100 data collection server. The identifier is used for two purposes, to 3101 associate the endpoint with further device information and to perform 3102 access control. During provisioning, an access control list of 3103 identifiers the device may start DTLS sessions with SHOULD also be 3104 installed. 3106 9.1.3.3. X.509 Certificates 3108 Implementations in Certificate Mode MUST support the mandatory to 3109 implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as 3110 specified in [RFC5246]. 3112 The Authority Name in the certificate is the name that would be used 3113 in the Host part of a CoAP URI. It is worth noting that this would 3114 typically not be either an IP address or DNS name built in the usual 3115 way but would instead be built out of a long term unique identifier 3116 for the device such as the EUI-64 [EUI64]. The discovery process 3117 used in the system would build up the mapping between IP addresses of 3118 the given devices and the Authority Name for each device. Some 3119 devices could have more than one Authority and would need more than a 3120 single certificate. 3122 When a new connection is formed, the certificate from the remote 3123 device needs to be verified. If the CoAP node has a source of 3124 absolute time, then the node SHOULD check that the validity dates of 3125 the certificate are within range. The certificate MUST also be 3126 signed by an appropriate chain of trust. If the certificate contains 3127 a SubjectAltName, then the Authority Name MUST match at least one of 3128 the authority names of any CoAP URI found in a field of URI type in 3129 the SubjectAltName set. If there is no SubjectAltName in the 3130 certificate, then the Authoritative Name must match the CN found in 3131 the certificate using the matching rules defined in [RFC2818] with 3132 the exception that certificates with wildcards are not allowed. 3134 If the system has a shared key in addition to the certificate, then a 3135 cipher suite that includes the shared key such as 3136 TLS_RSA_PSK_WITH_AES_128_CBC_SHA [RFC4279] SHOULD be used. 3138 10. Cross-Protocol Proxying between CoAP and HTTP 3140 CoAP supports a limited subset of HTTP functionality, and thus cross- 3141 protocol proxying to HTTP is straightforward. There might be several 3142 reasons for proxying between CoAP and HTTP, for example when 3143 designing a web interface for use over either protocol or when 3144 realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied 3145 to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the 3146 definition of these mechanisms is out of scope of this specification. 3148 There are two possible directions to access a resource via a forward- 3149 proxy: 3151 CoAP-HTTP Proxying: Enables CoAP clients to access resources on HTTP 3152 servers through an intermediary. This is initiated by including 3153 the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI 3154 in a CoAP request to a CoAP-HTTP proxy. 3156 HTTP-CoAP Proxying: Enables HTTP clients to access resources on CoAP 3157 servers through an intermediary. This is initiated by specifying 3158 a "coap" or "coaps" URI in the Request-Line of an HTTP request to 3159 an HTTP-CoAP proxy. 3161 Either way, only the Request/Response model of CoAP is mapped to 3162 HTTP. The underlying model of confirmable or non-confirmable 3163 messages, etc., is invisible and MUST have no effect on a proxy 3164 function. The following sections describe the handling of requests 3165 to a forward-proxy. Reverse proxies are not specified as the proxy 3166 function is transparent to the client with the proxy acting as if it 3167 was the origin server. However, similar considerations apply to 3168 reverse-proxies as to forward-proxies, and there generally will be an 3169 expectation that reverse-proxies operate in a similar way forward- 3170 proxies would. As an implementation note, HTTP client libraries may 3171 make it hard to operate an HTTP-CoAP forward proxy by not providing a 3172 way to put a CoAP URI on the HTTP Request-Line; reverse-proxying may 3173 therefore lead to wider applicability of a proxy. A separate 3174 specification may define a convention for URIs operating such a HTTP- 3175 CoAP reverse proxy [I-D.bormann-core-cross-reverse-convention]. 3177 10.1. CoAP-HTTP Proxying 3179 If a request contains a Proxy-Uri or Proxy-Scheme Option with an 3180 'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint 3181 (called "the proxy" henceforth) is requested to perform the operation 3182 specified by the request method on the indicated HTTP resource and 3183 return the result to the client. 3185 This section specifies for any CoAP request the CoAP response that 3186 the proxy should return to the client. How the proxy actually 3187 satisfies the request is an implementation detail, although the 3188 typical case is expected to be the proxy translating and forwarding 3189 the request to an HTTP origin server. 3191 Since HTTP and CoAP share the basic set of request methods, 3192 performing a CoAP request on an HTTP resource is not so different 3193 from performing it on a CoAP resource. The meanings of the 3194 individual CoAP methods when performed on HTTP resources are 3195 explained below. 3197 If the proxy is unable or unwilling to service a request with an HTTP 3198 URI, a 5.05 (Proxying Not Supported) response is returned to the 3199 client. If the proxy services the request by interacting with a 3200 third party (such as the HTTP origin server) and is unable to obtain 3201 a result within a reasonable time frame, a 5.04 (Gateway Timeout) 3202 response is returned; if a result can be obtained but is not 3203 understood, a 5.02 (Bad Gateway) response is returned. 3205 10.1.1. GET 3207 The GET method requests the proxy to return a representation of the 3208 HTTP resource identified by the request URI. 3210 Upon success, a 2.05 (Content) response code SHOULD be returned. The 3211 payload of the response MUST be a representation of the target HTTP 3212 resource, and the Content-Format Option be set accordingly. The 3213 response MUST indicate a Max-Age value that is no greater than the 3214 remaining time the representation can be considered fresh. If the 3215 HTTP entity has an entity tag, the proxy SHOULD include an ETag 3216 Option in the response and process ETag Options in requests as 3217 described below. 3219 A client can influence the processing of a GET request by including 3220 the following option: 3222 Accept: The request MAY include one or more Accept Options, 3223 identifying the preferred response content-format. 3225 ETag: The request MAY include one or more ETag Options, identifying 3226 responses that the client has stored. This requests the proxy to 3227 send a 2.03 (Valid) response whenever it would send a 2.05 3228 (Content) response with an entity tag in the requested set 3229 otherwise. Note that CoAP ETags are always strong ETags in the 3230 HTTP sense; CoAP does not have the equivalent of HTTP weak ETags, 3231 and there is no good way to make use of these in a cross-proxy. 3233 10.1.2. PUT 3235 The PUT method requests the proxy to update or create the HTTP 3236 resource identified by the request URI with the enclosed 3237 representation. 3239 If a new resource is created at the request URI, a 2.01 (Created) 3240 response MUST be returned to the client. If an existing resource is 3241 modified, a 2.04 (Changed) response MUST be returned to indicate 3242 successful completion of the request. 3244 10.1.3. DELETE 3246 The DELETE method requests the proxy to delete the HTTP resource 3247 identified by the request URI at the HTTP origin server. 3249 A 2.02 (Deleted) response MUST be returned to client upon success or 3250 if the resource does not exist at the time of the request. 3252 10.1.4. POST 3254 The POST method requests the proxy to have the representation 3255 enclosed in the request be processed by the HTTP origin server. The 3256 actual function performed by the POST method is determined by the 3257 origin server and dependent on the resource identified by the request 3258 URI. 3260 If the action performed by the POST method does not result in a 3261 resource that can be identified by a URI, a 2.04 (Changed) response 3262 MUST be returned to the client. If a resource has been created on 3263 the origin server, a 2.01 (Created) response MUST be returned. 3265 10.2. HTTP-CoAP Proxying 3267 If an HTTP request contains a Request-URI with a 'coap' or 'coaps' 3268 URI, then the receiving HTTP endpoint (called "the proxy" henceforth) 3269 is requested to perform the operation specified by the request method 3270 on the indicated CoAP resource and return the result to the client. 3272 This section specifies for any HTTP request the HTTP response that 3273 the proxy should return to the client. Unless otherwise specified 3274 all the statements made are RECOMMENDED behavior; some highly 3275 constrained implementations may need to resort to shortcuts. How the 3276 proxy actually satisfies the request is an implementation detail, 3277 although the typical case is expected to be the proxy translating and 3278 forwarding the request to a CoAP origin server. The meanings of the 3279 individual HTTP methods when performed on CoAP resources are 3280 explained below. 3282 If the proxy is unable or unwilling to service a request with a CoAP 3283 URI, a 501 (Not Implemented) response is returned to the client. If 3284 the proxy services the request by interacting with a third party 3285 (such as the CoAP origin server) and is unable to obtain a result 3286 within a reasonable time frame, a 504 (Gateway Timeout) response is 3287 returned; if a result can be obtained but is not understood, a 502 3288 (Bad Gateway) response is returned. 3290 10.2.1. OPTIONS and TRACE 3292 As the OPTIONS and TRACE methods are not supported in CoAP a 501 (Not 3293 Implemented) error MUST be returned to the client. 3295 10.2.2. GET 3297 The GET method requests the proxy to return a representation of the 3298 CoAP resource identified by the Request-URI. 3300 Upon success, a 200 (OK) response is returned. The payload of the 3301 response MUST be a representation of the target CoAP resource, and 3302 the Content-Type and Content-Encoding header fields be set 3303 accordingly. The response MUST indicate a max-age directive that 3304 indicates a value no greater than the remaining time the 3305 representation can be considered fresh. If the CoAP response has an 3306 ETag option, the proxy should include an ETag header field in the 3307 response. 3309 A client can influence the processing of a GET request by including 3310 the following options: 3312 Accept: Each individual Media-type of the HTTP Accept header in a 3313 request is mapped to a CoAP Accept option. HTTP Accept Media-type 3314 ranges, parameters and extensions are not supported by the CoAP 3315 Accept option. If the proxy cannot send a response which is 3316 acceptable according to the combined Accept field value, then the 3317 proxy sends a 406 (not acceptable) response. 3319 Conditional GETs: Conditional HTTP GET requests that include an "If- 3320 Match" or "If-None-Match" request-header field can be mapped to a 3321 corresponding CoAP request. The "If-Modified-Since" and "If- 3322 Unmodified-Since" request-header fields are not directly supported 3323 by CoAP, but are implemented locally by a caching proxy. 3325 10.2.3. HEAD 3327 The HEAD method is identical to GET except that the server MUST NOT 3328 return a message-body in the response. 3330 Although there is no direct equivalent of HTTP's HEAD method in CoAP, 3331 an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and 3332 the HTTP headers are returned without a message-body. 3334 Implementation Note: An HTTP-CoAP proxy may want to try using a 3335 block-wise transfer [I-D.ietf-core-block] option to minimize the 3336 amount of data actually transferred, but needs to be prepared for 3337 the case that the origin server does not support block-wise 3338 transfers. 3340 10.2.4. POST 3342 The POST method requests the proxy to have the representation 3343 enclosed in the request be processed by the CoAP origin server. The 3344 actual function performed by the POST method is determined by the 3345 origin server and dependent on the resource identified by the request 3346 URI. 3348 If the action performed by the POST method does not result in a 3349 resource that can be identified by a URI, a 200 (OK) or 204 (No 3350 Content) response MUST be returned to the client. If a resource has 3351 been created on the origin server, a 201 (Created) response MUST be 3352 returned. 3354 If any of the Location-* Options are present in the CoAP response, a 3355 Location header field constructed from the values of these options is 3356 returned. 3358 10.2.5. PUT 3360 The PUT method requests the proxy to update or create the CoAP 3361 resource identified by the Request-URI with the enclosed 3362 representation. 3364 If a new resource is created at the Request-URI, a 201 (Created) 3365 response is returned to the client. If an existing resource is 3366 modified, either the 200 (OK) or 204 (No Content) response codes is 3367 sent to indicate successful completion of the request. 3369 10.2.6. DELETE 3371 The DELETE method requests the proxy to delete the CoAP resource 3372 identified by the Request-URI at the CoAP origin server. 3374 A successful response is 200 (OK) if the response includes an entity 3375 describing the status or 204 (No Content) if the action has been 3376 enacted but the response does not include an entity. 3378 10.2.7. CONNECT 3380 This method can not currently be satisfied by an HTTP-CoAP proxy 3381 function as TLS to DTLS tunneling has not yet been specified. For 3382 now, a 501 (Not Implemented) error is returned to the client. 3384 11. Security Considerations 3386 This section analyzes the possible threats to the protocol. It is 3387 meant to inform protocol and application developers about the 3388 security limitations of CoAP as described in this document. As CoAP 3389 realizes a subset of the features in HTTP/1.1, the security 3390 considerations in Section 15 of [RFC2616] are also pertinent to CoAP. 3391 This section concentrates on describing limitations specific to CoAP. 3393 11.1. Protocol Parsing, Processing URIs 3395 A network-facing application can exhibit vulnerabilities in its 3396 processing logic for incoming packets. Complex parsers are well- 3397 known as a likely source of such vulnerabilities, such as the ability 3398 to remotely crash a node, or even remotely execute arbitrary code on 3399 it. CoAP attempts to narrow the opportunities for introducing such 3400 vulnerabilities by reducing parser complexity, by giving the entire 3401 range of encodable values a meaning where possible, and by 3402 aggressively reducing complexity that is often caused by unnecessary 3403 choice between multiple representations that mean the same thing. 3404 Much of the URI processing has been moved to the clients, further 3405 reducing the opportunities for introducing vulnerabilities into the 3406 servers. Even so, the URI processing code in CoAP implementations is 3407 likely to be a large source of remaining vulnerabilities and should 3408 be implemented with special care. The most complex parser remaining 3409 could be the one for the CoRE Link Format, although this also has 3410 been designed with a goal of reduced implementation complexity 3411 [RFC6690]. (See also section 15.2 of [RFC2616].) 3413 11.2. Proxying and Caching 3415 As mentioned in 15.7 of [RFC2616], proxies are by their very nature 3416 men-in-the-middle, breaking any IPsec or DTLS protection that a 3417 direct CoAP message exchange might have. They are therefore 3418 interesting targets for breaking confidentiality or integrity of CoAP 3419 message exchanges. As noted in [RFC2616], they are also interesting 3420 targets for breaking availability. 3422 The threat to confidentiality and integrity of request/response data 3423 is amplified where proxies also cache. Note that CoAP does not 3424 define any of the cache-suppressing Cache-Control options that 3425 HTTP/1.1 provides to better protect sensitive data. 3427 For a caching implementation, any access control considerations that 3428 would apply to making the request that generated the cache entry also 3429 need to be applied to the value in the cache. This is relevant for 3430 clients that implement multiple security domains, as well as for 3431 proxies that may serve multiple clients. Also, a caching proxy MUST 3432 NOT make cached values available to requests that have lesser 3433 transport security properties than to which it would make available 3434 the process of forwarding the request in the first place. 3436 Unlike the "coap" scheme, responses to "coaps" identified requests 3437 are never "public" and thus MUST NOT be reused for shared caching 3438 unless the cache is able to make equivalent access control decisions 3439 to the ones that led to the cached entry. They can, however, be 3440 reused in a private cache if the message is cacheable by default in 3441 CoAP. 3443 Finally, a proxy that fans out Separate Responses (as opposed to 3444 Piggy-backed Responses) to multiple original requesters may provide 3445 additional amplification (see below). 3447 11.3. Risk of amplification 3449 CoAP servers generally reply to a request packet with a response 3450 packet. This response packet may be significantly larger than the 3451 request packet. An attacker might use CoAP nodes to turn a small 3452 attack packet into a larger attack packet, an approach known as 3453 amplification. There is therefore a danger that CoAP nodes could 3454 become implicated in denial of service (DoS) attacks by using the 3455 amplifying properties of the protocol: An attacker that is attempting 3456 to overload a victim but is limited in the amount of traffic it can 3457 generate, can use amplification to generate a larger amount of 3458 traffic. 3460 This is particularly a problem in nodes that enable NoSec access, 3461 that are accessible from an attacker and can access potential victims 3462 (e.g. on the general Internet), as the UDP protocol provides no way 3463 to verify the source address given in the request packet. An 3464 attacker need only place the IP address of the victim in the source 3465 address of a suitable request packet to generate a larger packet 3466 directed at the victim. 3468 As a mitigating factor, many constrained networks will only be able 3469 to generate a small amount of traffic, which may make CoAP nodes less 3470 attractive for this attack. However, the limited capacity of the 3471 constrained network makes the network itself a likely victim of an 3472 amplification attack. 3474 A CoAP server can reduce the amount of amplification it provides to 3475 an attacker by using slicing/blocking modes of CoAP 3476 [I-D.ietf-core-block] and offering large resource representations 3477 only in relatively small slices. E.g., for a 1000 byte resource, a 3478 10-byte request might result in an 80-byte response (with a 64-byte 3479 block) instead of a 1016-byte response, considerably reducing the 3480 amplification provided. 3482 CoAP also supports the use of multicast IP addresses in requests, an 3483 important requirement for M2M. Multicast CoAP requests may be the 3484 source of accidental or deliberate denial of service attacks, 3485 especially over constrained networks. This specification attempts to 3486 reduce the amplification effects of multicast requests by limiting 3487 when a response is returned. To limit the possibility of malicious 3488 use, CoAP servers SHOULD NOT accept multicast requests that can not 3489 be authenticated in some way, cryptographically or by some multicast 3490 boundary limiting the potential sources. If possible a CoAP server 3491 SHOULD limit the support for multicast requests to the specific 3492 resources where the feature is required. 3494 On some general purpose operating systems providing a Posix-style 3495 API, it is not straightforward to find out whether a packet received 3496 was addressed to a multicast address. While many implementations 3497 will know whether they have joined a multicast group, this creates a 3498 problem for packets addressed to multicast addresses of the form 3499 FF0x::1, which are received by every IPv6 node. Implementations 3500 SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 3501 available, to make this determination. 3503 11.4. IP Address Spoofing Attacks 3505 Due to the lack of a handshake in UDP, a rogue endpoint which is free 3506 to read and write messages carried by the constrained network (i.e. 3507 NoSec or PreSharedKey deployments with nodes/key ratio > 1:1), may 3508 easily attack a single endpoint, a group of endpoints, as well as the 3509 whole network e.g. by: 3511 1. spoofing RST in response to a CON or NON message, thus making an 3512 endpoint "deaf"; or 3514 2. spoofing the entire response with forged payload/options (this 3515 has different levels of impact: from single response disruption, 3516 to much bolder attacks on the supporting infrastructure, e.g. 3517 poisoning proxy caches, or tricking validation / lookup 3518 interfaces in resource directories and, more generally, any 3519 component that stores global network state and uses CoAP as the 3520 messaging facility to handle state set/update's is a potential 3521 target.); or 3523 3. spoofing a multicast request for a target node which may result 3524 in both network congestion/collapse and victim DoS'ing / forced 3525 wakeup from sleeping; or 3527 4. spoofing observe messages, etc. 3529 In principle, spoofing can be detected by CoAP only in case CON 3530 semantics is used, because of unexpected ACK/RSTs coming from the 3531 deceived endpoint. But this imposes keeping track of the used 3532 Message IDs which is not always possible, and moreover detection 3533 becomes available usually after the damage is already done. This 3534 kind of attack can be prevented using security modes other than 3535 NoSec. 3537 11.5. Cross-Protocol Attacks 3539 The ability to incite a CoAP endpoint to send packets to a fake 3540 source address can be used not only for amplification, but also for 3541 cross-protocol attacks against a victim listening to UDP packets at a 3542 given address (IP address and port): 3544 o the attacker sends a message to a CoAP endpoint with the given 3545 address as the fake source address, 3547 o the CoAP endpoint replies with a message to the given source 3548 address, 3550 o the victim at the given address receives a UDP packet that it 3551 interprets according to the rules of a different protocol. 3553 This may be used to circumvent firewall rules that prevent direct 3554 communication from the attacker to the victim, but happen to allow 3555 communication from the CoAP endpoint (which may also host a valid 3556 role in the other protocol) to the victim. 3558 Also, CoAP endpoints may be the victim of a cross-protocol attack 3559 generated through an endpoint of another UDP-based protocol such as 3560 DNS. In both cases, attacks are possible if the security properties 3561 of the endpoints rely on checking IP addresses (and firewalling off 3562 direct attacks sent from outside using fake IP addresses). In 3563 general, because of their lack of context, UDP-based protocols are 3564 relatively easy targets for cross-protocol attacks. 3566 Finally, CoAP URIs transported by other means could be used to incite 3567 clients to send messages to endpoints of other protocols. 3569 One mitigation against cross-protocol attacks is strict checking of 3570 the syntax of packets received, combined with sufficient difference 3571 in syntax. As an example, it might help if it were difficult to 3572 incite a DNS server to send a DNS response that would pass the checks 3573 of a CoAP endpoint. Unfortunately, the first two bytes of a DNS 3574 reply are an ID that can be chosen by the attacker, which map into 3575 the interesting part of the CoAP header, and the next two bytes are 3576 then interpreted as CoAP's Message ID (i.e., any value is 3577 acceptable). The DNS count words may be interpreted as multiple 3578 instances of a (non-existent, but elective) CoAP option 0, or 3579 possibly as a Token. The echoed query finally may be manufactured by 3580 the attacker to achieve a desired effect on the CoAP endpoint; the 3581 response added by the server (if any) might then just be interpreted 3582 as added payload. 3584 1 1 1 1 1 1 3585 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 3586 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3587 | ID | T, TKL, code 3588 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3589 |QR| Opcode |AA|TC|RD|RA| Z | RCODE | message id 3590 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3591 | QDCOUNT | (options 0) 3592 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3593 | ANCOUNT | (options 0) 3594 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3595 | NSCOUNT | (options 0) 3596 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3597 | ARCOUNT | (options 0) 3598 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3600 Figure 14: DNS Header vs. CoAP Message 3602 In general, for any pair of protocols, one of the protocols can very 3603 well have been designed in a way that enables an attacker to cause 3604 the generation of replies that look like messages of the other 3605 protocol. It is often much harder to ensure or prove the absence of 3606 viable attacks than to generate examples that may not yet completely 3607 enable an attack but might be further developed by more creative 3608 minds. Cross-protocol attacks can therefore only be completely 3609 mitigated if endpoints don't authorize actions desired by an attacker 3610 just based on trusting the source IP address of a packet. 3611 Conversely, a NoSec environment that completely relies on a firewall 3612 for CoAP security not only needs to firewall off the CoAP endpoints 3613 but also all other endpoints that might be incited to send UDP 3614 messages to CoAP endpoints using some other UDP-based protocol. 3616 In addition to the considerations above, the security considerations 3617 for DTLS with respect to cross-protocol attacks apply. E.g., if the 3618 same DTLS security association ("connection") is used to carry data 3619 of multiple protocols, DTLS no longer provides protection against 3620 cross-protocol attacks between these protocols. 3622 12. IANA Considerations 3624 12.1. CoAP Code Registry 3626 This document defines a registry for the values of the Code field in 3627 the CoAP header. The name of the registry is "CoAP Codes". 3629 All values are assigned by sub-registries according to the following 3630 ranges: 3632 0 Indicates an empty message (see Section 4.1). 3634 1-31 Indicates a request. Values in this range are assigned by 3635 the "CoAP Method Codes" sub-registry (see Section 12.1.1). 3637 32-63 Reserved 3639 64-191 Indicates a response. Values in this range are assigned by 3640 the "CoAP Response Codes" sub-registry (see 3641 Section 12.1.2). 3643 192-255 Reserved 3645 12.1.1. Method Codes 3647 The name of the sub-registry is "CoAP Method Codes". 3649 Each entry in the sub-registry must include the Method Code in the 3650 range 1-31, the name of the method, and a reference to the method's 3651 documentation. 3653 Initial entries in this sub-registry are as follows: 3655 +------+--------+-----------+ 3656 | Code | Name | Reference | 3657 +------+--------+-----------+ 3658 | 1 | GET | [RFCXXXX] | 3659 | 2 | POST | [RFCXXXX] | 3660 | 3 | PUT | [RFCXXXX] | 3661 | 4 | DELETE | [RFCXXXX] | 3662 +------+--------+-----------+ 3664 Table 2: CoAP Method Codes 3666 All other Method Codes are Unassigned. 3668 The IANA policy for future additions to this registry is "IETF Review 3669 or IESG approval" as described in [RFC5226]. 3671 The documentation of a method code should specify the semantics of a 3672 request with that code, including the following properties: 3674 o The response codes the method returns in the success case. 3676 o Whether the method is idempotent, safe, or both. 3678 12.1.2. Response Codes 3680 The name of the sub-registry is "CoAP Response Codes". 3682 Each entry in the sub-registry must include the Response Code in the 3683 range 64-191, a description of the Response Code, and a reference to 3684 the Response Code's documentation. 3686 Initial entries in this sub-registry are as follows: 3688 +------+---------------------------------+-----------+ 3689 | Code | Description | Reference | 3690 +------+---------------------------------+-----------+ 3691 | 65 | 2.01 Created | [RFCXXXX] | 3692 | 66 | 2.02 Deleted | [RFCXXXX] | 3693 | 67 | 2.03 Valid | [RFCXXXX] | 3694 | 68 | 2.04 Changed | [RFCXXXX] | 3695 | 69 | 2.05 Content | [RFCXXXX] | 3696 | 128 | 4.00 Bad Request | [RFCXXXX] | 3697 | 129 | 4.01 Unauthorized | [RFCXXXX] | 3698 | 130 | 4.02 Bad Option | [RFCXXXX] | 3699 | 131 | 4.03 Forbidden | [RFCXXXX] | 3700 | 132 | 4.04 Not Found | [RFCXXXX] | 3701 | 133 | 4.05 Method Not Allowed | [RFCXXXX] | 3702 | 134 | 4.06 Not Acceptable | [RFCXXXX] | 3703 | 140 | 4.12 Precondition Failed | [RFCXXXX] | 3704 | 141 | 4.13 Request Entity Too Large | [RFCXXXX] | 3705 | 143 | 4.15 Unsupported Content-Format | [RFCXXXX] | 3706 | 160 | 5.00 Internal Server Error | [RFCXXXX] | 3707 | 161 | 5.01 Not Implemented | [RFCXXXX] | 3708 | 162 | 5.02 Bad Gateway | [RFCXXXX] | 3709 | 163 | 5.03 Service Unavailable | [RFCXXXX] | 3710 | 164 | 5.04 Gateway Timeout | [RFCXXXX] | 3711 | 165 | 5.05 Proxying Not Supported | [RFCXXXX] | 3712 +------+---------------------------------+-----------+ 3714 Table 3: CoAP Response Codes 3716 The Response Codes 96-127 are Reserved for future use. All other 3717 Response Codes are Unassigned. 3719 The IANA policy for future additions to this registry is "IETF Review 3720 or IESG approval" as described in [RFC5226]. 3722 The documentation of a response code should specify the semantics of 3723 a response with that code, including the following properties: 3725 o The methods the response code applies to. 3727 o Whether payload is required, optional or not allowed. 3729 o The semantics of the payload. For example, the payload of a 2.05 3730 (Content) response is a representation of the target resource; the 3731 payload in an error response is a human-readable diagnostic 3732 payload. 3734 o The format of the payload. For example, the format in a 2.05 3735 (Content) response is indicated by the Content-Format Option; the 3736 format of the payload in an error response is always Net-Unicode 3737 text. 3739 o Whether the response is cacheable according to the freshness 3740 model. 3742 o Whether the response is validatable according to the validation 3743 model. 3745 o Whether the response causes a cache to mark responses stored for 3746 the request URI as not fresh. 3748 12.2. Option Number Registry 3750 This document defines a registry for the Option Numbers used in CoAP 3751 options. The name of the registry is "CoAP Option Numbers". 3753 Each entry in the registry must include the Option Number, the name 3754 of the option and a reference to the option's documentation. 3756 Initial entries in this registry are as follows: 3758 +--------+----------------+-----------+ 3759 | Number | Name | Reference | 3760 +--------+----------------+-----------+ 3761 | 0 | (Reserved) | | 3762 | 1 | If-Match | [RFCXXXX] | 3763 | 3 | Uri-Host | [RFCXXXX] | 3764 | 4 | ETag | [RFCXXXX] | 3765 | 5 | If-None-Match | [RFCXXXX] | 3766 | 7 | Uri-Port | [RFCXXXX] | 3767 | 8 | Location-Path | [RFCXXXX] | 3768 | 11 | Uri-Path | [RFCXXXX] | 3769 | 12 | Content-Format | [RFCXXXX] | 3770 | 14 | Max-Age | [RFCXXXX] | 3771 | 15 | Uri-Query | [RFCXXXX] | 3772 | 16 | Accept | [RFCXXXX] | 3773 | 20 | Location-Query | [RFCXXXX] | 3774 | 35 | Proxy-Uri | [RFCXXXX] | 3775 | 39 | Proxy-Scheme | [RFCXXXX] | 3776 | 128 | (Reserved) | [RFCXXXX] | 3777 | 132 | (Reserved) | [RFCXXXX] | 3778 | 136 | (Reserved) | [RFCXXXX] | 3779 | 140 | (Reserved) | [RFCXXXX] | 3780 +--------+----------------+-----------+ 3782 Table 4: CoAP Option Numbers 3784 The IANA policy for future additions to this registry is split into 3785 three tiers as follows. The range of 0..255 is reserved for options 3786 defined by the IETF (IETF Review or IESG approval). The range of 3787 256..2047 is reserved for commonly used options with public 3788 specifications (Specification Required). The range of 2048..64999 is 3789 for all other options including private or vendor specific ones, 3790 which undergo a Designated Expert review to help ensure that the 3791 option semantics are defined correctly. The option numbers between 3792 65000 and 65535 inclusive are reserved for experiments. They are not 3793 meant for vendor specific use of any kind and MUST NOT be used in 3794 operational deployments. 3796 +---------------+------------------------------+ 3797 | Option Number | Policy [RFC5226] | 3798 +---------------+------------------------------+ 3799 | 0..255 | IETF Review or IESG approval | 3800 | 256..2047 | Specification Required | 3801 | 2048..64999 | Designated Expert | 3802 | 65000..65535 | Reserved for experiments | 3803 +---------------+------------------------------+ 3805 The documentation of an Option Number should specify the semantics of 3806 an option with that number, including the following properties: 3808 o The meaning of the option in a request. 3810 o The meaning of the option in a response. 3812 o Whether the option is critical or elective, as determined by the 3813 Option Number. 3815 o Whether the option is Safe, and, if yes, whether it is part of the 3816 Cache-Key, as determined by the Option Number (see Section 5.4.2). 3818 o The format and length of the option's value. 3820 o Whether the option must occur at most once or whether it can occur 3821 multiple times. 3823 o The default value, if any. For a critical option with a default 3824 value, a discussion on how the default value enables processing by 3825 implementations not implementing the critical option 3826 (Section 5.4.4). 3828 12.3. Content-Format Registry 3830 Internet media types are identified by a string, such as 3831 "application/xml" [RFC2046]. In order to minimize the overhead of 3832 using these media types to indicate the format of payloads, this 3833 document defines a registry for a subset of Internet media types to 3834 be used in CoAP and assigns each, in combination with a content- 3835 coding, a numeric identifier. The name of the registry is "CoAP 3836 Content-Formats". 3838 Each entry in the registry must include the media type registered 3839 with IANA, the numeric identifier in the range 0-65535 to be used for 3840 that media type in CoAP, the content-coding associated with this 3841 identifier, and a reference to a document describing what a payload 3842 with that media type means semantically. 3844 CoAP does not include a separate way to convey content-encoding 3845 information with a request or response, and for that reason the 3846 content-encoding is also specified for each identifier (if any). If 3847 multiple content-encodings will be used with a media type, then a 3848 separate Content-Format identifier for each is to be registered. 3849 Similarly, other parameters related to an Internet media type, such 3850 as level, can be defined for a CoAP Content-Format entry. 3852 Initial entries in this registry are as follows: 3854 +--------------------+----------+-----+-----------------------------+ 3855 | Media type | Encoding | Id. | Reference | 3856 +--------------------+----------+-----+-----------------------------+ 3857 | text/plain; | - | 0 | [RFC2046][RFC3676][RFC5147] | 3858 | charset=utf-8 | | | | 3859 | application/ | - | 40 | [RFC6690] | 3860 | link-format | | | | 3861 | application/xml | - | 41 | [RFC3023] | 3862 | application/ | - | 42 | [RFC2045][RFC2046] | 3863 | octet-stream | | | | 3864 | application/exi | - | 47 | [EXIMIME] | 3865 | application/json | - | 50 | [RFC4627] | 3866 +--------------------+----------+-----+-----------------------------+ 3868 Table 5: CoAP Content-Formats 3870 The identifiers between 65000 and 65535 inclusive are reserved for 3871 experiments. They are not meant for vendor specific use of any kind 3872 and MUST NOT be used in operational deployments. The identifiers 3873 between 256 and 9999 are reserved for future use in IETF 3874 specifications (IETF review or IESG approval). All other identifiers 3875 are Unassigned. 3877 Because the name space of single-byte identifiers is so small, the 3878 IANA policy for future additions in the range 0-255 inclusive to the 3879 registry is "Expert Review" as described in [RFC5226]. The IANA 3880 policy for additions in the range 10000-64999 inclusive is "First 3881 Come First Served" as described in [RFC5226]. 3883 In machine to machine applications, it is not expected that generic 3884 Internet media types such as text/plain, application/xml or 3885 application/octet-stream are useful for real applications in the long 3886 term. It is recommended that M2M applications making use of CoAP 3887 will request new Internet media types from IANA indicating semantic 3888 information about how to create or parse a payload. For example, a 3889 Smart Energy application payload carried as XML might request a more 3890 specific type like application/se+xml or application/se-exi. 3892 12.4. URI Scheme Registration 3894 This document requests the registration of the Uniform Resource 3895 Identifier (URI) scheme "coap". The registration request complies 3896 with [RFC4395]. 3898 URI scheme name. 3899 coap 3901 Status. 3902 Permanent. 3904 URI scheme syntax. 3905 Defined in Section 6.1 of [RFCXXXX]. 3907 URI scheme semantics. 3908 The "coap" URI scheme provides a way to identify resources that 3909 are potentially accessible over the Constrained Application 3910 Protocol (CoAP). The resources can be located by contacting the 3911 governing CoAP server and operated on by sending CoAP requests to 3912 the server. This scheme can thus be compared to the "http" URI 3913 scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of 3914 operation. 3916 Encoding considerations. 3917 The scheme encoding conforms to the encoding rules established for 3918 URIs in [RFC3986], i.e. internationalized and reserved characters 3919 are expressed using UTF-8-based percent-encoding. 3921 Applications/protocols that use this URI scheme name. 3922 The scheme is used by CoAP endpoints to access CoAP resources. 3924 Interoperability considerations. 3925 None. 3927 Security considerations. 3928 See Section 11.1 of [RFCXXXX]. 3930 Contact. 3931 IETF Chair 3933 Author/Change controller. 3934 IESG 3936 References. 3937 [RFCXXXX] 3939 12.5. Secure URI Scheme Registration 3941 This document requests the registration of the Uniform Resource 3942 Identifier (URI) scheme "coaps". The registration request complies 3943 with [RFC4395]. 3945 URI scheme name. 3946 coaps 3948 Status. 3949 Permanent. 3951 URI scheme syntax. 3952 Defined in Section 6.2 of [RFCXXXX]. 3954 URI scheme semantics. 3955 The "coaps" URI scheme provides a way to identify resources that 3956 are potentially accessible over the Constrained Application 3957 Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for 3958 transport security. The resources can be located by contacting 3959 the governing CoAP server and operated on by sending CoAP requests 3960 to the server. This scheme can thus be compared to the "https" 3961 URI scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details 3962 of operation. 3964 Encoding considerations. 3965 The scheme encoding conforms to the encoding rules established for 3966 URIs in [RFC3986], i.e. internationalized and reserved characters 3967 are expressed using UTF-8-based percent-encoding. 3969 Applications/protocols that use this URI scheme name. 3970 The scheme is used by CoAP endpoints to access CoAP resources 3971 using DTLS. 3973 Interoperability considerations. 3974 None. 3976 Security considerations. 3977 See Section 11.1 of [RFCXXXX]. 3979 Contact. 3980 IETF Chair 3982 Author/Change controller. 3983 IESG 3985 References. 3986 [RFCXXXX] 3988 12.6. Service Name and Port Number Registration 3990 One of the functions of CoAP is resource discovery: a CoAP client can 3991 ask a CoAP server about the resources offered by it (see Section 7). 3992 To enable resource discovery just based on the knowledge of an IP 3993 address, the CoAP port for resource discovery needs to be 3994 standardized. 3996 IANA has assigned the port number 5683 and the service name "coap", 3997 in accordance with [RFC6335]. 3999 Besides unicast, CoAP can be used with both multicast and anycast. 4001 Service Name. 4002 coap 4004 Transport Protocol. 4005 UDP 4007 Assignee. 4008 IESG 4010 Contact. 4011 IETF Chair 4013 Description. 4014 Constrained Application Protocol (CoAP) 4016 Reference. 4017 [RFCXXXX] 4019 Port Number. 4020 5683 4022 12.7. Secure Service Name and Port Number Registration 4024 CoAP resource discovery may also be provided using the DTLS-secured 4025 CoAP "coaps" scheme. Thus the CoAP port for secure resource 4026 discovery needs to be standardized. 4028 This document requests the assignment of the port number 4029 [IANA_TBD_PORT] and the service name "coaps", in accordance with 4030 [RFC6335]. 4032 Besides unicast, DTLS-secured CoAP can be used with anycast. 4034 Service Name. 4035 coaps 4037 Transport Protocol. 4038 UDP 4040 Assignee. 4041 IESG 4043 Contact. 4044 IETF Chair 4046 Description. 4047 DTLS-secured CoAP 4049 Reference. 4050 [RFCXXXX] 4052 Port Number. 4053 [IANA_TBD_PORT] 4055 12.8. Multicast Address Registration 4057 Section 8, "Multicast CoAP", defines the use of multicast. This 4058 document requests the assignment of the following multicast addresses 4059 for use by CoAP nodes: 4061 IPv4 -- "All CoAP Nodes" address [TBD1], from the IPv4 Multicast 4062 Address Space Registry. As the address is used for discovery that 4063 may span beyond a single network, it should come from the 4064 Internetwork Control Block (224.0.1.x, RFC 5771). 4066 IPv6 -- "All CoAP Nodes" address [TBD2], from the IPv6 Multicast 4067 Address Space Registry, in the Variable Scope Multicast Addresses 4068 space (RFC3307). Note that there is a distinct multicast address 4069 for each scope that interested CoAP nodes should listen to; CoAP 4070 needs the Link-Local and Site-Local scopes only. The address 4071 should be of the form FF0x::nn, where nn is a single byte, to 4072 ensure good compression of the local-scope address with [RFC6282]. 4074 [The explanatory text to be removed upon allocation of the addresses, 4075 except for the note about the distinct multicast addresses.] 4077 13. Acknowledgements 4079 Special thanks to Peter Bigot, Esko Dijk and Cullen Jennings for 4080 substantial contributions to the ideas and text in the document, 4081 along with countless detailed reviews and discussions. 4083 Thanks to Ed Beroset, Angelo P. Castellani, Gilbert Clark, Robert 4084 Cragie, Esko Dijk, Lisa Dussealt, Thomas Fossati, Tom Herbst, Richard 4085 Kelsey, Ari Keranen, Matthias Kovatsch, Salvatore Loreto, Kerry Lynn, 4086 Alexey Melnikov, Guido Moritz, Petri Mutka, Colin O'Flynn, Charles 4087 Palmer, Adriano Pezzuto, Robert Quattlebaum, Akbar Rahman, Eric 4088 Rescorla, David Ryan, Szymon Sasin, Michael Scharf, Dale Seed, Robby 4089 Simpson, Peter van der Stok, Michael Stuber, Linyi Tian, Gilman 4090 Tolle, Matthieu Vial and Alper Yegin for helpful comments and 4091 discussions that have shaped the document. 4093 Some of the text has been borrowed from the working documents of the 4094 IETF httpbis working group. 4096 14. References 4098 14.1. Normative References 4100 [I-D.farrell-decade-ni] 4101 Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 4102 Keranen, A., and P. Hallam-Baker, "Naming Things with 4103 Hashes", draft-farrell-decade-ni-10 (work in progress), 4104 August 2012. 4106 [I-D.ietf-tls-oob-pubkey] 4107 Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and 4108 T. Kivinen, "Out-of-Band Public Key Validation for 4109 Transport Layer Security (TLS)", 4110 draft-ietf-tls-oob-pubkey-06 (work in progress), 4111 October 2012. 4113 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4114 Extensions (MIME) Part One: Format of Internet Message 4115 Bodies", RFC 2045, November 1996. 4117 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4118 Extensions (MIME) Part Two: Media Types", RFC 2046, 4119 November 1996. 4121 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4122 Requirement Levels", BCP 14, RFC 2119, March 1997. 4124 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 4125 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 4126 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 4128 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 4129 Types", RFC 3023, January 2001. 4131 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 4132 10646", STD 63, RFC 3629, November 2003. 4134 [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", 4135 RFC 3676, February 2004. 4137 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4138 Resource Identifier (URI): Generic Syntax", STD 66, 4139 RFC 3986, January 2005. 4141 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 4142 for Transport Layer Security (TLS)", RFC 4279, 4143 December 2005. 4145 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 4146 Registration Procedures for New URI Schemes", BCP 35, 4147 RFC 4395, February 2006. 4149 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 4150 text/plain Media Type", RFC 5147, April 2008. 4152 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 4153 Interchange", RFC 5198, March 2008. 4155 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4156 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 4157 May 2008. 4159 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 4160 Specifications: ABNF", STD 68, RFC 5234, January 2008. 4162 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4163 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 4165 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4166 Housley, R., and W. Polk, "Internet X.509 Public Key 4167 Infrastructure Certificate and Certificate Revocation List 4168 (CRL) Profile", RFC 5280, May 2008. 4170 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4171 Uniform Resource Identifiers (URIs)", RFC 5785, 4172 April 2010. 4174 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 4175 Address Text Representation", RFC 5952, August 2010. 4177 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 4179 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 4180 Extension Definitions", RFC 6066, January 2011. 4182 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4183 Security Version 1.2", RFC 6347, January 2012. 4185 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 4186 Format", RFC 6690, August 2012. 4188 14.2. Informative References 4190 [EUI64] "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) 4191 REGISTRATION AUTHORITY", April 2010, . 4194 [EXIMIME] "Efficient XML Interchange (EXI) Format 1.0", 4195 December 2009, . 4198 [I-D.allman-tcpm-rto-consider] 4199 Allman, M., "Retransmission Timeout Considerations", 4200 draft-allman-tcpm-rto-consider-01 (work in progress), 4201 May 2012. 4203 [I-D.bormann-coap-misc] 4204 Bormann, C. and K. Hartke, "Miscellaneous additions to 4205 CoAP", draft-bormann-coap-misc-21 (work in progress), 4206 October 2012. 4208 [I-D.bormann-core-cross-reverse-convention] 4209 Bormann, C., "A convention for URIs operating a HTTP-CoAP 4210 reverse proxy", 4211 draft-bormann-core-cross-reverse-convention-00 (work in 4212 progress), December 2012. 4214 [I-D.bormann-core-ipsec-for-coap] 4215 Bormann, C., "Using CoAP with IPsec", 4216 draft-bormann-core-ipsec-for-coap-00 (work in progress), 4217 December 2012. 4219 [I-D.ietf-core-block] 4220 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 4221 draft-ietf-core-block-10 (work in progress), October 2012. 4223 [I-D.ietf-core-observe] 4224 Hartke, K., "Observing Resources in CoAP", 4225 draft-ietf-core-observe-07 (work in progress), 4226 October 2012. 4228 [I-D.mcgrew-tls-aes-ccm-ecc] 4229 McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 4230 CCM ECC Cipher Suites for TLS", 4231 draft-mcgrew-tls-aes-ccm-ecc-05 (work in progress), 4232 July 2012. 4234 [REST] Fielding, R., "Architectural Styles and the Design of 4235 Network-based Software Architectures", Ph.D. Dissertation, 4236 University of California, Irvine, 2000, . 4240 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4241 RFC 793, September 1981. 4243 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 4245 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 4246 with Session Description Protocol (SDP)", RFC 3264, 4247 June 2002. 4249 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4250 "Advanced Sockets Application Program Interface (API) for 4251 IPv6", RFC 3542, May 2003. 4253 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 4254 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 4255 for Transport Layer Security (TLS)", RFC 4492, May 2006. 4257 [RFC4627] Crockford, D., "The application/json Media Type for 4258 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 4260 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 4261 "Transmission of IPv6 Packets over IEEE 802.15.4 4262 Networks", RFC 4944, September 2007. 4264 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 4265 for Application Designers", BCP 145, RFC 5405, 4266 November 2008. 4268 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 4269 Protocol (XMPP): Core", RFC 6120, March 2011. 4271 [RFC6282] Hui, J. and P. Thubert, "Compression Format for IPv6 4272 Datagrams over IEEE 802.15.4-Based Networks", RFC 6282, 4273 September 2011. 4275 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 4276 Cheshire, "Internet Assigned Numbers Authority (IANA) 4277 Procedures for the Management of the Service Name and 4278 Transport Protocol Port Number Registry", BCP 165, 4279 RFC 6335, August 2011. 4281 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 4282 Transport Layer Security (TLS)", RFC 6655, July 2012. 4284 Appendix A. Examples 4286 This section gives a number of short examples with message flows for 4287 GET requests. These examples demonstrate the basic operation, the 4288 operation in the presence of retransmissions, and multicast. 4290 Figure 15 shows a basic GET request causing a piggy-backed response: 4291 The client sends a Confirmable GET request for the resource 4292 coap://server/temperature to the server with a Message ID of 0x7d34. 4293 The request includes one Uri-Path Option (Delta 0 + 11 = 11, Length 4294 11, Value "temperature"); the Token is left empty. This request is a 4295 total of 16 bytes long. A 2.05 (Content) response is returned in the 4296 Acknowledgement message that acknowledges the Confirmable request, 4297 echoing both the Message ID 0x7d34 and the empty Token value. The 4298 response includes a Payload of "22.3 C" and is 10 bytes long. 4300 Client Server 4301 | | 4302 | | 4303 +----->| Header: GET (T=CON, Code=1, MID=0x7d34) 4304 | GET | Uri-Path: "temperature" 4305 | | 4306 | | 4307 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d34) 4308 | 2.05 | Payload: "22.3 C" 4309 | | 4311 0 1 2 3 4312 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 4313 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4314 | 1 | 0 | 0 | GET=1 | MID=0x7d34 | 4315 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4316 | 11 | 11 | "temperature" (11 B) ... 4317 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4319 0 1 2 3 4320 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 4321 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4322 | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | 4323 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4324 |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... 4325 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4327 Figure 15: Confirmable request; piggy-backed response 4329 Figure 16 shows a similar example, but with the inclusion of an non- 4330 empty Token (Value 0x20) in the request and (Jump 15 + 4 = 19) in the 4331 response, increasing the sizes to 18 and 12 bytes, respectively. 4333 Client Server 4334 | | 4335 | | 4336 +----->| Header: GET (T=CON, Code=1, MID=0x7d35) 4337 | GET | Token: 0x20 4338 | | Uri-Path: "temperature" 4339 | | 4340 | | 4341 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d35) 4342 | 2.05 | Token: 0x20 4343 | | Payload: "22.3 C" 4344 | | 4346 0 1 2 3 4347 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 4348 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4349 | 1 | 0 | 1 | GET=1 | MID=0x7d35 | 4350 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4351 | 0x20 | 4352 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4353 | 11 | 11 | "temperature" (11 B) ... 4354 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4356 0 1 2 3 4357 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 4358 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4359 | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | 4360 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4361 | 0x20 | 4362 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4363 |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... 4364 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4366 Figure 16: Confirmable request; piggy-backed response 4368 In Figure 17, the Confirmable GET request is lost. After ACK_TIMEOUT 4369 seconds, the client retransmits the request, resulting in a piggy- 4370 backed response as in the previous example. 4372 Client Server 4373 | | 4374 | | 4375 +----X | Header: GET (T=CON, Code=1, MID=0x7d36) 4376 | GET | Token: 0x31 4377 | | Uri-Path: "temperature" 4378 TIMEOUT | 4379 | | 4380 +----->| Header: GET (T=CON, Code=1, MID=0x7d36) 4381 | GET | Token: 0x31 4382 | | Uri-Path: "temperature" 4383 | | 4384 | | 4385 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d36) 4386 | 2.05 | Token: 0x31 4387 | | Payload: "22.3 C" 4388 | | 4390 Figure 17: Confirmable request (retransmitted); piggy-backed response 4392 In Figure 18, the first Acknowledgement message from the server to 4393 the client is lost. After ACK_TIMEOUT seconds, the client 4394 retransmits the request. 4396 Client Server 4397 | | 4398 | | 4399 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 4400 | GET | Token: 0x42 4401 | | Uri-Path: "temperature" 4402 | | 4403 | | 4404 | X----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 4405 | 2.05 | Token: 0x42 4406 | | Payload: "22.3 C" 4407 TIMEOUT | 4408 | | 4409 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 4410 | GET | Token: 0x42 4411 | | Uri-Path: "temperature" 4412 | | 4413 | | 4414 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 4415 | 2.05 | Token: 0x42 4416 | | Payload: "22.3 C" 4417 | | 4419 Figure 18: Confirmable request; piggy-backed response (retransmitted) 4420 In Figure 19, the server acknowledges the Confirmable request and 4421 sends a 2.05 (Content) response separately in a Confirmable message. 4422 Note that the Acknowledgement message and the Confirmable response do 4423 not necessarily arrive in the same order as they were sent. The 4424 client acknowledges the Confirmable response. 4426 Client Server 4427 | | 4428 | | 4429 +----->| Header: GET (T=CON, Code=1, MID=0x7d38) 4430 | GET | Token: 0x53 4431 | | Uri-Path: "temperature" 4432 | | 4433 | | 4434 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d38) 4435 | | 4436 | | 4437 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7b) 4438 | 2.05 | Token: 0x53 4439 | | Payload: "22.3 C" 4440 | | 4441 | | 4442 +- - ->| Header: (T=ACK, Code=0, MID=0xad7b) 4443 | | 4445 Figure 19: Confirmable request; separate response 4447 Figure 20 shows an example where the client loses its state (e.g., 4448 crashes and is rebooted) right after sending a Confirmable request, 4449 so the separate response arriving some time later comes unexpected. 4450 In this case, the client rejects the Confirmable response with a 4451 Reset message. Note that the unexpected ACK is silently ignored. 4453 Client Server 4454 | | 4455 | | 4456 +----->| Header: GET (T=CON, Code=1, MID=0x7d39) 4457 | GET | Token: 0x64 4458 | | Uri-Path: "temperature" 4459 CRASH | 4460 | | 4461 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d39) 4462 | | 4463 | | 4464 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7c) 4465 | 2.05 | Token: 0x64 4466 | | Payload: "22.3 C" 4467 | | 4468 | | 4469 +- - ->| Header: (T=RST, Code=0, MID=0xad7c) 4470 | | 4472 Figure 20: Confirmable request; separate response (unexpected) 4474 Figure 21 shows a basic GET request where the request and the 4475 response are non-confirmable, so both may be lost without notice. 4477 Client Server 4478 | | 4479 | | 4480 +----->| Header: GET (T=NON, Code=1, MID=0x7d40) 4481 | GET | Token: 0x75 4482 | | Uri-Path: "temperature" 4483 | | 4484 | | 4485 |<-----+ Header: 2.05 Content (T=NON, Code=69, MID=0xad7d) 4486 | 2.05 | Token: 0x75 4487 | | Payload: "22.3 C" 4488 | | 4490 Figure 21: Non-confirmable request; Non-confirmable response 4492 In Figure 22, the client sends a Non-confirmable GET request to a 4493 multicast address: all nodes in link-local scope. There are 3 4494 servers on the link: A, B and C. Servers A and B have a matching 4495 resource, therefore they send back a Non-confirmable 2.05 (Content) 4496 response. The response sent by B is lost. C does not have matching 4497 response, therefore it sends a Non-confirmable 4.04 (Not Found) 4498 response. 4500 Client ff02::1 A B C 4501 | | | | | 4502 | | | | | 4503 +------>| | | | Header: GET (T=NON, Code=1, MID=0x7d41) 4504 | GET | | | | Token: 0x86 4505 | | | | Uri-Path: "temperature" 4506 | | | | 4507 | | | | 4508 |<------------+ | | Header: 2.05 (T=NON, Code=69, MID=0x60b1) 4509 | 2.05 | | | Token: 0x86 4510 | | | | Payload: "22.3 C" 4511 | | | | 4512 | | | | 4513 | X------------+ | Header: 2.05 (T=NON, Code=69, MID=0x01a0) 4514 | 2.05 | | | Token: 0x86 4515 | | | | Payload: "20.9 C" 4516 | | | | 4517 | | | | 4518 |<------------------+ Header: 4.04 (T=NON, Code=132, MID=0x952a) 4519 | 4.04 | | | Token: 0x86 4520 | | | | 4522 Figure 22: Non-confirmable request (multicast); Non-confirmable 4523 response 4525 Appendix B. URI Examples 4527 The following examples demonstrate different sets of Uri options, and 4528 the result after constructing an URI from them. 4530 o coap://[2001:db8::2:1]/ 4532 Destination IP Address = [2001:db8::2:1] 4534 Destination UDP Port = 5683 4536 o coap://example.net/ 4538 Destination IP Address = [2001:db8::2:1] 4540 Destination UDP Port = 5683 4542 Uri-Host = "example.net" 4544 o coap://example.net/.well-known/core 4545 Destination IP Address = [2001:db8::2:1] 4547 Destination UDP Port = 5683 4549 Uri-Host = "example.net" 4551 Uri-Path = ".well-known" 4553 Uri-Path = "core" 4555 o coap:// 4556 xn--18j4d.example/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF 4558 Destination IP Address = [2001:db8::2:1] 4560 Destination UDP Port = 5683 4562 Uri-Host = "xn--18j4d.example" 4564 Uri-Path = the string composed of the Unicode characters U+3053 4565 U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as 4566 E38193E38293E381ABE381A1E381AF hexadecimal 4568 o coap://198.51.100.1:61616//%2F//?%2F%2F&?%26 4570 Destination IP Address = 198.51.100.1 4572 Destination UDP Port = 61616 4574 Uri-Path = "" 4576 Uri-Path = "/" 4578 Uri-Path = "" 4580 Uri-Path = "" 4582 Uri-Query = "//" 4584 Uri-Query = "?&" 4586 Appendix C. Changelog 4588 Changed from ietf-12 to ietf-13: 4590 o Simplified message format. 4592 * Removed the OC (Option Count) field in the CoAP Header. 4594 * Changed the End-of-Options Marker into the Payload Marker. 4596 * Changed the format of Options: use 4 bits for option length and 4597 delta; insert one or two additional bytes after the option 4598 header if necessary. 4600 * Promoted the Token Option to a field following the CoAP Header. 4602 o Clarified when a payload is a diagnostic payload (#264). 4604 o Moved IPsec discussion to separate draft (#262). 4606 o Added a reference to a separate draft on reverse-proxy URI 4607 embedding (#259). 4609 o Clarified the use of ETags and of 2.03 responses (#265, #254, 4610 #256). 4612 o Added reserved Location-* numbers and clarified Location-*. 4614 o Added Proxy-Scheme proposal. 4616 o Clarified terms such as content negotiation, selected 4617 representation, representation-format, message format error. 4619 o Numerous clarifications and a few bugfixes. 4621 Changed from ietf-11 to ietf-12: 4623 o Extended options to support lengths of up to 1034 bytes (#202). 4625 o Added new Jump mechanism for options and removed Fenceposting 4626 (#214). 4628 o Added new IANA option number registration policy (#214). 4630 o Added Proxy Unsafe/Safe and Cache-Key masking to option numbers 4631 (#241). 4633 o Re-numbered option numbers to use Unsafe/Safe and Cache-Key 4634 compliant numbers (#241). 4636 o Defined NSTART and restricted the value to 1 with a MUST (#215). 4638 o Defined PROBING_RATE and set it to 1 Byte/second (#215). 4640 o Defined DEFAULT_LEISURE (#246). 4642 o Renamed Content-Type into Content-Format, and Media Type registry 4643 into Content-Format registry. 4645 o A large number of small editorial changes, clarifications and 4646 improvements have been made. 4648 Changed from ietf-10 to ietf-11: 4650 o Expanded section 4.8 on Transmission Parameters, and used the 4651 derived values defined there (#201). Changed parameter names to 4652 be shorter and more to the point. 4654 o Several more small editorial changes, clarifications and 4655 improvements have been made. 4657 Changed from ietf-09 to ietf-10: 4659 o Option deltas are restricted to 0 to 14; the option delta 15 is 4660 used exclusively for the end-of-options marker (#239). 4662 o Option numbers that are a multiple of 14 are not reserved, but are 4663 required to have an empty default value (#212). 4665 o Fixed misleading language that was introduced in 5.10.2 in coap-07 4666 re Uri-Host and Uri-Port (#208). 4668 o Segments and arguments can have a length of zero characters 4669 (#213). 4671 o The Location-* options describe together describe one location. 4672 The location is a relative URI, not an "absolute path URI" (#218). 4674 o The value of the Location-Path Option must not be '.' or '..' 4675 (#218). 4677 o Added a sentence on constructing URIs from Location-* options 4678 (#231). 4680 o Reserved option numbers for future Location-* options (#230). 4682 o Fixed response codes with payload inconsistency (#233). 4684 o Added advice on default values for critical options (#207). 4686 o Clarified use of identifiers in RawPublicKey Mode Provisioning 4687 (#222). 4689 o Moved "Securing CoAP" out of the "Security Considerations" (#229). 4691 o Added "All CoAP Nodes" multicast addresses to "IANA 4692 Considerations" (#216). 4694 o Over 100 small editorial changes, clarifications and improvements 4695 have been made. 4697 Changed from ietf-08 to ietf-09: 4699 o Improved consistency of statements about RST on NON: RST is a 4700 valid response to a NON message (#183). 4702 o Clarified that the protocol constants can be configured for 4703 specific application environments. 4705 o Added implementation note recommending piggy-backing whenever 4706 possible (#182). 4708 o Added a content-encoding column to the media type registry (#181). 4710 o Minor improvements to Appendix D. 4712 o Added text about multicast response suppression (#177). 4714 o Included the new End-of-options Marker (#176). 4716 o Added a reference to draft-ietf-tls-oob-pubkey and updated the RPK 4717 text accordingly. 4719 Changed from ietf-07 to ietf-08: 4721 o Clarified matching rules for messages (#175) 4723 o Fixed a bug in Section 8.2.2 on Etags (#168) 4725 o Added an IP address spoofing threat analysis contribution (#167) 4727 o Re-focused the security section on raw public keys (#166) 4729 o Added an 4.06 error to Accept (#165) 4731 Changed from ietf-06 to ietf-07: 4733 o application/link-format added to Media types registration (#160) 4735 o Moved content-type attribute to the document from link-format. 4737 o Added coaps scheme and DTLS-secured CoAP default port (#154) 4739 o Allowed 0-length Content-type options (#150) 4741 o Added congestion control recommendations (#153) 4743 o Improved text on PUT/POST response payloads (#149) 4745 o Added an Accept option for content-negotiation (#163) 4747 o Added If-Match and If-None-Match options (#155) 4749 o Improved Token Option explanation (#147) 4751 o Clarified mandatory to implement security (#156) 4753 o Added first come first server policy for 2-byte Media type codes 4754 (#161) 4756 o Clarify matching rules for messages and tokens (#151) 4758 o Changed OPTIONS and TRACE to always return 501 in HTTP-CoAP 4759 mapping (#164) 4761 Changed from ietf-05 to ietf-06: 4763 o HTTP mapping section improved with the minimal protocol standard 4764 text for CoAP-HTTP and HTTP-CoAP forward proxying (#137). 4766 o Eradicated percent-encoding by including one Uri-Query Option per 4767 &-delimited argument in a query. 4769 o Allowed RST message in reply to a NON message with unexpected 4770 token (#135). 4772 o Cache Invalidation only happens upon successful responses (#134). 4774 o 50% jitter added to the initial retransmit timer (#142). 4776 o DTLS cipher suites aligned with ZigBee IP, DTLS clarified as 4777 default CoAP security mechanism (#138, #139) 4779 o Added a minimal reference to draft-kivinen-ipsecme-ikev2-minimal 4780 (#140). 4782 o Clarified the comparison of UTF-8s (#136). 4784 o Minimized the initial media type registry (#101). 4786 Changed from ietf-04 to ietf-05: 4788 o Renamed Immediate into Piggy-backed and Deferred into Separate -- 4789 should finally end the confusion on what this is about. 4791 o GET requests now return a 2.05 (Content) response instead of 2.00 4792 (OK) response (#104). 4794 o Added text to allow 2.02 (Deleted) responses in reply to POST 4795 requests (#105). 4797 o Improved message deduplication rules (#106). 4799 o Section added on message size implementation considerations 4800 (#103). 4802 o Clarification made on human readable error payloads (#109). 4804 o Definition of CoAP methods improved (#108). 4806 o Max-Age removed from requests (#107). 4808 o Clarified uniqueness of tokens (#112). 4810 o Location-Query Option added (#113). 4812 o ETag length set to 1-8 bytes (#123). 4814 o Clarified relation between elective/critical and option numbers 4815 (#110). 4817 o Defined when to update Version header field (#111). 4819 o URI scheme registration improved (#102). 4821 o Added review guidelines for new CoAP codes and numbers. 4823 Changes from ietf-03 to ietf-04: 4825 o Major document reorganization (#51, #63, #71, #81). 4827 o Max-age length set to 0-4 bytes (#30). 4829 o Added variable unsigned integer definition (#31). 4831 o Clarification made on human readable error payloads (#50). 4833 o Definition of POST improved (#52). 4835 o Token length changed to 0-8 bytes (#53). 4837 o Section added on multiplexing CoAP, DTLS and STUN (#56). 4839 o Added cross-protocol attack considerations (#61). 4841 o Used new Immediate/Deferred response definitions (#73). 4843 o Improved request/response matching rules (#74). 4845 o Removed unnecessary media types and added recommendations for 4846 their use in M2M (#76). 4848 o Response codes changed to base 32 coding, new Y.XX naming (#77). 4850 o References updated as per AD review (#79). 4852 o IANA section completed (#80). 4854 o Proxy-Uri Option added to disambiguate between proxy and non-proxy 4855 requests (#82). 4857 o Added text on critical options in cached states (#83). 4859 o HTTP mapping sections improved (#88). 4861 o Added text on reverse proxies (#72). 4863 o Some security text on multicast added (#54). 4865 o Trust model text added to introduction (#58, #60). 4867 o AES-CCM vs. AES-CCB text added (#55). 4869 o Text added about device capabilities (#59). 4871 o DTLS section improvements (#87). 4873 o Caching semantics aligned with RFC2616 (#78). 4875 o Uri-Path Option split into multiple path segments. 4877 o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. 4879 Changes from ietf-02 to ietf-03: 4881 o Token Option and related use in asynchronous requests added (#25). 4883 o CoAP specific error codes added (#26). 4885 o Erroring out on unknown critical options changed to a MUST (#27). 4887 o Uri-Query Option added. 4889 o Terminology and definitions of URIs improved. 4891 o Security section completed (#22). 4893 Changes from ietf-01 to ietf-02: 4895 o Sending an error on a critical option clarified (#18). 4897 o Clarification on behavior of PUT and idempotent operations (#19). 4899 o Use of Uri-Authority clarified along with server processing rules; 4900 Uri-Scheme Option removed (#20, #23). 4902 o Resource discovery section removed to a separate CoRE Link Format 4903 draft (#21). 4905 o Initial security section outline added. 4907 Changes from ietf-00 to ietf-01: 4909 o New cleaner transaction message model and header (#5). 4911 o Removed subscription while being designed (#1). 4913 o Section 2 re-written (#3). 4915 o Text added about use of short URIs (#4). 4917 o Improved header option scheme (#5, #14). 4919 o Date option removed whiled being designed (#6). 4921 o New text for CoAP default port (#7). 4923 o Completed proxying section (#8). 4925 o Completed resource discovery section (#9). 4927 o Completed HTTP mapping section (#10). 4929 o Several new examples added (#11). 4931 o URI split into 3 options (#12). 4933 o MIME type defined for link-format (#13, #16). 4935 o New text on maximum message size (#15). 4937 o Location Option added. 4939 Changes from shelby-01 to ietf-00: 4941 o Removed the TCP binding section, left open for the future. 4943 o Fixed a bug in the example. 4945 o Marked current Sub/Notify as (Experimental) while under WG 4946 discussion. 4948 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 4949 CoAP-CoAP proxying to work). 4951 o Temporarily removed the Magic Byte header as TCP is no longer 4952 included as a binding. 4954 o Removed the Uri-code Option as different URI encoding schemes are 4955 being discussed. 4957 o Changed the rel= field to desc= for resource discovery. 4959 o Changed the maximum message size to 1024 bytes to allow for IP/UDP 4960 headers. 4962 o Made the URI slash optimization and method idempotence MUSTs 4964 o Minor editing and bug fixing. 4966 Changes from shelby-00 to shelby-01: 4968 o Unified the message header and added a notify message type. 4970 o Renamed methods with HTTP names and removed the NOTIFY method. 4972 o Added a number of options field to the header. 4974 o Combines the Option Type and Length into an 8-bit field. 4976 o Added the magic byte header. 4978 o Added new ETag Option. 4980 o Added new Date Option. 4982 o Added new Subscription Option. 4984 o Completed the HTTP Code - CoAP Code mapping table appendix. 4986 o Completed the Content-type Identifier appendix and tables. 4988 o Added more simplifications for URI support. 4990 o Initial subscription and discovery sections. 4992 o A Flag requirements simplified. 4994 Authors' Addresses 4996 Zach Shelby 4997 Sensinode 4998 Kidekuja 2 4999 Vuokatti 88600 5000 Finland 5002 Phone: +358407796297 5003 Email: zach@sensinode.com 5005 Klaus Hartke 5006 Universitaet Bremen TZI 5007 Postfach 330440 5008 Bremen D-28359 5009 Germany 5011 Phone: +49-421-218-63905 5012 Email: hartke@tzi.org 5013 Carsten Bormann 5014 Universitaet Bremen TZI 5015 Postfach 330440 5016 Bremen D-28359 5017 Germany 5019 Phone: +49-421-218-63921 5020 Email: cabo@tzi.org 5022 Brian Frank 5023 SkyFoundry 5024 Richmond, VA 5025 USA 5027 Phone: 5028 Email: brian@skyfoundry.com