idnits 2.17.1 draft-ietf-core-coap-15.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 4633 has weird spacing: '... Client ff02:...' -- The document date (April 14, 2013) is 4023 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 485, but not defined == Missing Reference: '0x01a0' is mentioned on line 500, but not defined == Missing Reference: '0xbc90' is mentioned on line 542, but not defined == Missing Reference: '0xbc91' is mentioned on line 542, but not defined == Missing Reference: '0x7a10' is mentioned on line 566, but not defined == Missing Reference: '0x23bb' is mentioned on line 577, but not defined == Missing Reference: '0x7a11' is mentioned on line 590, but not defined == Missing Reference: '0x23bc' is mentioned on line 595, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 4158, but not defined == Missing Reference: 'TBD1' is mentioned on line 4169, but not defined == Missing Reference: 'TBD2' is mentioned on line 4174, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-tls-oob-pubkey-07 == Outdated reference: A later version (-08) exists of draft-mcgrew-tls-aes-ccm-ecc-06 ** Downref: Normative reference to an Informational draft: draft-mcgrew-tls-aes-ccm-ecc (ref. 'I-D.mcgrew-tls-aes-ccm-ecc') ** 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-24 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-11 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-08 == Outdated reference: A later version (-07) exists of draft-ietf-lwig-terminology-03 -- 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: 9 errors (**), 0 flaws (~~), 21 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: October 16, 2013 C. Bormann 6 Universitaet Bremen TZI 7 April 14, 2013 9 Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-15 12 Abstract 14 The Constrained Application Protocol (CoAP) is a specialized web 15 transfer protocol for use with constrained nodes and constrained 16 (e.g., low-power, lossy) networks. The nodes often have 8-bit 17 microcontrollers with small amounts of ROM and RAM, while constrained 18 networks such as 6LoWPAN often have high packet error rates and a 19 typical throughput of 10s of kbit/s. The protocol is designed for 20 machine-to-machine (M2M) applications such as smart energy and 21 building automation. 23 CoAP provides a request/response interaction model between 24 application endpoints, supports built-in discovery of services and 25 resources, and includes key concepts of the Web such as URIs and 26 Internet media types. CoAP easily interfaces with HTTP for 27 integration with the Web while meeting specialized requirements such 28 as multicast support, very low overhead and simplicity for 29 constrained environments. 31 Status of this Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on October 16, 2013. 48 Copyright Notice 49 Copyright (c) 2013 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 65 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 5 66 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 67 2. Constrained Application Protocol . . . . . . . . . . . . . . 9 68 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 10 69 2.2. Request/Response Model . . . . . . . . . . . . . . . . . 11 70 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 14 71 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . 14 72 3. Message Format . . . . . . . . . . . . . . . . . . . . . . . 15 73 3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 16 74 3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 18 75 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 19 76 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20 77 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 20 78 4.3. Messages Transmitted Without Reliability . . . . . . . . 21 79 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 22 80 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 22 81 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 23 82 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 24 83 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 25 84 4.8.1. Changing The Parameters . . . . . . . . . . . . . . . 25 85 4.8.2. Time Values derived from Transmission Parameters . . 26 86 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 28 87 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 29 88 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 29 89 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 30 90 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 31 91 5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 32 92 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 32 93 5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 32 94 5.3.2. Request/Response Matching Rules . . . . . . . . . . . 33 95 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 33 96 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 34 97 5.4.2. Proxy Unsafe/Safe and Cache-Key . . . . . . . . . . . 35 98 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 36 99 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 36 100 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 36 101 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 36 102 5.5. Payloads and Representations . . . . . . . . . . . . . . 37 103 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 37 104 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 38 105 5.5.3. Selected Representation . . . . . . . . . . . . . . . 38 106 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 39 107 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 39 108 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 40 109 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 40 110 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 40 111 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 41 112 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 42 113 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 43 114 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 43 115 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 44 116 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 44 117 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 44 118 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 45 119 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 45 120 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 45 121 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 46 122 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 48 123 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 48 124 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 49 125 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 50 126 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 51 127 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 51 128 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . . 51 129 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 52 130 5.10.7. Location-Path and Location-Query . . . . . . . . . . 53 131 5.10.8. Conditional Request Options . . . . . . . . . . . . . 54 132 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 55 133 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 55 134 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 56 135 6.3. Normalization and Comparison Rules . . . . . . . . . . . 56 136 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 57 137 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 58 138 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 59 139 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 59 140 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 60 141 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 60 142 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 61 143 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 61 144 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 61 145 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 62 146 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 63 147 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 63 148 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 64 149 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 66 150 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 66 151 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 66 152 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 68 153 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 69 154 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 70 155 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 70 156 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 71 157 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 71 158 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 71 159 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . . 72 160 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . . 72 161 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 72 162 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 73 163 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 73 164 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 73 165 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 73 166 11. Security Considerations . . . . . . . . . . . . . . . . . . . 74 167 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . . 74 168 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 74 169 11.3. Risk of amplification . . . . . . . . . . . . . . . . . . 75 170 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . . 76 171 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 77 172 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 173 12.1. CoAP Code Registry . . . . . . . . . . . . . . . . . . . 79 174 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 80 175 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 81 176 12.2. Option Number Registry . . . . . . . . . . . . . . . . . 82 177 12.3. Content-Format Registry . . . . . . . . . . . . . . . . . 84 178 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 85 179 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 86 180 12.6. Service Name and Port Number Registration . . . . . . . . 87 181 12.7. Secure Service Name and Port Number Registration . . . . 88 182 12.8. Multicast Address Registration . . . . . . . . . . . . . 89 183 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 89 184 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 90 185 14.1. Normative References . . . . . . . . . . . . . . . . . . 90 186 14.2. Informative References . . . . . . . . . . . . . . . . . 92 187 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 94 188 Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 100 189 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 102 190 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 111 192 1. Introduction 194 The use of web services (web APIs) on the Internet has become 195 ubiquitous in most applications, and depends on the fundamental 196 Representational State Transfer [REST] architecture of the web. 198 The Constrained RESTful Environments (CoRE) work aims at realizing 199 the REST architecture in a suitable form for the most constrained 200 nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and 201 networks (e.g. 6LoWPAN, [RFC4944]). Constrained networks like 202 6LoWPAN support the expensive fragmentation of IPv6 packets into 203 small link-layer frames. One design goal of CoAP has been to keep 204 message overhead small, thus limiting the use of fragmentation. 206 One of the main goals of CoAP is to design a generic web protocol for 207 the special requirements of this constrained environment, especially 208 considering energy, building automation and other machine-to-machine 209 (M2M) applications. The goal of CoAP is not to blindly compress HTTP 210 [RFC2616], but rather to realize a subset of REST common with HTTP 211 but optimized for M2M applications. Although CoAP could be used for 212 compressing simple HTTP interfaces, it more importantly also offers 213 features for M2M such as built-in discovery, multicast support and 214 asynchronous message exchanges. 216 This document specifies the Constrained Application Protocol (CoAP), 217 which easily translates to HTTP for integration with the existing web 218 while meeting specialized requirements such as multicast support, 219 very low overhead and simplicity for constrained environments and M2M 220 applications. 222 1.1. Features 224 CoAP has the following main features: 226 o Constrained web protocol fulfilling M2M requirements. 228 o UDP [RFC0768] binding with optional reliability supporting unicast 229 and multicast requests. 231 o Asynchronous message exchanges. 233 o Low header overhead and parsing complexity. 235 o URI and Content-type support. 237 o Simple proxy and caching capabilities. 239 o A stateless HTTP mapping, allowing proxies to be built providing 240 access to CoAP resources via HTTP in a uniform way or for HTTP 241 simple interfaces to be realized alternatively over CoAP. 243 o Security binding to Datagram Transport Layer Security (DTLS) 244 [RFC6347]. 246 1.2. Terminology 248 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 249 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 250 "OPTIONAL" in this document are to be interpreted as described in 251 [RFC2119] when they appear in ALL CAPS. These words may also appear 252 in this document in lower case as plain English words, absent their 253 normative meanings. 255 This specification requires readers to be familiar with all the terms 256 and concepts that are discussed in [RFC2616], including "resource", 257 "representation", "cache", and "fresh". In addition, this 258 specification defines the following terminology: 260 Endpoint 261 An entity participating in the CoAP protocol. Colloquially, an 262 endpoint lives on a "Node", although "Host" would be more 263 consistent with Internet standards usage, and is further 264 identified by transport layer multiplexing information that can 265 include a UDP port number and a security association 266 (Section 4.1). 268 Sender 269 The originating endpoint of a message. When the aspect of 270 identification of the specific sender is in focus, also "source 271 endpoint". 273 Recipient 274 The destination endpoint of a message. When the aspect of 275 identification of the specific recipient is in focus, also 276 "destination endpoint". 278 Client 279 The originating endpoint of a request; the destination endpoint of 280 a response. 282 Server 283 The destination endpoint of a request; the originating endpoint of 284 a response. 286 Origin Server 287 The server on which a given resource resides or is to be created. 289 Intermediary 290 A CoAP endpoint that acts both as a server and as a client towards 291 (possibly via further intermediaries) an origin server. A common 292 form of an intermediary is a proxy; several classes of such 293 proxies are discussed in this specification. 295 Proxy 296 An intermediary that mainly is concerned with forwarding requests 297 and relaying back responses, possibly performing caching, 298 namespace translation, or protocol translation in the process. As 299 opposed to intermediaries in the general sense, proxies generally 300 do not implement specific application semantics. Based on the 301 position in the overall structure of the request forwarding, there 302 are two common forms of proxy: forward-proxy and reverse-proxy. 303 In some cases, a single endpoint might act as an origin server, 304 forward-proxy, or reverse-proxy, switching behavior based on the 305 nature of each request. 307 Forward-Proxy 308 A "forward-proxy" is an endpoint selected by a client, usually via 309 local configuration rules, to perform requests on behalf of the 310 client, doing any necessary translations. Some translations are 311 minimal, such as for proxy requests for "coap" URIs, whereas other 312 requests might require translation to and from entirely different 313 application-layer protocols. 315 Reverse-Proxy 316 A "reverse-proxy" is an endpoint that stands in for one or more 317 other server(s) and satisfies requests on behalf of these, doing 318 any necessary translations. Unlike a forward-proxy, the client 319 may not be aware that it is communicating with a reverse-proxy; a 320 reverse-proxy receives requests as if it was the origin server for 321 the target resource. 323 Cross-Proxy 324 A cross-protocol proxy, or "cross-proxy" for short, is a proxy 325 that translates between different protocols, such as a CoAP-to- 326 HTTP proxy or an HTTP-to-CoAP proxy. While this specification 327 makes very specific demands of CoAP-to-CoAP proxies, there is more 328 variation possible in cross-proxies. 330 Confirmable Message 331 Some messages require an acknowledgement. These messages are 332 called "Confirmable". When no packets are lost, each Confirmable 333 message elicits exactly one return message of type Acknowledgement 334 or type Reset. 336 Non-confirmable Message 337 Some other messages do not require an acknowledgement. This is 338 particularly true for messages that are repeated regularly for 339 application requirements, such as repeated readings from a sensor. 341 Acknowledgement Message 342 An Acknowledgement message acknowledges that a specific 343 Confirmable Message arrived. It does not indicate success or 344 failure of any encapsulated request. 346 Reset Message 347 A Reset message indicates that a specific message (Confirmable or 348 Non-confirmable) was received, but some context is missing to 349 properly process it. This condition is usually caused when the 350 receiving node has rebooted and has forgotten some state that 351 would be required to interpret the message. Provoking a Reset 352 message (e.g., by sending an empty Confirmable message) is also 353 useful as an inexpensive check of the liveness of an endpoint 354 ("CoAP ping"). 356 Piggy-backed Response 357 A Piggy-backed Response is included right in a CoAP 358 Acknowledgement (ACK) message that is sent to acknowledge receipt 359 of the Request for this Response (Section 5.2.1). 361 Separate Response 362 When a Confirmable message carrying a Request is acknowledged with 363 an empty message (e.g., because the server doesn't have the answer 364 right away), a Separate Response is sent in a separate message 365 exchange (Section 5.2.2). 367 Critical Option 368 An option that would need to be understood by the endpoint 369 receiving the message in order to properly process the message 370 (Section 5.4.1). Note that the implementation of critical options 371 is, as the name "Option" implies, generally optional: unsupported 372 critical options lead to an error response or summary rejection of 373 the message. 375 Elective Option 376 An option that is intended to be ignored by an endpoint that does 377 not understand it. Processing the message even without 378 understanding the option is acceptable (Section 5.4.1). 380 Unsafe Option 381 An option that would need to be understood by a proxy receiving 382 the message in order to safely forward the message 383 (Section 5.4.2). 385 Safe Option 386 An option that is intended to be safe for forwarding by a proxy 387 that does not understand it. Forwarding the message even without 388 understanding the option is acceptable (Section 5.4.2). 390 Resource Discovery 391 The process where a CoAP client queries a server for its list of 392 hosted resources (i.e., links, Section 7). 394 Content-Format 395 The combination of an Internet media type, potentially with 396 specific parameters given, and a content-coding (which is often 397 the identity content-coding), identified by a numeric identifier 398 defined by the CoAP Content-Format registry. When the focus is 399 less on the numeric identifier than on the combination of these 400 characteristics of a resource representation, this is also called 401 "representation format". 403 Additional terminology for constrained nodes and constrained node 404 networks can be found in [I-D.ietf-lwig-terminology]. 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: 430 Confirmable, Non-confirmable, Acknowledgement, Reset; method codes 431 and response codes included in some of these messages make them carry 432 requests or responses. The basic exchanges of the four types of 433 messages are somewhat orthogonal to the request/response 434 interactions; requests can be carried in Confirmable and Non- 435 confirmable messages, and responses can be carried in these as well 436 as piggy-backed in Acknowledgement messages. 438 One could think of CoAP logically as using a two-layer approach, a 439 CoAP messaging layer used to deal with UDP and the asynchronous 440 nature of the interactions, and the request/response interactions 441 using Method and Response codes (see Figure 1). CoAP is however a 442 single protocol, with messaging and request/response just features of 443 the CoAP header. 445 +----------------------+ 446 | Application | 447 +----------------------+ 448 +----------------------+ \ 449 | Requests/Responses | | 450 |----------------------| | CoAP 451 | Messages | | 452 +----------------------+ / 453 +----------------------+ 454 | UDP | 455 +----------------------+ 457 Figure 1: Abstract layering of CoAP 459 2.1. Messaging Model 461 The CoAP messaging model is based on the exchange of messages over 462 UDP between endpoints. 464 CoAP uses a short fixed-length binary header (4 bytes) that may be 465 followed by compact binary options and a payload. This message 466 format is shared by requests and responses. The CoAP message format 467 is specified in Section 3. Each message contains a Message ID used 468 to detect duplicates and for optional reliability. 470 Reliability is provided by marking a message as Confirmable (CON). A 471 Confirmable message is retransmitted using a default timeout and 472 exponential back-off between retransmissions, until the recipient 473 sends an Acknowledgement message (ACK) with the same Message ID (for 474 example, 0x7d34) from the corresponding endpoint; see Figure 2. When 475 a recipient is not at all able to process a Confirmable message 476 (i.e., not even able to provide a suitable error response), it 477 replies with a Reset message (RST) instead of an Acknowledgement 478 (ACK). 480 Client Server 481 | | 482 | CON [0x7d34] | 483 +----------------->| 484 | | 485 | ACK [0x7d34] | 486 |<-----------------+ 487 | | 489 Figure 2: Reliable message transmission 491 A message that does not require reliable transmission, for example 492 each single measurement out of a stream of sensor data, can be sent 493 as a Non-confirmable message (NON). These are not acknowledged, but 494 still have a Message ID for duplicate detection; see Figure 3. When 495 a recipient is not able to process a Non-confirmable message, it may 496 reply with a Reset message (RST). 498 Client Server 499 | | 500 | NON [0x01a0] | 501 +----------------->| 502 | | 504 Figure 3: Unreliable message transmission 506 See Section 4 for details of CoAP messages. 508 As CoAP is based on UDP, it also supports the use of multicast IP 509 destination addresses, enabling multicast CoAP requests. Section 8 510 discusses the proper use of CoAP messages with multicast addresses 511 and precautions for avoiding response congestion. 513 Several security modes are defined for CoAP in Section 9 ranging from 514 no security to certificate-based security. This document specifies a 515 binding to DTLS for securing the protocol; the use of IPsec with CoAP 516 is discussed in [I-D.bormann-core-ipsec-for-coap]. 518 2.2. Request/Response Model 520 CoAP request and response semantics are carried in CoAP messages, 521 which include either a Method code or Response code, respectively. 522 Optional (or default) request and response information, such as the 523 URI and payload media type are carried as CoAP options. A Token is 524 used to match responses to requests independently from the underlying 525 messages (Section 5.3). 527 A request is carried in a Confirmable (CON) or Non-confirmable (NON) 528 message, and if immediately available, the response to a request 529 carried in a Confirmable message is carried in the resulting 530 Acknowledgement (ACK) message. This is called a piggy-backed 531 response, detailed in Section 5.2.1. Two examples for a basic GET 532 request with piggy-backed response are shown in Figure 4, one 533 successful, one resulting in a 4.04 (Not Found) response. 535 Client Server Client Server 536 | | | | 537 | CON [0xbc90] | | CON [0xbc91] | 538 | GET /temperature | | GET /temperature | 539 | (Token 0x71) | | (Token 0x72) | 540 +----------------->| +----------------->| 541 | | | | 542 | ACK [0xbc90] | | ACK [0xbc91] | 543 | 2.05 Content | | 4.04 Not Found | 544 | (Token 0x71) | | (Token 0x72) | 545 | "22.5 C" | | "Not found" | 546 |<-----------------+ |<-----------------+ 547 | | | | 549 Figure 4: Two GET requests with piggy-backed responses 551 If the server is not able to respond immediately to a request carried 552 in a Confirmable message, it simply responds with an empty 553 Acknowledgement message so that the client can stop retransmitting 554 the request. When the response is ready, the server sends it in a 555 new Confirmable message (which then in turn needs to be acknowledged 556 by the client). This is called a separate response, as illustrated 557 in Figure 5 and described in more detail in Section 5.2.2. 559 Client Server 560 | | 561 | CON [0x7a10] | 562 | GET /temperature | 563 | (Token 0x73) | 564 +----------------->| 565 | | 566 | ACK [0x7a10] | 567 |<-----------------+ 568 | | 569 ... Time Passes ... 570 | | 571 | CON [0x23bb] | 572 | 2.05 Content | 573 | (Token 0x73) | 574 | "22.5 C" | 575 |<-----------------+ 576 | | 577 | ACK [0x23bb] | 578 +----------------->| 579 | | 581 Figure 5: A GET request with a separate response 583 Likewise, if a request is sent in a Non-confirmable message, then the 584 response is usually sent using a new Non-confirmable message, 585 although the server may send a Confirmable message. This type of 586 exchange is illustrated in Figure 6. 588 Client Server 589 | | 590 | NON [0x7a11] | 591 | GET /temperature | 592 | (Token 0x74) | 593 +----------------->| 594 | | 595 | NON [0x23bc] | 596 | 2.05 Content | 597 | (Token 0x74) | 598 | "22.5 C" | 599 |<-----------------+ 600 | | 602 Figure 6: A NON request and response 604 CoAP makes use of GET, PUT, POST and DELETE methods in a similar 605 manner to HTTP, with the semantics specified in Section 5.8. (Note 606 that the detailed semantics of CoAP methods are "almost, but not 607 entirely unlike" [HHGTTG] those of HTTP methods: Intuition taken from 608 HTTP experience generally does apply well, but there are enough 609 differences that make it worthwhile to actually read the present 610 specification.) 612 URI support in a server is simplified as the client already parses 613 the URI and splits it into host, port, path and query components, 614 making use of default values for efficiency. Response codes 615 correspond to a small subset of HTTP response codes with a few CoAP 616 specific codes added, as defined in Section 5.9. 618 2.3. Intermediaries and Caching 620 The protocol supports the caching of responses in order to 621 efficiently fulfill requests. Simple caching is enabled using 622 freshness and validity information carried with CoAP responses. A 623 cache could be located in an endpoint or an intermediary. Caching 624 functionality is specified in Section 5.6. 626 Proxying is useful in constrained networks for several reasons, 627 including network traffic limiting, to improve performance, to access 628 resources of sleeping devices or for security reasons. The proxying 629 of requests on behalf of another CoAP endpoint is supported in the 630 protocol. When using a proxy, the URI of the resource to request is 631 included in the request, while the destination IP address is set to 632 the address of the proxy. See Section 5.7 for more information on 633 proxy functionality. 635 As CoAP was designed according to the REST architecture and thus 636 exhibits functionality similar to that of the HTTP protocol, it is 637 quite straightforward to map from CoAP to HTTP and from HTTP to CoAP. 638 Such a mapping may be used to realize an HTTP REST interface using 639 CoAP, or for converting between HTTP and CoAP. This conversion can 640 be carried out by a cross-protocol proxy ("cross-proxy"), which 641 converts the method or response code, media type, and options to the 642 corresponding HTTP feature. Section 10 provides more detail about 643 HTTP mapping. 645 2.4. Resource Discovery 647 Resource discovery is important for machine-to-machine interactions, 648 and is supported using the CoRE Link Format [RFC6690] as discussed in 649 Section 7. 651 3. Message Format 653 CoAP is based on the exchange of short messages which, by default, 654 are transported over UDP (i.e. each CoAP message occupies the data 655 section of one UDP datagram). CoAP may also be used over Datagram 656 Transport Layer Security (DTLS) (see Section 9.1). It could also be 657 used over other transports such as SMS, TCP or SCTP, the 658 specification of which is out of this document's scope. 660 CoAP messages are encoded in a simple binary format. The message 661 format starts with a fixed-size 4-byte header. This is followed by a 662 variable-length Token value which can be between 0 and 8 bytes long. 663 Following the Token value comes a sequence of zero or more CoAP 664 Options in Type-Length-Value (TLV) format, optionally followed by a 665 payload which takes up the rest of the datagram. 667 0 1 2 3 668 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 669 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 670 |Ver| T | TKL | Code | Message ID | 671 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 672 | Token (if any, TKL bytes) ... 673 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 674 | Options (if any) ... 675 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 676 |1 1 1 1 1 1 1 1| Payload (if any) ... 677 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 679 Figure 7: Message Format 681 The fields in the header are defined as follows: 683 Version (Ver): 2-bit unsigned integer. Indicates the CoAP version 684 number. Implementations of this specification MUST set this field 685 to 1. Other values are reserved for future versions. 687 Type (T): 2-bit unsigned integer. Indicates if this message is of 688 type Confirmable (0), Non-confirmable (1), Acknowledgement (2) or 689 Reset (3). The semantics of these message types are defined in 690 Section 4. 692 Token Length (TKL): 4-bit unsigned integer. Indicates the length of 693 the variable-length Token field (0-8 bytes). Lengths 9-15 are 694 reserved, MUST NOT be sent, and MUST be processed as a message 695 format error. 697 Code: 8-bit unsigned integer. Indicates if the message carries a 698 request (1-31) or a response (64-191), or is empty (0). (All 699 other code values are reserved.) In case of a request, the Code 700 field indicates the Request Method; in case of a response a 701 Response Code. Possible values are maintained in the CoAP Code 702 Registry (Section 12.1). The semantics of requests and responses 703 are defined in Section 5. 705 Message ID: 16-bit unsigned integer in network byte order. Used for 706 the detection of message duplication, and to match messages of 707 type Acknowledgement/Reset to messages of type Confirmable/ 708 Non-confirmable. The rules for generating a Message ID and 709 matching messages are defined in Section 4. 711 The header is followed by the Token value, which may be 0 to 8 bytes, 712 as given by the Token Length field. The Token value is used to 713 correlate requests and responses. The rules for generating a Token 714 and correlating requests and responses are defined in Section 5.3.1. 716 Header and Token are followed by zero or more Options (Section 3.1). 717 An Option can be followed by the end of the message, by another 718 Option, or by the Payload Marker and the payload. 720 Following the header, token, and options, if any, comes the optional 721 payload. If present and of non-zero length, it is prefixed by a 722 fixed, one-byte Payload Marker (0xFF) which indicates the end of 723 options and the start of the payload. The payload data extends from 724 after the marker to the end of the UDP datagram, i.e., the Payload 725 Length is calculated from the datagram size. The absence of the 726 Payload Marker denotes a zero-length payload. The presence of a 727 marker followed by a zero-length payload MUST be processed as a 728 message format error. 730 Implementation Note: The byte value 0xFF may also occur within an 731 option length or value, so simple byte-wise scanning for 0xFF is 732 not a viable technique for finding the payload marker. The byte 733 0xFF has the meaning of a payload marker only where the beginning 734 of another option could occur. 736 3.1. Option Format 738 CoAP defines a number of options which can be included in a message. 739 Each option instance in a message specifies the Option Number of the 740 defined CoAP option, the length of the Option Value and the Option 741 Value itself. 743 Instead of specifying the Option Number directly, the instances MUST 744 appear in order of their Option Numbers and a delta encoding is used 745 between them: The Option Number for each instance is calculated as 746 the sum of its delta and the Option Number of the preceding instance 747 in the message. For the first instance in a message, a preceding 748 option instance with Option Number zero is assumed. Multiple 749 instances of the same option can be included by using a delta of 750 zero. 752 Option Numbers are maintained in the CoAP Option Number Registry 753 (Section 12.2). See Section 5.4 for the semantics of the options 754 defined in this document. 756 0 1 2 3 4 5 6 7 757 +---------------+---------------+ 758 | | | 759 | Option Delta | Option Length | 1 byte 760 | | | 761 +---------------+---------------+ 762 \ \ 763 / Option Delta / 0-2 bytes 764 \ (extended) \ 765 +-------------------------------+ 766 \ \ 767 / Option Length / 0-2 bytes 768 \ (extended) \ 769 +-------------------------------+ 770 \ \ 771 / / 772 \ \ 773 / Option Value / 0 or more bytes 774 \ \ 775 / / 776 \ \ 777 +-------------------------------+ 779 Figure 8: Option Format 781 The fields in an option are defined as follows: 783 Option Delta: 4-bit unsigned integer. A value between 0 and 12 784 indicates the Option Delta. Three values are reserved for special 785 constructs: 787 13: An 8-bit unsigned integer follows the initial byte and 788 indicates the Option Delta minus 13. 790 14: A 16-bit unsigned integer in network byte order follows the 791 initial byte and indicates the Option Delta minus 269. 793 15: Reserved for the Payload Marker. If the field is set to this 794 value but the entire byte is not the payload marker, this MUST 795 be processed as a message format error. 797 The resulting Option Delta is used as the difference between the 798 Option Number of this option and that of the previous option (or 799 zero for the first option). In other words, the Option Number is 800 calculated by simply summing the Option Delta values of this and 801 all previous options before it. 803 Option Length: 4-bit unsigned integer. A value between 0 and 12 804 indicates the length of the Option Value, in bytes. Three values 805 are reserved for special constructs: 807 13: An 8-bit unsigned integer precedes the Option Value and 808 indicates the Option Length minus 13. 810 14: A 16-bit unsigned integer in network byte order precedes the 811 Option Value and indicates the Option Length minus 269. 813 15: Reserved for future use. If the field is set to this value, 814 it MUST be processed as a message format error. 816 Value: A sequence of exactly Option Length bytes. The length and 817 format of the Option Value depend on the respective option, which 818 MAY define variable length values. See Section 3.2 for the 819 formats used in this document; options defined in other documents 820 MAY make use of other option value formats. 822 3.2. Option Value Formats 824 The options defined in this document make use of the following option 825 value formats. 827 empty: A zero-length sequence of bytes. 829 opaque: An opaque sequence of bytes. 831 uint: A non-negative integer which is represented in network byte 832 order using the number of bytes given by the Option Length 833 field. 835 An option definition may specify a range of permissible 836 numbers of bytes; if it has a choice, a sender SHOULD 837 represent the integer with as few bytes as possible, i.e., 838 without leading zero bytes. For example, the number 0 is 839 represented with an empty option value (a zero-length 840 sequence of bytes), and the number 1 by a single byte with 841 the numerical value of 1 (bit combination 00000001 in most 842 significant bit first notation). A recipient MUST be 843 prepared to process values with leading zero bytes. 845 Implementation Note: The exceptional behavior permitted 846 for the sender is intended for highly 847 constrained, templated implementations (e.g., 848 hardware implementations) that use fixed size 849 options in the templates. 851 string: A Unicode string which is encoded using UTF-8 [RFC3629] in 852 Net-Unicode form [RFC5198]. 854 Note that here and in all other places where UTF-8 encoding 855 is used in the CoAP protocol, the intention is that the 856 encoded strings can be directly used and compared as opaque 857 byte strings by CoAP protocol implementations. There is no 858 expectation and no need to perform normalization within a 859 CoAP implementation (except where Unicode strings that are 860 not known to be normalized are imported from sources 861 outside the CoAP protocol). Note also that ASCII strings 862 (that do not make use of special control characters) are 863 always valid UTF-8 Net-Unicode strings. 865 4. Message Transmission 867 CoAP messages are exchanged asynchronously between CoAP endpoints. 868 They are used to transport CoAP requests and responses, the semantics 869 of which are defined in Section 5. 871 As CoAP is bound to non-reliable transports such as UDP, CoAP 872 messages may arrive out of order, appear duplicated, or go missing 873 without notice. For this reason, CoAP implements a lightweight 874 reliability mechanism, without trying to re-create the full feature 875 set of a transport like TCP. It has the following features: 877 o Simple stop-and-wait retransmission reliability with exponential 878 back-off for Confirmable messages. 880 o Duplicate detection for both Confirmable and Non-confirmable 881 messages. 883 4.1. Messages and Endpoints 885 A CoAP endpoint is the source or destination of a CoAP message. The 886 specific definition of an endpoint depends on the transport being 887 used for CoAP. For the transports defined in this specification, the 888 endpoint is identified depending on the security mode used (see 889 Section 9): With no security, the endpoint is solely identified by an 890 IP address and a UDP port number. With other security modes, the 891 endpoint is identified as defined by the security mode. 893 There are different types of messages. The type of a message is 894 specified by the Type field of the CoAP Header. 896 Separate from the message type, a message may carry a request, a 897 response, or be empty. This is signaled by the Request/Response Code 898 field in the CoAP Header and is relevant to the request/response 899 model. Possible values for the field are maintained in the CoAP Code 900 Registry (Section 12.1). 902 An empty message has the Code field set to 0. The Token Length field 903 MUST be set to 0 and no bytes MUST be present after the Message ID 904 field. If there are any bytes, they MUST be processed as a message 905 format error. 907 4.2. Messages Transmitted Reliably 909 The reliable transmission of a message is initiated by marking the 910 message as Confirmable in the CoAP header. A Confirmable message 911 always carries either a request or response and MUST NOT be empty, 912 unless it is used only to elicit a Reset message. A recipient MUST 913 acknowledge such a message with an Acknowledgement message or, if it 914 lacks context to process the message properly (including the case 915 where the message is empty or has a message format error), MUST 916 reject it; rejecting a Confirmable message is effected by sending a 917 matching Reset message and otherwise ignoring it. The 918 Acknowledgement message MUST echo the Message ID of the Confirmable 919 message, and MUST carry a response or be empty (see Section 5.2.1 and 920 Section 5.2.2). The Reset message MUST echo the Message ID of the 921 Confirmable message, and MUST be empty. Rejecting an Acknowledgement 922 or Reset message is effected by silently ignoring it. More 923 generally, Acknowledgement and Reset messages MUST NOT elicit any 924 Acknowledgement or Reset message from their recipient. 926 The sender retransmits the Confirmable message at exponentially 927 increasing intervals, until it receives an acknowledgement (or Reset 928 message), or runs out of attempts. 930 Retransmission is controlled by two things that a CoAP endpoint MUST 931 keep track of for each Confirmable message it sends while waiting for 932 an acknowledgement (or reset): a timeout and a retransmission 933 counter. For a new Confirmable message, the initial timeout is set 934 to a random number between ACK_TIMEOUT and (ACK_TIMEOUT * 935 ACK_RANDOM_FACTOR) (see Section 4.8), and the retransmission counter 936 is set to 0. When the timeout is triggered and the retransmission 937 counter is less than MAX_RETRANSMIT, the message is retransmitted, 938 the retransmission counter is incremented, and the timeout is 939 doubled. If the retransmission counter reaches MAX_RETRANSMIT on a 940 timeout, or if the endpoint receives a Reset message, then the 941 attempt to transmit the message is canceled and the application 942 process informed of failure. On the other hand, if the endpoint 943 receives an acknowledgement in time, transmission is considered 944 successful. 946 A CoAP endpoint that sent a Confirmable message MAY give up in 947 attempting to obtain an ACK even before the MAX_RETRANSMIT counter 948 value is reached: E.g., the application has canceled the request as 949 it no longer needs a response, or there is some other indication that 950 the CON message did arrive. In particular, a CoAP request message 951 may have elicited a separate response, in which case it is clear to 952 the requester that only the ACK was lost and a retransmission of the 953 request would serve no purpose. However, a responder MUST NOT in 954 turn rely on this cross-layer behavior from a requester, i.e. it 955 SHOULD retain the state to create the ACK for the request, if needed, 956 even if a Confirmable response was already acknowledged by the 957 requester. 959 4.3. Messages Transmitted Without Reliability 961 Some messages do not require an acknowledgement. This is 962 particularly true for messages that are repeated regularly for 963 application requirements, such as repeated readings from a sensor 964 where eventual success is sufficient. 966 As a more lightweight alternative, a message can be transmitted less 967 reliably by marking the message as Non-confirmable. A Non- 968 confirmable message always carries either a request or response and 969 MUST NOT be empty. A Non-confirmable message MUST NOT be 970 acknowledged by the recipient. If a recipient lacks context to 971 process the message properly (including the case where the message is 972 empty or has a message format error), it MUST reject the message; 973 rejecting a Non-confirmable message MAY involve sending a matching 974 Reset message, and apart from the Reset message the rejected message 975 MUST be silently ignored. 977 At the CoAP level, there is no way for the sender to detect if a Non- 978 confirmable message was received or not. A sender MAY choose to 979 transmit multiple copies of a Non-confirmable message within 980 MAX_TRANSMIT_SPAN (limited by the provisions of Section 4.7, in 981 particular by PROBING_RATE if no response is received), or the 982 network may duplicate the message in transit. To enable the receiver 983 to act only once on the message, Non-confirmable messages specify a 984 Message ID as well. (This Message ID is drawn from the same number 985 space as the Message IDs for Confirmable messages.) 987 4.4. Message Correlation 989 An Acknowledgement or Reset message is related to a Confirmable 990 message or Non-confirmable message by means of a Message ID along 991 with additional address information of the corresponding endpoint. 992 The Message ID is a 16-bit unsigned integer that is generated by the 993 sender of a Confirmable or Non-confirmable message and included in 994 the CoAP header. The Message ID MUST be echoed in the 995 Acknowledgement or Reset message by the recipient. 997 The same Message ID MUST NOT be re-used (in communicating with the 998 same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2). 1000 Implementation Note: Several implementation strategies can be 1001 employed for generating Message IDs. In the simplest case a CoAP 1002 endpoint generates Message IDs by keeping a single Message ID 1003 variable, which is changed each time a new Confirmable or Non- 1004 confirmable message is sent regardless of the destination address 1005 or port. Endpoints dealing with large numbers of transactions 1006 could keep multiple Message ID variables, for example per prefix 1007 or destination address (note that some receiving endpoints may not 1008 be able to distinguish unicast and multicast packets adressed to 1009 it, so endpoints generating Message IDs need to make sure these do 1010 not overlap). The initial variable value should be randomized. 1012 For an Acknowledgement or Reset message to match a Confirmable or 1013 Non-confirmable message, the Message ID and source endpoint of the 1014 Acknowledgement or Reset message MUST match the Message ID and 1015 destination endpoint of the Confirmable or Non-confirmable message. 1017 4.5. Message Deduplication 1019 A recipient MUST be prepared to receive the same Confirmable message 1020 (as indicated by the Message ID and source endpoint) multiple times 1021 within the EXCHANGE_LIFETIME (Section 4.8.2), for example, when its 1022 Acknowledgement went missing or didn't reach the original sender 1023 before the first timeout. The recipient SHOULD acknowledge each 1024 duplicate copy of a Confirmable message using the same 1025 Acknowledgement or Reset message, but SHOULD process any request or 1026 response in the message only once. This rule MAY be relaxed in case 1027 the Confirmable message transports a request that is idempotent (see 1028 Section 5.1) or can be handled in an idempotent fashion. Examples 1029 for relaxed message deduplication: 1031 o A server MAY relax the requirement to answer all retransmissions 1032 of an idempotent request with the same response (Section 4.2), so 1033 that it does not have to maintain state for Message IDs. For 1034 example, an implementation might want to process duplicate 1035 transmissions of a GET, PUT or DELETE request as separate requests 1036 if the effort incurred by duplicate processing is less expensive 1037 than keeping track of previous responses would be. 1039 o A constrained server MAY even want to relax this requirement for 1040 certain non-idempotent requests if the application semantics make 1041 this trade-off favorable. For example, if the result of a POST 1042 request is just the creation of some short-lived state at the 1043 server, it may be less expensive to incur this effort multiple 1044 times for a request than keeping track of whether a previous 1045 transmission of the same request already was processed. 1047 A recipient MUST be prepared to receive the same Non-confirmable 1048 message (as indicated by the Message ID and source endpoint) multiple 1049 times within NON_LIFETIME (Section 4.8.2). As a general rule that 1050 MAY be relaxed based on the specific semantics of a message, the 1051 recipient SHOULD silently ignore any duplicated Non-confirmable 1052 message, and SHOULD process any request or response in the message 1053 only once. 1055 4.6. Message Size 1057 While specific link layers make it beneficial to keep CoAP messages 1058 small enough to fit into their link layer packets (see Section 1), 1059 this is a matter of implementation quality. The CoAP specification 1060 itself provides only an upper bound to the message size. Messages 1061 larger than an IP fragment result in undesired packet fragmentation. 1062 A CoAP message, appropriately encapsulated, SHOULD fit within a 1063 single IP packet (i.e., avoid IP fragmentation) and (by fitting into 1064 one UDP payload) obviously MUST fit within a single IP datagram. If 1065 the Path MTU is not known for a destination, an IP MTU of 1280 bytes 1066 SHOULD be assumed; if nothing is known about the size of the headers, 1067 good upper bounds are 1152 bytes for the message size and 1024 bytes 1068 for the payload size. 1070 Implementation Note: CoAP's choice of message size parameters works 1071 well with IPv6 and with most of today's IPv4 paths. (However, 1072 with IPv4, it is harder to absolutely ensure that there is no IP 1073 fragmentation. If IPv4 support on unusual networks is a 1074 consideration, implementations may want to limit themselves to 1075 more conservative IPv4 datagram sizes such as 576 bytes; worse, 1076 the absolute minimum value of the IP MTU for IPv4 is as low as 68 1077 bytes, which would leave only 40 bytes minus security overhead for 1078 a UDP payload. Implementations extremely focused on this problem 1079 set might also set the IPv4 DF bit and perform some form of path 1080 MTU discovery; this should generally be unnecessary in most 1081 realistic use cases for CoAP, however.) A more important kind of 1082 fragmentation in many constrained networks is that on the 1083 adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 1084 bytes including various overheads); this may motivate 1085 implementations to be frugal in their packet sizes and to move to 1086 block-wise transfers [I-D.ietf-core-block] when approaching three- 1087 digit message sizes. 1089 Message sizes are also of considerable importance to 1090 implementations on constrained nodes. Many implementations will 1091 need to allocate a buffer for incoming messages. If an 1092 implementation is too constrained to allow for allocating the 1093 above-mentioned upper bound, it could apply the following 1094 implementation strategy: Implementations receiving a datagram into 1095 a buffer that is too small are usually able to determine if the 1096 trailing portion of a datagram was discarded and to retrieve the 1097 initial portion. So, if not all of the payload, at least the CoAP 1098 header and options are likely to fit within the buffer. A server 1099 can thus fully interpret a request and return a 4.13 (Request 1100 Entity Too Large, see Section 5.9.2.9) response code if the 1101 payload was truncated. A client sending an idempotent request and 1102 receiving a response larger than would fit in the buffer can 1103 repeat the request with a suitable value for the Block Option 1104 [I-D.ietf-core-block]. 1106 4.7. Congestion Control 1108 Basic congestion control for CoAP is provided by the exponential 1109 back-off mechanism in Section 4.2. 1111 In order not to cause congestion, Clients (including proxies) MUST 1112 strictly limit the number of simultaneous outstanding interactions 1113 that they maintain to a given server (including proxies) to NSTART. 1114 An outstanding interaction is either a CON for which an ACK has not 1115 yet been received but is still expected (message layer) or a request 1116 for which neither a response nor an Acknowledgment message has yet 1117 been received but is still expected (which may both occur at the same 1118 time, counting as one outstanding interaction). The default value of 1119 NSTART for this specification is 1. 1121 Further congestion control optimizations and considerations are 1122 expected in the future, which may for example provide automatic 1123 initialization of the CoAP transmission parameters defined in 1124 Section 4.8, and thus may allow a value for NSTART greater than one. 1126 A client stops expecting a response to a Confirmable request for 1127 which no acknowledgment message was received, after 1128 EXCHANGE_LIFETIME. The specific algorithm by which a client stops to 1129 "expect" a response to a Confirmable request that was acknowledged, 1130 or to a Non-confirmable request, is not defined. Unless this is 1131 modified by additional congestion control optimizations, it MUST be 1132 chosen in such a way that an endpoint does not exceed an average data 1133 rate of PROBING_RATE in sending to another endpoint that does not 1134 respond. 1136 Note: CoAP places the onus of congestion control mostly on the 1137 clients. However, clients may malfunction or actually be 1138 attackers, e.g. to perform amplification attacks (Section 11.3). 1139 To limit the damage (to the network and to its own energy 1140 resources), a server SHOULD implement some rate limiting for its 1141 response transmission based on reasonable assumptions about 1142 application requirements. This is most helpful if the rate limit 1143 can be made effective for the misbehaving endpoints, only. 1145 4.8. Transmission Parameters 1147 Message transmission is controlled by the following parameters: 1149 +-------------------+---------------+ 1150 | name | default value | 1151 +-------------------+---------------+ 1152 | ACK_TIMEOUT | 2 seconds | 1153 | ACK_RANDOM_FACTOR | 1.5 | 1154 | MAX_RETRANSMIT | 4 | 1155 | NSTART | 1 | 1156 | DEFAULT_LEISURE | 5 seconds | 1157 | PROBING_RATE | 1 Byte/second | 1158 +-------------------+---------------+ 1160 Table 1: CoAP Protocol Parameters 1162 4.8.1. Changing The Parameters 1164 The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT, 1165 NSTART, DEFAULT_LEISURE, and PROBING_RATE may be configured to values 1166 specific to the application environment (including dynamically 1167 adjusted values), however the configuration method is out of scope of 1168 this document. It is recommended that an application environment use 1169 consistent values for these parameters. 1171 The transmission parameters have been chosen to achieve a behavior in 1172 the presence of congestion that is safe in the Internet. If a 1173 configuration desires to use different values, the onus is on the 1174 configuration to ensure these congestion control properties are not 1175 violated. In particular, a decrease of ACK_TIMEOUT below 1 second 1176 would violate the guidelines of [RFC5405]. 1177 ([I-D.allman-tcpm-rto-consider] provides some additional background.) 1178 CoAP was designed to enable implementations that do not maintain 1179 round-trip-time (RTT) measurements. However, where it is desired to 1180 decrease the ACK_TIMEOUT significantly or increase NSTART, this can 1181 only be done safely when maintaining such measurements. 1182 Configurations MUST NOT decrease ACK_TIMEOUT or increase NSTART 1183 without using mechanisms that ensure congestion control safety, 1184 either defined in the configuration or in future standards documents. 1186 ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have 1187 a value that is sufficiently different from 1.0 to provide some 1188 protection from synchronization effects. 1190 MAX_RETRANSMIT can be freely adjusted, but a too small value will 1191 reduce the probability that a Confirmable message is actually 1192 received, while a larger value than given here will require further 1193 adjustments in the time values (see Section 4.8.2). 1195 If the choice of transmission parameters leads to an increase of 1196 derived time values (see Section 4.8.2), the configuration mechanism 1197 MUST ensure the adjusted value is also available to all the endpoints 1198 that these adjusted values are to be used to communicate with. 1200 4.8.2. Time Values derived from Transmission Parameters 1202 The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR and MAX_RETRANSMIT 1203 influences the timing of retransmissions, which in turn influences 1204 how long certain information items need to be kept by an 1205 implementation. To be able to unambiguously reference these derived 1206 time values, we give them names as follows: 1208 o MAX_TRANSMIT_SPAN is the maximum time from the first transmission 1209 of a Confirmable message to its last retransmission. For the 1210 default transmission parameters, the value is (2+4+8+16)*1.5 = 45 1211 seconds, or more generally: 1213 ACK_TIMEOUT * (2 ** MAX_RETRANSMIT - 1) * ACK_RANDOM_FACTOR 1215 o MAX_TRANSMIT_WAIT is the maximum time from the first transmission 1216 of a Confirmable message to the time when the sender gives up on 1217 receiving an acknowledgement or reset. For the default 1218 transmission parameters, the value is (2+4+8+16+32)*1.5 = 93 1219 seconds, or more generally: 1221 ACK_TIMEOUT * (2 ** (MAX_RETRANSMIT + 1) - 1) * 1222 ACK_RANDOM_FACTOR 1224 In addition, some assumptions need to be made on the characteristics 1225 of the network and the nodes. 1227 o MAX_LATENCY is the maximum time a datagram is expected to take 1228 from the start of its transmission to the completion of its 1229 reception. This constant is related to the MSL (Maximum Segment 1230 Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 1231 minutes" ([RFC0793] glossary, page 81). Note that this is not 1232 necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not 1233 intended to describe a situation when the protocol works well, but 1234 the worst case situation against which the protocol has to guard. 1235 We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart 1236 from being reasonably realistic for the bulk of configurations as 1237 well as close to the historic choice for TCP, this value also 1238 allows Message ID lifetime timers to be represented in 8 bits 1239 (when measured in seconds). In these calculations, there is no 1240 assumption that the direction of the transmission is irrelevant 1241 (i.e. that the network is symmetric), just that the same value can 1242 reasonably be used as a maximum value for both directions. If 1243 that is not the case, the following calculations become only 1244 slightly more complex. 1246 o PROCESSING_DELAY is the time a node takes to turn around a 1247 Confirmable message into an acknowledgement. We assume the node 1248 will attempt to send an ACK before having the sender time out, so 1249 as a conservative assumption we set it equal to ACK_TIMEOUT. 1251 o MAX_RTT is the maximum round-trip time, or: 1253 2 * MAX_LATENCY + PROCESSING_DELAY 1255 From these values, we can derive the following values relevant to the 1256 protocol operation: 1258 o EXCHANGE_LIFETIME is the time from starting to send a Confirmable 1259 message to the time when an acknowledgement is no longer expected, 1260 i.e. message layer information about the message exchange can be 1261 purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a 1262 MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the 1263 way back. Note that there is no need to consider 1264 MAX_TRANSMIT_WAIT if the configuration is chosen such that the 1265 last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the 1266 difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is 1267 less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY 1268 is a worst case value unlikely to be met in the real world. In 1269 this case, EXCHANGE_LIFETIME simplifies to: 1271 MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY 1273 or 247 seconds with the default transmission parameters. 1275 o NON_LIFETIME is the time from sending a Non-confirmable message to 1276 the time its Message ID can be safely reused. If multiple 1277 transmission of a NON message is not used, its value is 1278 MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a 1279 NON message multiple times, in particular for multicast 1280 applications. While the period of re-use is not bounded by the 1281 specification, an expectation of reliable detection of duplication 1282 at the receiver is in the timescales of MAX_TRANSMIT_SPAN. 1283 Therefore, for this purpose, it is safer to use the value: 1285 MAX_TRANSMIT_SPAN + MAX_LATENCY 1287 or 145 seconds with the default transmission parameters; however, 1288 an implementation that just wants to use a single timeout value 1289 for retiring Messagen IDs can safely use the larger value for 1290 EXCHANGE_LIFETIME. 1292 Table 2 summarizes the derived parameters introduced in this 1293 subsection with their default values. 1295 +-------------------+---------------+ 1296 | name | default value | 1297 +-------------------+---------------+ 1298 | MAX_TRANSMIT_SPAN | 45 s | 1299 | MAX_TRANSMIT_WAIT | 93 s | 1300 | MAX_LATENCY | 100 s | 1301 | PROCESSING_DELAY | 2 s | 1302 | MAX_RTT | 202 s | 1303 | EXCHANGE_LIFETIME | 247 s | 1304 | NON_LIFETIME | 145 s | 1305 +-------------------+---------------+ 1307 Table 2: Derived Protocol Parameters 1309 5. Request/Response Semantics 1311 CoAP operates under a similar request/response model as HTTP: a CoAP 1312 endpoint in the role of a "client" sends one or more CoAP requests to 1313 a "server", which services the requests by sending CoAP responses. 1315 Unlike HTTP, requests and responses are not sent over a previously 1316 established connection, but exchanged asynchronously over CoAP 1317 messages. 1319 5.1. Requests 1321 A CoAP request consists of the method to be applied to the resource, 1322 the identifier of the resource, a payload and Internet media type (if 1323 any), and optional meta-data about the request. 1325 CoAP supports the basic methods of GET, POST, PUT, DELETE, which are 1326 easily mapped to HTTP. They have the same properties of safe (only 1327 retrieval) and idempotent (you can invoke it multiple times with the 1328 same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method 1329 is safe, therefore it MUST NOT take any other action on a resource 1330 other than retrieval. The GET, PUT and DELETE methods MUST be 1331 performed in such a way that they are idempotent. POST is not 1332 idempotent, because its effect is determined by the origin server and 1333 dependent on the target resource; it usually results in a new 1334 resource being created or the target resource being updated. 1336 A request is initiated by setting the Code field in the CoAP header 1337 of a Confirmable or a Non-confirmable message to a Method Code and 1338 including request information. 1340 The methods used in requests are described in detail in Section 5.8. 1342 5.2. Responses 1344 After receiving and interpreting a request, a server responds with a 1345 CoAP response, which is matched to the request by means of a client- 1346 generated token (Section 5.3, note that this is different from the 1347 Message ID that matches a Confirmable message to its 1348 Acknowledgement). 1350 A response is identified by the Code field in the CoAP header being 1351 set to a Response Code. Similar to the HTTP Status Code, the CoAP 1352 Response Code indicates the result of the attempt to understand and 1353 satisfy the request. These codes are fully defined in Section 5.9. 1354 The Response Code numbers to be set in the Code field of the CoAP 1355 header are maintained in the CoAP Response Code Registry 1356 (Section 12.1.2). 1358 0 1359 0 1 2 3 4 5 6 7 1360 +-+-+-+-+-+-+-+-+ 1361 |class| detail | 1362 +-+-+-+-+-+-+-+-+ 1364 Figure 9: Structure of a Response Code 1366 The upper three bits of the 8-bit Response Code number define the 1367 class of response. The lower five bits do not have any 1368 categorization role; they give additional detail to the overall class 1369 (Figure 9). 1371 As a human readable notation for specifications and protocol 1372 diagnostics, the response code is documented in the format "c.dd", 1373 where "c" is the class in decimal, and "dd" is the detail as a two- 1374 digit decimal. For example, "Forbidden" is written as 4.03 -- 1375 indicating a value of 4*32+3, hexadecimal 0x83 or decimal 131. 1377 There are 3 classes: 1379 2 - Success: The request was successfully received, understood, and 1380 accepted. 1382 4 - Client Error: The request contains bad syntax or cannot be 1383 fulfilled. 1385 5 - Server Error: The server failed to fulfill an apparently valid 1386 request. 1388 The response codes are designed to be extensible: Response Codes in 1389 the Client Error and Server Error class that are unrecognized by an 1390 endpoint MUST be treated as being equivalent to the generic Response 1391 Code of that class (4.00 and 5.00, respectively). However, there is 1392 no generic Response Code indicating success, so a Response Code in 1393 the Success class that is unrecognized by an endpoint can only be 1394 used to determine that the request was successful without any further 1395 details. 1397 The possible response codes are described in detail in Section 5.9. 1399 Responses can be sent in multiple ways, which are defined in the 1400 following subsections. 1402 5.2.1. Piggy-backed 1404 In the most basic case, the response is carried directly in the 1405 Acknowledgement message that acknowledges the request (which requires 1406 that the request was carried in a Confirmable message). This is 1407 called a "Piggy-backed" Response. 1409 The response is returned in the Acknowledgement message independent 1410 of whether the response indicates success or failure. In effect, the 1411 response is piggy-backed on the Acknowledgement message, and no 1412 separate message is required to return the response. 1414 Implementation Note: The protocol leaves the decision whether to 1415 piggy-back a response or not (i.e., send a separate response) to 1416 the server. The client MUST be prepared to receive either. On 1417 the quality of implementation level, there is a strong expectation 1418 that servers will implement code to piggy-back whenever possible 1419 -- saving resources in the network and both at the client and at 1420 the server. 1422 5.2.2. Separate 1424 It may not be possible to return a piggy-backed response in all 1425 cases. For example, a server might need longer to obtain the 1426 representation of the resource requested than it can wait sending 1427 back the Acknowledgement message, without risking the client to 1428 repeatedly retransmit the request message (see also the discussion of 1429 PROCESSING_DELAY in Section 4.8.2). The Response to a request 1430 carried in a Non-confirmable message is always sent separately (as 1431 there is no Acknowledgement message). 1433 The server maybe initiates the attempt to obtain the resource 1434 representation and times out an acknowledgement timer, or it 1435 immediately sends an acknowledgement knowing in advance that there 1436 will be no piggy-backed response. The acknowledgement effectively is 1437 a promise that the request will be acted upon. 1439 When the server finally has obtained the resource representation, it 1440 sends the response. When it is desired that this message is not 1441 lost, it is sent as a Confirmable message from the server to the 1442 client and answered by the client with an Acknowledgement, echoing 1443 the new Message ID chosen by the server. (It may also be sent as a 1444 Non-confirmable message; see Section 5.2.3.) 1446 When the server chooses to use a separate response, it sends the 1447 Acknowledgement to the Confirmable request as an empty message. If 1448 the server then sends a Confirmable response, the client's 1449 Acknowledgement to that response MUST also be an empty message (one 1450 that carries neither a request nor a response). The server MUST stop 1451 retransmitting its response on any matching Acknowledgement (silently 1452 ignoring any response code or payload) or Reset message. 1454 Implementation Notes: Note that, as the underlying datagram 1455 transport may not be sequence-preserving, the Confirmable message 1456 carrying the response may actually arrive before or after the 1457 Acknowledgement message for the request; for the purposes of 1458 terminating the retransmission sequence, this also serves as an 1459 acknowledgement. Note also that, while the CoAP protocol itself 1460 does not make any specific demands here, there is an expectation 1461 that the response will come within a time frame that is reasonable 1462 from an application point of view; as there is no underlying 1463 transport protocol that could be instructed to run a keep-alive 1464 mechanism, the requester may want to set up a timeout that is 1465 unrelated to CoAP's retransmission timers in case the server is 1466 destroyed or otherwise unable to send the response.) 1468 5.2.3. Non-confirmable 1470 If the request message is Non-confirmable, then the response SHOULD 1471 be returned in a Non-confirmable message as well. However, an 1472 endpoint MUST be prepared to receive a Non-confirmable response 1473 (preceded or followed by an empty Acknowledgement message) in reply 1474 to a Confirmable request, or a Confirmable response in reply to a 1475 Non-confirmable request. 1477 5.3. Request/Response Matching 1479 Regardless of how a response is sent, it is matched to the request by 1480 means of a token that is included by the client in the request, along 1481 with additional address information of the corresponding endpoint. 1483 5.3.1. Token 1485 The Token is used to match a response with a request. The token 1486 value is a sequence of 0 to 8 bytes. (Note that every message 1487 carries a token, even if it is of zero length.) Every request 1488 carries a client-generated token, which the server MUST echo in any 1489 resulting response without modification. 1491 A token is intended for use as a client-local identifier for 1492 differentiating between concurrent requests (see Section 5.3); it 1493 could have been called a "request ID". 1495 The client SHOULD generate tokens in such a way that tokens currently 1496 in use for a given source/destination endpoint pair are unique. 1497 (Note that a client implementation can use the same token for any 1498 request if it uses a different endpoint each time, e.g. a different 1499 source port number.) An empty token value is appropriate e.g. when 1500 no other tokens are in use to a destination, or when requests are 1501 made serially per destination and receive piggy-backed responses. 1503 There are however multiple possible implementation strategies to 1504 fulfill this. 1506 A client sending a request without using transport layer security 1507 (Section 9) may want to use a non-trivial, randomized token if it is 1508 desirable to guard against spoofing of responses (Section 11.4). 1509 This protective use of tokens is the reason they are allowed to be up 1510 to 8 bytes in size. 1512 An endpoint receiving a token it did not generate MUST treat it as 1513 opaque and make no assumptions about its content or structure. 1515 5.3.2. Request/Response Matching Rules 1517 The exact rules for matching a response to a request are as follows: 1519 1. The source endpoint of the response MUST be the same as the 1520 destination endpoint of the original request. 1522 2. In a piggy-backed response, both the Message ID of the 1523 Confirmable request and the Acknowledgement, and the token of the 1524 response and original request MUST match. In a separate 1525 response, just the token of the response and original request 1526 MUST match. 1528 In case a message carrying a response is unexpected (the client is 1529 not waiting for a response from the identified endpoint, at the 1530 endpoint addressed, and/or with the given token), the response is 1531 rejected (Section 4.2, Section 4.3). 1533 Implementation Note: A client that receives a response in a CON 1534 message may want to clean up the message state right after sending 1535 the ACK. If that ACK is lost and the server retransmits the CON, 1536 the client may no longer have any state to correlate this response 1537 to, making the retransmission an unexpected message; the client 1538 may send a Reset message so it does not receive any more 1539 retransmissions. This behavior is normal and not an indication of 1540 an error. (Clients that are not aggressively optimized in their 1541 state memory usage will still have message state that will 1542 identify the second CON as a retransmission. Clients that 1543 actually expect more messages from the server 1544 [I-D.ietf-core-observe] will have to keep state in any case.) 1546 5.4. Options 1548 Both requests and responses may include a list of one or more 1549 options. For example, the URI in a request is transported in several 1550 options, and meta-data that would be carried in an HTTP header in 1551 HTTP is supplied as options as well. 1553 CoAP defines a single set of options that are used in both requests 1554 and responses: 1556 o Content-Format 1558 o ETag 1560 o Location-Path 1562 o Location-Query 1564 o Max-Age 1566 o Proxy-Uri 1568 o Proxy-Scheme 1570 o Uri-Host 1572 o Uri-Path 1574 o Uri-Port 1576 o Uri-Query 1578 o Accept 1580 o If-Match 1582 o If-None-Match 1584 The semantics of these options along with their properties are 1585 defined in detail in Section 5.10. 1587 Not all options are defined for use with all methods and response 1588 codes. The possible options for methods and response codes are 1589 defined in Section 5.8 and Section 5.9 respectively. In case an 1590 option is not defined for a method or response code, it MUST NOT be 1591 included by a sender and MUST be treated like an unrecognized option 1592 by a recipient. 1594 5.4.1. Critical/Elective 1596 Options fall into one of two classes: "critical" or "elective". The 1597 difference between these is how an option unrecognized by an endpoint 1598 is handled: 1600 o Upon reception, unrecognized options of class "elective" MUST be 1601 silently ignored. 1603 o Unrecognized options of class "critical" that occur in a 1604 Confirmable request MUST cause the return of a 4.02 (Bad Option) 1605 response. This response SHOULD include a diagnostic payload 1606 describing the unrecognized option(s) (see Section 5.5.2). 1608 o Unrecognized options of class "critical" that occur in a 1609 Confirmable response, or piggy-backed in an Acknowledgement, MUST 1610 cause the response to be rejected (Section 4.2). 1612 o Unrecognized options of class "critical" that occur in a Non- 1613 confirmable message MUST cause the message to be rejected 1614 (Section 4.3). 1616 Note that, whether critical or elective, an option is never 1617 "mandatory" (it is always optional): These rules are defined in order 1618 to enable implementations to stop processing options they do not 1619 understand or implement. 1621 Critical/Elective rules apply to non-proxying endpoints. A proxy 1622 processes options based on Unsafe/Safe classes as defined in 1623 Section 5.7. 1625 5.4.2. Proxy Unsafe/Safe and Cache-Key 1627 In addition to an option being marked as Critical or Elective, 1628 options are also classified based on how a proxy is to deal with the 1629 option if it does not recognize it. For this purpose, an option can 1630 either be considered Unsafe to Forward (UnSafe is set) or Safe to 1631 Forward (UnSafe is clear). 1633 In addition, for options that are marked Safe to Forward, the option 1634 indicates whether it is intended to be part of the Cache-Key in a 1635 request (some of the NoCacheKey bits are 0) or not (all NoCacheKey 1636 bits are 1; see Section 5.4.6). 1638 Note: The Cache-Key indication is relevant only for proxies that do 1639 not implement the given option as a request option and instead 1640 rely on the Safe/Unsafe indication only. E.g., for ETag, actually 1641 using the request option as a cache key is grossly inefficient, 1642 but it is the best thing one can do if ETag is not implemented by 1643 a proxy, as the response is going to differ based on the presence 1644 of the request option. A more useful proxy that does implement 1645 the ETag request option is not using ETag as a cache key. 1647 NoCacheKey is indicated in three bits so that only one out of 1648 eight codepoints is qualified as NoCacheKey, assuming this is the 1649 less likely case. 1651 Proxy behavior with regard to these classes is defined in 1652 Section 5.7. 1654 5.4.3. Length 1656 Option values are defined to have a specific length, often in the 1657 form of an upper and lower bound. If the length of an option value 1658 in a request is outside the defined range, that option MUST be 1659 treated like an unrecognized option (see Section 5.4.1). 1661 5.4.4. Default Values 1663 Options may be defined to have a default value. If the value of 1664 option is intended to be this default value, the option SHOULD NOT be 1665 included in the message. If the option is not present, the default 1666 value MUST be assumed. 1668 Where a critical option has a default value, this is chosen in such a 1669 way that the absence of the option in a message can be processed 1670 properly both by implementations unaware of the critical option and 1671 by implementations that interpret this absence as the presence of the 1672 default value for the option. 1674 5.4.5. Repeatable Options 1676 The definition of some options specifies that those options are 1677 repeatable. An option that is repeatable MAY be included one or more 1678 times in a message. An option that is not repeatable MUST NOT be 1679 included more than once in a message. 1681 If a message includes an option with more occurrences than the option 1682 is defined for, the additional option occurrences MUST be treated 1683 like an unrecognized option (see Section 5.4.1). 1685 5.4.6. Option Numbers 1687 An Option is identified by an option number, which also provides some 1688 additional semantics information: e.g., odd numbers indicate a 1689 critical option, while even numbers indicate an elective option. 1690 Note that this is not just a convention, it is a feature of the 1691 protocol: Whether an option is elective or critical is entirely 1692 determined by whether its option number is even or odd. 1694 More generally speaking, an Option number is constructed with a bit 1695 mask to indicate if an option is Critical/Elective, Unsafe/Safe and 1696 in the case of Safe, also a Cache-Key indication as shown by the 1697 following figure. When bit 7 (the least significant bit) is 1, an 1698 option is Critical (and likewise Elective when 0). When bit 6 is 1, 1699 an option is Unsafe (and likewise Safe when 0). When bit 6 is 0, 1700 i.e., the option is not Unsafe, it is not a Cache-Key (NoCacheKey) if 1701 and only if bits 3-5 are all set to 1; all other bit combinations 1702 mean that it indeed is a Cache-Key. These classes of options are 1703 explained in the next sections. 1705 0 1 2 3 4 5 6 7 1706 +---+---+---+---+---+---+---+---+ 1707 | | NoCacheKey| U | C | 1708 +---+---+---+---+---+---+---+---+ 1710 Figure 10: Option Number Mask 1712 An endpoint may use an equivalent of the C code in Figure 11 to 1713 derive the characteristics of an option number "onum". 1715 Critical = (onum & 1); 1716 UnSafe = (onum & 2); 1717 NoCacheKey = ((onum & 0x1e) == 0x1c); 1719 Figure 11: Determining Characteristics from an Option Number 1721 The option numbers for the options defined in this document are 1722 listed in the CoAP Option Number Registry (Section 12.2). 1724 5.5. Payloads and Representations 1726 Both requests and responses may include a payload, depending on the 1727 method or response code respectively. If a method or response code 1728 is not defined to have a payload, then a sender MUST NOT include one, 1729 and a recipient MUST ignore it. 1731 5.5.1. Representation 1733 The payload of requests or of responses indicating success is 1734 typically a representation of a resource or the result of the 1735 requested action. Its format is specified by the Internet media type 1736 and content coding given by the Content-Format Option. In the 1737 absence of this option, no default value is assumed and the format 1738 will need to be inferred by the application (e.g., from the 1739 application context). Payload "sniffing" SHOULD only be attempted if 1740 no content type is given. 1742 Implementation Note: On a quality of implementation level, there is 1743 a strong expectation that a Content-Format indication will be 1744 provided with resource representations whenever possible. This is 1745 not a "SHOULD"-level requirement solely because it is not a 1746 protocol requirement, and it also would be difficult to outline 1747 exactly in what cases this expectation can be violated. 1749 For responses indicating a client or server error, the payload is 1750 considered a representation of the result of the requested action 1751 only if a Content-Format Option is given. In the absence of this 1752 option, the payload is a Diagnostic Payload (Section 5.5.2). 1754 5.5.2. Diagnostic Payload 1756 If no Content-Format option is given, the payload of responses 1757 indicating a client or server error is a brief human-readable 1758 diagnostic message, explaining the error situation. This diagnostic 1759 message MUST be encoded using UTF-8 [RFC3629], more specifically 1760 using Net-Unicode form [RFC5198]. 1762 The message is similar to the Reason-Phrase on an HTTP status line. 1763 It is not intended for end-users but for software engineers that 1764 during debugging need to interpret it in the context of the present, 1765 English-language specification; therefore no mechanism for language 1766 tagging is needed or provided. In contrast to what is usual in HTTP, 1767 the payload SHOULD be empty if there is no additional information 1768 beyond the response code. 1770 5.5.3. Selected Representation 1772 Not all responses carry a payload that provides a representation of 1773 the resource addressed by the request. It is, however, sometimes 1774 useful to be able to refer to such a representation in relation to a 1775 response, independent of whether it actually was enclosed. 1777 We use the term "selected representation" to refer to the current 1778 representation of a target resource that would have been selected in 1779 a successful response if the corresponding request had used the 1780 method GET and excluded any conditional request options 1781 (Section 5.10.8). 1783 Certain response options provide metadata about the selected 1784 representation, which might differ from the representation included 1785 in the message for responses to some state-changing methods. Of the 1786 response options defined in this specification, only the ETag 1787 response option (Section 5.10.6) is defined as selected 1788 representation metadata. 1790 5.5.4. Content Negotiation 1792 A server may be able to supply a representation for a resource in one 1793 of multiple representation formats. Without further information from 1794 the client, it will provide the representation in the format it 1795 prefers. 1797 By using the Accept Option (Section 5.10.4) in a request, the client 1798 can indicate which content-format it prefers to receive. 1800 5.6. Caching 1802 CoAP endpoints MAY cache responses in order to reduce the response 1803 time and network bandwidth consumption on future, equivalent 1804 requests. 1806 The goal of caching in CoAP is to reuse a prior response message to 1807 satisfy a current request. In some cases, a stored response can be 1808 reused without the need for a network request, reducing latency and 1809 network round-trips; a "freshness" mechanism is used for this purpose 1810 (see Section 5.6.1). Even when a new request is required, it is 1811 often possible to reuse the payload of a prior response to satisfy 1812 the request, thereby reducing network bandwidth usage; a "validation" 1813 mechanism is used for this purpose (see Section 5.6.2). 1815 Unlike HTTP, the cacheability of CoAP responses does not depend on 1816 the request method, but the Response Code. The cacheability of each 1817 Response Code is defined along the Response Code definitions in 1818 Section 5.9. Response Codes that indicate success and are 1819 unrecognized by an endpoint MUST NOT be cached. 1821 For a presented request, a CoAP endpoint MUST NOT use a stored 1822 response, unless: 1824 o the presented request method and that used to obtain the stored 1825 response match, 1827 o all options match between those in the presented request and those 1828 of the request used to obtain the stored response (which includes 1829 the request URI), except that there is no need for a match of any 1830 request options marked as NoCacheKey (Section 5.4) or recognized 1831 by the Cache and fully interpreted with respect to its specified 1832 cache behavior (such as the ETag request option, Section 5.10.6, 1833 see also Section 5.4.2), and 1835 o the stored response is either fresh or successfully validated as 1836 defined below. 1838 5.6.1. Freshness Model 1840 When a response is "fresh" in the cache, it can be used to satisfy 1841 subsequent requests without contacting the origin server, thereby 1842 improving efficiency. 1844 The mechanism for determining freshness is for an origin server to 1845 provide an explicit expiration time in the future, using the Max-Age 1846 Option (see Section 5.10.5). The Max-Age Option indicates that the 1847 response is to be considered not fresh after its age is greater than 1848 the specified number of seconds. 1850 The Max-Age Option defaults to a value of 60. Thus, if it is not 1851 present in a cacheable response, then the response is considered not 1852 fresh after its age is greater than 60 seconds. If an origin server 1853 wishes to prevent caching, it MUST explicitly include a Max-Age 1854 Option with a value of zero seconds. 1856 If a client has a fresh stored response and makes a new request 1857 matching the request for that stored response, the new response 1858 invalidates the old response. 1860 5.6.2. Validation Model 1862 When an endpoint has one or more stored responses for a GET request, 1863 but cannot use any of them (e.g., because they are not fresh), it can 1864 use the ETag Option (Section 5.10.6) in the GET request to give the 1865 origin server an opportunity to both select a stored response to be 1866 used, and to update its freshness. This process is known as 1867 "validating" or "revalidating" the stored response. 1869 When sending such a request, the endpoint SHOULD add an ETag Option 1870 specifying the entity-tag of each stored response that is applicable. 1872 A 2.03 (Valid) response indicates the stored response identified by 1873 the entity-tag given in the response's ETag Option can be reused, 1874 after updating it as described in Section 5.9.1.3. 1876 Any other response code indicates that none of the stored responses 1877 nominated in the request is suitable. Instead, the response SHOULD 1878 be used to satisfy the request and MAY replace the stored response. 1880 5.7. Proxying 1882 A proxy is a CoAP endpoint that can be tasked by CoAP clients to 1883 perform requests on their behalf. This may be useful, for example, 1884 when the request could otherwise not be made, or to service the 1885 response from a cache in order to reduce response time and network 1886 bandwidth or energy consumption. 1888 In an overall architecture for a Constrained RESTful Environment, 1889 proxies can serve quite different purposes. Proxies can be 1890 explicitly selected by clients, a role that we term "forward-proxy". 1891 Proxies can also be inserted to stand in for origin servers, a role 1892 that we term "reverse-proxy". Orthogonal to this distinction, a 1893 proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP 1894 proxy) or translate from or to a different protocol ("cross-proxy"). 1895 Full definitions of these terms are provided in Section 1.2. 1897 Notes: The terminology in this specification has been selected to be 1898 culturally compatible with the terminology used in the wider Web 1899 application environments, without necessarily matching it in every 1900 detail (which may not even be relevant to Constrained RESTful 1901 Environments). Not too much semantics should be ascribed to the 1902 components of the terms (such as "forward", "reverse", or 1903 "cross"). 1905 HTTP proxies, besides acting as HTTP proxies, often offer a 1906 transport protocol proxying function ("CONNECT") to enable end-to- 1907 end transport layer security through the proxy. No such function 1908 is defined for CoAP-to-CoAP proxies in this specification, as 1909 forwarding of UDP packets is unlikely to be of much value in 1910 Constrained RESTful environments. See also Section 10.2.7 for the 1911 cross-proxy case. 1913 5.7.1. Proxy Operation 1915 A proxy generally needs a way to determine potential request 1916 parameters for a request to a destination based on the request it 1917 received. This way is fully specified for a forward-proxy, but may 1918 depend on the specific configuration for a reverse-proxy. In 1919 particular, the client of a reverse-proxy generally does not indicate 1920 a locator for the destination, necessitating some form of namespace 1921 translation in the reverse-proxy. However, some aspects of the 1922 operation of proxies are common to all its forms. 1924 If a proxy does not employ a cache, then it simply forwards the 1925 translated request to the determined destination. Otherwise, if it 1926 does employ a cache but does not have a stored response that matches 1927 the translated request and is considered fresh, then it needs to 1928 refresh its cache according to Section 5.6. For options in the 1929 request that the proxy recognizes, it knows whether the option is 1930 intended to act as part of the key used in looking up the cached 1931 value or not. E.g., since requests for different Uri-Path values 1932 address different resources, Uri-Path values are always parts of the 1933 cache key, while, e.g., Token values are never part of the cache key. 1935 For options that the proxy does not recognize but that are marked 1936 Safe in the option number, the option also indicates whether it is to 1937 be included in the cache key (NoCacheKey is not all set) or not 1938 (NoCacheKey is all set). (Options that are unrecognized and marked 1939 Unsafe lead to 4.02 Bad Option.) 1941 If the request to the destination times out, then a 5.04 (Gateway 1942 Timeout) response MUST be returned. If the request to the 1943 destination returns a response that cannot be processed by the proxy 1944 (e.g, due to unrecognized critical options, message format errors), 1945 then a 5.02 (Bad Gateway) response MUST be returned. Otherwise, the 1946 proxy returns the response to the client. 1948 If a response is generated out of a cache, it MUST be generated with 1949 a Max-Age Option that does not extend the max-age originally set by 1950 the server, considering the time the resource representation spent in 1951 the cache. E.g., the Max-Age Option could be adjusted by the proxy 1952 for each response using the formula: 1954 proxy-max-age = original-max-age - cache-age 1956 For example if a request is made to a proxied resource that was 1957 refreshed 20 seconds ago and had an original Max-Age of 60 seconds, 1958 then that resource's proxied max-age is now 40 seconds. Considering 1959 potential network delays on the way from the origin server, a proxy 1960 SHOULD be conservative in the max-age values offered. 1962 All options present in a proxy request MUST be processed at the 1963 proxy. Unsafe options in a request that are not recognized by the 1964 proxy MUST lead to a 4.02 (Bad Option) response being returned by the 1965 proxy. A CoAP-to-CoAP proxy MUST forward to the origin server all 1966 Safe options that it does not recognize. Similarly, Unsafe options 1967 in a response that are not recognized by the CoAP-to-CoAP proxy 1968 server MUST lead to a 5.02 (Bad Gateway) response. Again, Safe 1969 options that are not recognized MUST be forwarded. 1971 Additional considerations for cross-protocol proxying between CoAP 1972 and HTTP are discussed in Section 10. 1974 5.7.2. Forward-Proxies 1976 CoAP distinguishes between requests made (as if) to an origin server 1977 and a request made through a forward-proxy. CoAP requests to a 1978 forward-proxy are made as normal Confirmable or Non-confirmable 1979 requests to the forward-proxy endpoint, but specify the request URI 1980 in a different way: The request URI in a proxy request is specified 1981 as a string in the Proxy-Uri Option (see Section 5.10.2), while the 1982 request URI in a request to an origin server is split into the Uri- 1983 Host, Uri-Port, Uri-Path and Uri-Query Options (see Section 5.10.1); 1984 alternatively the URI in a proxy request can be assembled from a 1985 Proxy-Scheme option and the split options mentioned. 1987 When a proxy request is made to an endpoint and the endpoint is 1988 unwilling or unable to act as proxy for the request URI, it MUST 1989 return a 5.05 (Proxying Not Supported) response. If the authority 1990 (host and port) is recognized as identifying the proxy endpoint 1991 itself (see Section 5.10.2), then the request MUST be treated as a 1992 local (non-proxied) request. 1994 Unless a proxy is configured to forward the proxy request to another 1995 proxy, it MUST translate the request as follows: The scheme of the 1996 request URI defines the outgoing protocol and its details (e.g., CoAP 1997 is used over UDP for the "coap" scheme and over DTLS for the "coaps" 1998 scheme.) For a CoAP-to-CoAP proxy, the origin server's IP address 1999 and port are determined by the authority component of the request 2000 URI, and the request URI is decoded and split into the Uri-Host, Uri- 2001 Port, Uri-Path and Uri-Query Options. This consumes the Proxy-Uri or 2002 Proxy-Scheme option, which is therefore not forwarded to the origin 2003 server. 2005 5.7.3. Reverse-Proxies 2007 Reverse-proxies do not make use of the Proxy-Uri or Proxy-Scheme 2008 options, but need to determine the destination (next hop) of a 2009 request from information in the request and information in their 2010 configuration. E.g., a reverse-proxy might offer various resources 2011 the existence of which it has learned through resource discovery as 2012 if they were its own resources. The reverse-proxy is free to build a 2013 namespace for the URIs that identify these resources. A reverse- 2014 proxy may also build a namespace that gives the client more control 2015 over where the request goes, e.g. by embedding host identifiers and 2016 port numbers into the URI path of the resources offered. 2018 In processing the response, a reverse-proxy has to be careful that 2019 ETag option values from different sources are not mixed up on one 2020 resource offered to its clients. In many cases, the ETag can be 2021 forwarded unchanged. If the mapping from a resource offered by the 2022 reverse-proxy to resources offered by its various origin servers is 2023 not unique, the reverse-proxy may need to generate a new ETag, making 2024 sure the semantics of this option are properly preserved. 2026 5.8. Method Definitions 2028 In this section each method is defined along with its behavior. A 2029 request with an unrecognized or unsupported Method Code MUST generate 2030 a 4.05 (Method Not Allowed) piggy-backed response. 2032 5.8.1. GET 2034 The GET method retrieves a representation for the information that 2035 currently corresponds to the resource identified by the request URI. 2036 If the request includes an Accept Option, that indicates the 2037 preferred content-format of a response. If the request includes an 2038 ETag Option, the GET method requests that ETag be validated and that 2039 the representation be transferred only if validation failed. Upon 2040 success a 2.05 (Content) or 2.03 (Valid) response code SHOULD be 2041 present in the response. 2043 The GET method is safe and idempotent. 2045 5.8.2. POST 2047 The POST method requests that the representation enclosed in the 2048 request be processed. The actual function performed by the POST 2049 method is determined by the origin server and dependent on the target 2050 resource. It usually results in a new resource being created or the 2051 target resource being updated. 2053 If a resource has been created on the server, the response returned 2054 by the server SHOULD have a 2.01 (Created) response code and SHOULD 2055 include the URI of the new resource in a sequence of one or more 2056 Location-Path and/or Location-Query Options (Section 5.10.7). If the 2057 POST succeeds but does not result in a new resource being created on 2058 the server, the response SHOULD have a 2.04 (Changed) response code. 2059 If the POST succeeds and results in the target resource being 2060 deleted, the response SHOULD have a 2.02 (Deleted) response code. 2062 POST is neither safe nor idempotent. 2064 5.8.3. PUT 2066 The PUT method requests that the resource identified by the request 2067 URI be updated or created with the enclosed representation. The 2068 representation format is specified by the media type and content 2069 coding given in the Content-Format Option, if provided. 2071 If a resource exists at the request URI the enclosed representation 2072 SHOULD be considered a modified version of that resource, and a 2.04 2073 (Changed) response code SHOULD be returned. If no resource exists 2074 then the server MAY create a new resource with that URI, resulting in 2075 a 2.01 (Created) response code. If the resource could not be created 2076 or modified, then an appropriate error response code SHOULD be sent. 2078 Further restrictions to a PUT can be made by including the If-Match 2079 (see Section 5.10.8.1) or If-None-Match (see Section 5.10.8.2) 2080 options in the request. 2082 PUT is not safe, but is idempotent. 2084 5.8.4. DELETE 2086 The DELETE method requests that the resource identified by the 2087 request URI be deleted. A 2.02 (Deleted) response code SHOULD be 2088 used on success or in case the resource did not exist before the 2089 request. 2091 DELETE is not safe, but is idempotent. 2093 5.9. Response Code Definitions 2095 Each response code is described below, including any options required 2096 in the response. Where appropriate, some of the codes will be 2097 specified in regards to related response codes in HTTP [RFC2616]; 2098 this does not mean that any such relationship modifies the HTTP 2099 mapping specified in Section 10. 2101 5.9.1. Success 2.xx 2103 This class of status code indicates that the clients request was 2104 successfully received, understood, and accepted. 2106 5.9.1.1. 2.01 Created 2108 Like HTTP 201 "Created", but only used in response to POST and PUT 2109 requests. The payload returned with the response, if any, is a 2110 representation of the action result. 2112 If the response includes one or more Location-Path and/or Location- 2113 Query Options, the values of these options specify the location at 2114 which the resource was created. Otherwise, the resource was created 2115 at the request URI. A cache receiving this response MUST mark any 2116 stored response for the created resource as not fresh. 2118 This response is not cacheable. 2120 5.9.1.2. 2.02 Deleted 2122 Like HTTP 204 "No Content", but only used in response to DELETE 2123 requests. The payload returned with the response, if any, is a 2124 representation of the action result. 2126 This response is not cacheable. However, a cache MUST mark any 2127 stored response for the deleted resource as not fresh. 2129 5.9.1.3. 2.03 Valid 2131 Related to HTTP 304 "Not Modified", but only used to indicate that 2132 the response identified by the entity-tag identified by the included 2133 ETag Option is valid. Accordingly, the response MUST include an ETag 2134 Option, and MUST NOT include a payload. 2136 When a cache that recognizes and processes the ETag response option 2137 receives a 2.03 (Valid) response, it MUST update the stored response 2138 with the value of the Max-Age Option included in the response 2139 (explicitly, or implicitly as a default value; see also 2140 Section 5.6.2). For each type of Safe option present in the 2141 response, the (possibly empty) set of options of this type that are 2142 present in the stored response MUST be replaced with the set of 2143 options of this type in the response received. (Unsafe options may 2144 trigger similar option specific processing as defined by the option.) 2146 5.9.1.4. 2.04 Changed 2148 Like HTTP 204 "No Content", but only used in response to POST and PUT 2149 requests. The payload returned with the response, if any, is a 2150 representation of the action result. 2152 This response is not cacheable. However, a cache MUST mark any 2153 stored response for the changed resource as not fresh. 2155 5.9.1.5. 2.05 Content 2157 Like HTTP 200 "OK", but only used in response to GET requests. 2159 The payload returned with the response is a representation of the 2160 target resource. 2162 This response is cacheable: Caches can use the Max-Age Option to 2163 determine freshness (see Section 5.6.1) and (if present) the ETag 2164 Option for validation (see Section 5.6.2). 2166 5.9.2. Client Error 4.xx 2168 This class of response code is intended for cases in which the client 2169 seems to have erred. These response codes are applicable to any 2170 request method. 2172 The server SHOULD include a diagnostic payload under the conditions 2173 detailed in Section 5.5.2. 2175 Responses of this class are cacheable: Caches can use the Max-Age 2176 Option to determine freshness (see Section 5.6.1). They cannot be 2177 validated. 2179 5.9.2.1. 4.00 Bad Request 2181 Like HTTP 400 "Bad Request". 2183 5.9.2.2. 4.01 Unauthorized 2185 The client is not authorized to perform the requested action. The 2186 client SHOULD NOT repeat the request without previously improving its 2187 authentication status to the server. Which specific mechanism can be 2188 used for this is outside this document's scope; see also Section 9. 2190 5.9.2.3. 4.02 Bad Option 2192 The request could not be understood by the server due to one or more 2193 unrecognized or malformed options. The client SHOULD NOT repeat the 2194 request without modification. 2196 5.9.2.4. 4.03 Forbidden 2198 Like HTTP 403 "Forbidden". 2200 5.9.2.5. 4.04 Not Found 2202 Like HTTP 404 "Not Found". 2204 5.9.2.6. 4.05 Method Not Allowed 2206 Like HTTP 405 "Method Not Allowed", but with no parallel to the 2207 "Allow" header field. 2209 5.9.2.7. 4.06 Not Acceptable 2211 Like HTTP 406 "Not Acceptable", but with no response entity. 2213 5.9.2.8. 4.12 Precondition Failed 2215 Like HTTP 412 "Precondition Failed". 2217 5.9.2.9. 4.13 Request Entity Too Large 2219 Like HTTP 413 "Request Entity Too Large". 2221 5.9.2.10. 4.15 Unsupported Content-Format 2223 Like HTTP 415 "Unsupported Media Type". 2225 5.9.3. Server Error 5.xx 2227 This class of response code indicates cases in which the server is 2228 aware that it has erred or is incapable of performing the request. 2229 These response codes are applicable to any request method. 2231 The server SHOULD include a diagnostic payload under the conditions 2232 detailed in Section 5.5.2. 2234 Responses of this class are cacheable: Caches can use the Max-Age 2235 Option to determine freshness (see Section 5.6.1). They cannot be 2236 validated. 2238 5.9.3.1. 5.00 Internal Server Error 2240 Like HTTP 500 "Internal Server Error". 2242 5.9.3.2. 5.01 Not Implemented 2244 Like HTTP 501 "Not Implemented". 2246 5.9.3.3. 5.02 Bad Gateway 2248 Like HTTP 502 "Bad Gateway". 2250 5.9.3.4. 5.03 Service Unavailable 2252 Like HTTP 503 "Service Unavailable", but using the Max-Age Option in 2253 place of the "Retry-After" header field to indicate the number of 2254 seconds after which to retry. 2256 5.9.3.5. 5.04 Gateway Timeout 2258 Like HTTP 504 "Gateway Timeout". 2260 5.9.3.6. 5.05 Proxying Not Supported 2262 The server is unable or unwilling to act as a forward-proxy for the 2263 URI specified in the Proxy-Uri Option or using Proxy-Scheme (see 2264 Section 5.10.2). 2266 5.10. Option Definitions 2268 The individual CoAP options are summarized in Table 3 and explained 2269 in the subsections of this section. 2271 In this table, the C, U, and N columns indicate the properties, 2272 Critical, UnSafe, and NoCacheKey, respectively. Since NoCacheKey 2273 only has a meaning for options that are safe to foward (not marked 2274 Unsafe), the column is filled with a dash for UnSafe options. (The 2275 present specification does not define any NoCacheKey options, but the 2276 format of the table is intended to be useful for additional 2277 specifications.) 2279 +-----+---+---+---+---+----------------+--------+--------+----------+ 2280 | No. | C | U | N | R | Name | Format | Length | Default | 2281 +-----+---+---+---+---+----------------+--------+--------+----------+ 2282 | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | 2283 | 3 | x | x | - | | Uri-Host | string | 1-255 | (see | 2284 | | | | | | | | | below) | 2285 | 4 | | | | x | ETag | opaque | 1-8 | (none) | 2286 | 5 | x | | | | If-None-Match | empty | 0 | (none) | 2287 | 7 | x | x | - | | Uri-Port | uint | 0-2 | (see | 2288 | | | | | | | | | below) | 2289 | 8 | | | | x | Location-Path | string | 0-255 | (none) | 2290 | 11 | x | x | - | x | Uri-Path | string | 0-255 | (none) | 2291 | 12 | | | | | Content-Format | uint | 0-2 | (none) | 2292 | 14 | | x | - | | Max-Age | uint | 0-4 | 60 | 2293 | 15 | x | x | - | x | Uri-Query | string | 0-255 | (none) | 2294 | 16 | | | | | Accept | uint | 0-2 | (none) | 2295 | 20 | | | | x | Location-Query | string | 0-255 | (none) | 2296 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | (none) | 2297 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | (none) | 2298 +-----+---+---+---+---+----------------+--------+--------+----------+ 2300 C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable 2302 Table 3: Options 2304 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query 2306 The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to 2307 specify the target resource of a request to a CoAP origin server. 2308 The options encode the different components of the request URI in a 2309 way that no percent-encoding is visible in the option values and that 2310 the full URI can be reconstructed at any involved endpoint. The 2311 syntax of CoAP URIs is defined in Section 6. 2313 The steps for parsing URIs into options is defined in Section 6.4. 2314 These steps result in zero or more Uri-Host, Uri-Port, Uri-Path and 2315 Uri-Query Options being included in a request, where each option 2316 holds the following values: 2318 o the Uri-Host Option specifies the Internet host of the resource 2319 being requested, 2321 o the Uri-Port Option specifies the transport layer port number of 2322 the resource, 2324 o each Uri-Path Option specifies one segment of the absolute path to 2325 the resource, and 2327 o each Uri-Query Option specifies one argument parameterizing the 2328 resource. 2330 Note: Fragments ([RFC3986], Section 3.5) are not part of the request 2331 URI and thus will not be transmitted in a CoAP request. 2333 The default value of the Uri-Host Option is the IP literal 2334 representing the destination IP address of the request message. 2335 Likewise, the default value of the Uri-Port Option is the destination 2336 UDP port. The default values for the Uri-Host and Uri-Port Options 2337 are sufficient for requests to most servers. Explicit Uri-Host and 2338 Uri-Port Options are typically used when an endpoint hosts multiple 2339 virtual servers. 2341 The Uri-Path and Uri-Query Option can contain any character sequence. 2342 No percent-encoding is performed. The value of a Uri-Path Option 2343 MUST NOT be "." or ".." (as the request URI must be resolved before 2344 parsing it into options). 2346 The steps for constructing the request URI from the options are 2347 defined in Section 6.5. Note that an implementation does not 2348 necessarily have to construct the URI; it can simply look up the 2349 target resource by looking at the individual options. 2351 Examples can be found in Appendix B. 2353 5.10.2. Proxy-Uri and Proxy-Scheme 2355 The Proxy-Uri Option is used to make a request to a forward-proxy 2356 (see Section 5.7). The forward-proxy is requested to forward the 2357 request or service it from a valid cache, and return the response. 2359 The option value is an absolute-URI ([RFC3986], Section 4.3). 2361 Note that the forward-proxy MAY forward the request on to another 2362 proxy or directly to the server specified by the absolute-URI. In 2363 order to avoid request loops, a proxy MUST be able to recognize all 2364 of its server names, including any aliases, local variations, and the 2365 numeric IP addresses. 2367 An endpoint receiving a request with a Proxy-Uri Option that is 2368 unable or unwilling to act as a forward-proxy for the request MUST 2369 cause the return of a 5.05 (Proxying Not Supported) response. 2371 The Proxy-Uri Option MUST take precedence over any of the Uri-Host, 2372 Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included 2373 at the same time in a request containing the Proxy-Uri Option). 2375 As a special case to simplify many proxy clients, the absolute-URI 2376 can be constructed from the Uri-* options. When a Proxy-Scheme 2377 Option is present, the absolute-URI is constructed as follows: A CoAP 2378 URI is constructed from the Uri-* options as defined in Section 6.5. 2379 In the resulting URI, the initial scheme up to, but not including the 2380 following colon is then replaced by the content of the Proxy-Scheme 2381 Option. 2383 5.10.3. Content-Format 2385 The Content-Format Option indicates the representation format of the 2386 message payload. The representation format is given as a numeric 2387 content format identifier that is defined in the CoAP Content Format 2388 registry (Section 12.3). In the absence of the option, no default 2389 value is assumed, i.e. the representation format of any 2390 representation message payload is indeterminate (Section 5.5). 2392 5.10.4. Accept 2394 The CoAP Accept option can be used to indicate which Content-Format 2395 is acceptable to the client. The representation format is given as a 2396 numeric Content-Format identifier that is defined in the CoAP 2397 Content-Format registry (Section 12.3). If no Accept option is 2398 given, the client does not express a preference (thus no default 2399 value is assumed). The client prefers the representation returned by 2400 the server to be in the Content-Format indicated. The server SHOULD 2401 return the preferred Content-Format if available. If the preferred 2402 Content-Format cannot be returned, then a 4.06 "Not Acceptable" 2403 SHOULD be sent as a response. 2405 Note that as a server might not support the Accept option (and thus 2406 would ignore it as it is elective), the client needs to be prepared 2407 to receive a representation in a different Content-Format. The 2408 client can simply discard a representation it can not make use of. 2410 5.10.5. Max-Age 2412 The Max-Age Option indicates the maximum time a response may be 2413 cached before it MUST be considered not fresh (see Section 5.6.1). 2415 The option value is an integer number of seconds between 0 and 2416 2**32-1 inclusive (about 136.1 years). A default value of 60 seconds 2417 is assumed in the absence of the option in a response. 2419 The value is intended to be current at the time of transmission. 2420 Servers that provide resources with strict tolerances on the value of 2421 Max-Age SHOULD update the value before each retransmission. (See 2422 also Section 5.7.1.) 2424 5.10.6. ETag 2426 An entity-tag is intended for use as a resource-local identifier for 2427 differentiating between representations of the same resource that 2428 vary over time. It is generated by the server providing the 2429 resource, which may generate it in any number of ways including a 2430 version, checksum, hash or time. An endpoint receiving an entity-tag 2431 MUST treat it as opaque and make no assumptions about its content or 2432 structure. (Endpoints that generate an entity-tag are encouraged to 2433 use the most compact representation possible, in particular in 2434 regards to clients and intermediaries that may want to store multiple 2435 ETag values.) 2437 5.10.6.1. ETag as a Response Option 2439 The ETag Option in a response provides the current value (i.e., after 2440 the request was processed) of the entity-tag for the "tagged 2441 representation". If no Location-* options are present, the tagged 2442 representation is the selected representation (Section 5.5.3) of the 2443 target resource. If one or more Location-* options are present and 2444 thus a location URI is indicated (Section 5.10.7), the tagged 2445 representation is the representation that would be retrieved by a GET 2446 request to the location URI. 2448 An ETag response option can be included with any response for which 2449 there is a tagged representation (e.g., it would not be meaningful in 2450 a 4.04 or 4.00 response). The ETag Option MUST NOT occur more than 2451 once in a response. 2453 There is no default value for the ETag Option; if it is not present 2454 in a response, the server makes no statement about the entity-tag for 2455 the tagged representation. 2457 5.10.6.2. ETag as a Request Option 2459 In a GET request, an endpoint that has one or more representations 2460 previously obtained from the resource, and has obtained ETag response 2461 options with these, can specify an instance of the ETag Option for 2462 one or more of these stored responses. 2464 A server can issue a 2.03 Valid response (Section 5.9.1.3) in place 2465 of a 2.05 Content response if one of the ETags given is the entity- 2466 tag for the current representation, i.e. is valid; the 2.03 Valid 2467 response then echoes this specific ETag in a response option. 2469 In effect, a client can determine if any of the stored 2470 representations is current (see Section 5.6.2) without needing to 2471 transfer them again. 2473 The ETag Option MAY occur zero, one or more times in a request. 2475 5.10.7. Location-Path and Location-Query 2477 The Location-Path and Location-Query Options together indicate a 2478 relative URI that consists either of an absolute path, a query string 2479 or both. A combination of these options is included in a 2.01 2480 (Created) response to indicate the location of the resource created 2481 as the result of a POST request (see Section 5.8.2). The location is 2482 resolved relative to the request URI. 2484 If a response with one or more Location-Path and/or Location-Query 2485 Options passes through a cache that interprets these options and the 2486 implied URI identifies one or more currently stored responses, those 2487 entries MUST be marked as not fresh. 2489 Each Location-Path Option specifies one segment of the absolute path 2490 to the resource, and each Location-Query Option specifies one 2491 argument parameterizing the resource. The Location-Path and 2492 Location-Query Option can contain any character sequence. No 2493 percent-encoding is performed. The value of a Location-Path Option 2494 MUST NOT be "." or "..". 2496 The steps for constructing the location URI from the options are 2497 analogous to Section 6.5, except that the first five steps are 2498 skipped and the result is a relative URI-reference, which is then 2499 interpreted relative to the request URI. Note that the relative URI- 2500 reference constructed this way always includes an absolute-path 2501 (e.g., leaving out Location-Path but supplying Location-Query means 2502 the path component in the URI is "/"). 2504 The options that are used to compute the relative URI-reference are 2505 collectively called Location-* options. Beyond Location-Path and 2506 Location-Query, more Location-* options may be defined in the future, 2507 and have been reserved option numbers 128, 132, 136, and 140. If any 2508 of these reserved option numbers occurs in addition to Location-Path 2509 and/or Location-Query and are not supported, then a 4.02 (Bad Option) 2510 error MUST be returned. 2512 5.10.8. Conditional Request Options 2514 Conditional request options enable a client to ask the server to 2515 perform the request only if certain conditions specified by the 2516 option are fulfilled. 2518 For each of these options, if the condition given is not fulfilled, 2519 then the the server MUST NOT perform the requested method. Instead, 2520 the server MUST respond with the 4.12 (Precondition Failed) response 2521 code. 2523 If the condition is fulfilled, the server performs the request method 2524 as if the conditional request options were not present. 2526 If the request would, without the conditional request options, result 2527 in anything other than a 2.xx or 4.12 response code, then any 2528 conditional request options MAY be ignored. 2530 5.10.8.1. If-Match 2532 The If-Match Option MAY be used to make a request conditional on the 2533 current existence or value of an ETag for one or more representations 2534 of the target resource. If-Match is generally useful for resource 2535 update requests, such as PUT requests, as a means for protecting 2536 against accidental overwrites when multiple clients are acting in 2537 parallel on the same resource (i.e., the "lost update" problem). 2539 The value of an If-Match option is either an ETag or the empty 2540 string. An If-Match option with an ETag matches a representation 2541 with that exact ETag. An If-Match option with an empty value matches 2542 any existing representation (i.e., it places the precondition on the 2543 existence of any current representation for the target resource). 2545 The If-Match Option can occur multiple times. If any of the options 2546 match, then the condition is fulfilled. 2548 If there is one or more If-Match Option, but none of the options 2549 match, then the condition is not fulfilled. 2551 5.10.8.2. If-None-Match 2553 The If-None-Match Option MAY be used to make a request conditional on 2554 the non-existence of the target resource. If-None-Match is useful 2555 for resource creation requests, such as PUT requests, as a means for 2556 protecting against accidental overwrites when multiple clients are 2557 acting in parallel on the same resource. The If-None-Match Option 2558 carries no value. 2560 If the target resource does exist, then the condition is not 2561 fulfilled. 2563 6. CoAP URIs 2565 CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP 2566 resources and providing a means of locating the resource. Resources 2567 are organized hierarchically and governed by a potential CoAP origin 2568 server listening for CoAP requests ("coap") or DTLS-secured CoAP 2569 requests ("coaps") on a given UDP port. The CoAP server is 2570 identified via the generic syntax's authority component, which 2571 includes a host component and optional UDP port number. The 2572 remainder of the URI is considered to be identifying a resource which 2573 can be operated on by the methods defined by the CoAP protocol. The 2574 "coap" and "coaps" URI schemes can thus be compared to the "http" and 2575 "https" URI schemes respectively. 2577 The syntax of the "coap" and "coaps" URI schemes is specified in this 2578 section in Augmented Backus-Naur Form (ABNF) [RFC5234]. The 2579 definitions of "host", "port", "path-abempty", "query", "segment", 2580 "IP-literal", "IPv4address" and "reg-name" are adopted from 2581 [RFC3986]. 2583 Implementation Note: Unfortunately, over time the URI format has 2584 acquired significant complexity. Implementers are encouraged to 2585 examine [RFC3986] closely. E.g., the ABNF for IPv6 addresses is 2586 more complicated than maybe expected. Also, implementers should 2587 take care to perform the processing of percent decoding/encoding 2588 exactly once on the way from a URI to its decoded components or 2589 back. Percent encoding is crucial for data transparency, but may 2590 lead to unusual results such as a slash in a path component. 2592 6.1. coap URI Scheme 2594 coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] 2596 If the host component is provided as an IP-literal or IPv4address, 2597 then the CoAP server can be reached at that IP address. If host is a 2598 registered name, then that name is considered an indirect identifier 2599 and the endpoint might use a name resolution service, such as DNS, to 2600 find the address of that host. The host MUST NOT be empty; if a URI 2601 is received with a missing authority or an empty host, then it MUST 2602 be considered invalid. The port subcomponent indicates the UDP port 2603 at which the CoAP server is located. If it is empty or not given, 2604 then the default port 5683 is assumed. 2606 The path identifies a resource within the scope of the host and port. 2608 It consists of a sequence of path segments separated by a slash 2609 character (U+002F SOLIDUS "/"). 2611 The query serves to further parameterize the resource. It consists 2612 of a sequence of arguments separated by an ampersand character 2613 (U+0026 AMPERSAND "&"). An argument is often in the form of a 2614 "key=value" pair. 2616 The "coap" URI scheme supports the path prefix "/.well-known/" 2617 defined by [RFC5785] for "well-known locations" in the name-space of 2618 a host. This enables discovery of policy or other information about 2619 a host ("site-wide metadata"), such as hosted resources (see 2620 Section 7). 2622 Application designers are encouraged to make use of short, but 2623 descriptive URIs. As the environments that CoAP is used in are 2624 usually constrained for bandwidth and energy, the trade-off between 2625 these two qualities should lean towards the shortness, without 2626 ignoring descriptiveness. 2628 6.2. coaps URI Scheme 2630 coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty 2631 [ "?" query ] 2633 All of the requirements listed above for the "coap" scheme are also 2634 requirements for the "coaps" scheme, except that a default UDP port 2635 of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or 2636 not given, and the UDP datagrams MUST be secured for privacy through 2637 the use of DTLS as described in Section 9.1. 2639 Considerations for caching of responses to "coaps" identified 2640 requests are discussed in Section 11.2. 2642 Resources made available via the "coaps" scheme have no shared 2643 identity with the "coap" scheme even if their resource identifiers 2644 indicate the same authority (the same host listening to the same UDP 2645 port). They are distinct name spaces and are considered to be 2646 distinct origin servers. 2648 6.3. Normalization and Comparison Rules 2650 Since the "coap" and "coaps" schemes conform to the URI generic 2651 syntax, such URIs are normalized and compared according to the 2652 algorithm defined in [RFC3986], Section 6, using the defaults 2653 described above for each scheme. 2655 If the port is equal to the default port for a scheme, the normal 2656 form is to elide the port subcomponent. Likewise, an empty path 2657 component is equivalent to an absolute path of "/", so the normal 2658 form is to provide a path of "/" instead. The scheme and host are 2659 case-insensitive and normally provided in lowercase; IP-literals are 2660 in recommended form [RFC5952]; all other components are compared in a 2661 case-sensitive manner. Characters other than those in the "reserved" 2662 set are equivalent to their percent-encoded bytes (see [RFC3986], 2663 Section 2.1): the normal form is to not encode them. 2665 For example, the following three URIs are equivalent, and cause the 2666 same options and option values to appear in the CoAP messages: 2668 coap://example.com:5683/~sensors/temp.xml 2669 coap://EXAMPLE.com/%7Esensors/temp.xml 2670 coap://EXAMPLE.com:/%7esensors/temp.xml 2672 6.4. Decomposing URIs into Options 2674 The steps to parse a request's options from a string /url/ are as 2675 follows. These steps either result in zero or more of the Uri-Host, 2676 Uri-Port, Uri-Path and Uri-Query Options being included in the 2677 request, or they fail. 2679 1. If the /url/ string is not an absolute URI ([RFC3986]), then fail 2680 this algorithm. 2682 2. Resolve the /url/ string using the process of reference 2683 resolution defined by [RFC3986]. At this stage the URL is in 2684 ASCII encoding [RFC0020], even though the decoded components will 2685 be interpreted in UTF-8 [RFC3629] after step 5, 8 and 9. 2687 NOTE: It doesn't matter what it is resolved relative to, since we 2688 already know it is an absolute URL at this point. 2690 3. If /url/ does not have a component whose value, when 2691 converted to ASCII lowercase, is "coap" or "coaps", then fail 2692 this algorithm. 2694 4. If /url/ has a component, then fail this algorithm. 2696 5. If the component of /url/ does not represent the request's 2697 destination IP address as an IP-literal or IPv4address, include a 2698 Uri-Host Option and let that option's value be the value of the 2699 component of /url/, converted to ASCII lowercase, and then 2700 converting all percent-encodings ("%" followed by two hexadecimal 2701 digits) to the corresponding characters. 2703 NOTE: In the usual case where the request's destination IP 2704 address is derived from the host part, this ensures that a Uri- 2705 Host Option is only used for a component of the form reg- 2706 name. 2708 6. If /url/ has a component, then let /port/ be that 2709 component's value interpreted as a decimal integer; otherwise, 2710 let /port/ be the default port for the scheme. 2712 7. If /port/ does not equal the request's destination UDP port, 2713 include a Uri-Port Option and let that option's value be /port/. 2715 8. If the value of the component of /url/ is empty or 2716 consists of a single slash character (U+002F SOLIDUS "/"), then 2717 move to the next step. 2719 Otherwise, for each segment in the component, include a 2720 Uri-Path Option and let that option's value be the segment (not 2721 including the delimiting slash characters) after converting each 2722 percent-encoding ("%" followed by two hexadecimal digits) to the 2723 corresponding byte. 2725 9. If /url/ has a component, then, for each argument in the 2726 component, include a Uri-Query Option and let that 2727 option's value be the argument (not including the question mark 2728 and the delimiting ampersand characters) after converting each 2729 percent-encoding to the corresponding byte. 2731 Note that these rules completely resolve any percent-encoding. 2733 6.5. Composing URIs from Options 2735 The steps to construct a URI from a request's options are as follows. 2736 These steps either result in a URI, or they fail. In these steps, 2737 percent-encoding a character means replacing each of its (UTF-8 2738 encoded) bytes by a "%" character followed by two hexadecimal digits 2739 representing the byte, where the digits A-F are in upper case (as 2740 defined in [RFC3986] Section 2.1; to reduce variability, the 2741 hexadecimal notation for percent-encoding in CoAP URIs MUST use 2742 uppercase letters). The definitions of "unreserved" and "sub-delims" 2743 are adopted from [RFC3986]. 2745 1. If the request is secured using DTLS, let /url/ be the string 2746 "coaps://". Otherwise, let /url/ be the string "coap://". 2748 2. If the request includes a Uri-Host Option, let /host/ be that 2749 option's value, where any non-ASCII characters are replaced by 2750 their corresponding percent-encoding. If /host/ is not a valid 2751 reg-name or IP-literal or IPv4address, fail the algorithm. If 2752 the request does not include a Uri-Host Option, let /host/ be 2753 the IP-literal (making use of the conventions of [RFC5952]) or 2754 IPv4address representing the request's destination IP address. 2756 3. Append /host/ to /url/. 2758 4. If the request includes a Uri-Port Option, let /port/ be that 2759 option's value. Otherwise, let /port/ be the request's 2760 destination UDP port. 2762 5. If /port/ is not the default port for the scheme, then append a 2763 single U+003A COLON character (:) followed by the decimal 2764 representation of /port/ to /url/. 2766 6. Let /resource name/ be the empty string. For each Uri-Path 2767 Option in the request, append a single character U+002F SOLIDUS 2768 (/) followed by the option's value to /resource name/, after 2769 converting any character that is not either in the "unreserved" 2770 set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL 2771 AT (@) character, to its percent-encoded form. 2773 7. If /resource name/ is the empty string, set it to a single 2774 character U+002F SOLIDUS (/). 2776 8. For each Uri-Query Option in the request, append a single 2777 character U+003F QUESTION MARK (?) (first option) or U+0026 2778 AMPERSAND (&) (subsequent options) followed by the option's 2779 value to /resource name/, after converting any character that is 2780 not either in the "unreserved" set, "sub-delims" set (except 2781 U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT 2782 (@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, 2783 to its percent-encoded form. 2785 9. Append /resource name/ to /url/. 2787 10. Return /url/. 2789 Note that these steps have been designed to lead to a URI in normal 2790 form (see Section 6.3). 2792 7. Discovery 2794 7.1. Service Discovery 2796 As a part of discovering the services offered by a CoAP server, a 2797 client has to learn about the endpoint used by a server. 2799 A server is discovered by a client by the client knowing or learning 2800 a URI that references a resource in the namespace of the server. 2801 Alternatively, clients can use Multicast CoAP (see Section 8) and the 2802 "All CoAP Nodes" multicast address to find CoAP servers. 2804 Unless the port subcomponent in a "coap" or "coaps" URI indicates the 2805 UDP port at which the CoAP server is located, the server is assumed 2806 to be reachable at the default port. 2808 The CoAP default port number 5683 MUST be supported by a server that 2809 offers resources for resource discovery (see Section 7.2 below) and 2810 SHOULD be supported for providing access to other resources. The 2811 default port number [IANA_TBD_PORT] for DTLS-secured CoAP MAY be 2812 supported by a server for resource discovery and for providing access 2813 to other resources. In addition other endpoints may be hosted at 2814 other ports, e.g. in the dynamic port space. 2816 Implementation Note: When a CoAP server is hosted by a 6LoWPAN node, 2817 header compression efficiency is improved when it also supports a 2818 port number in the 61616-61631 compressed UDP port space defined 2819 in [RFC4944] (note that, as its UDP port differs from the default 2820 port, it is a different endpoint from the server at the default 2821 port). 2823 7.2. Resource Discovery 2825 The discovery of resources offered by a CoAP endpoint is extremely 2826 important in machine-to-machine applications where there are no 2827 humans in the loop and static interfaces result in fragility. A CoAP 2828 endpoint SHOULD support the CoRE Link Format of discoverable 2829 resources as described in [RFC6690]. It is up to the server which 2830 resources are made discoverable (if any). 2832 7.2.1. 'ct' Attribute 2834 This section defines a new Web Linking [RFC5988] attribute for use 2835 with [RFC6690]. The Content-Format code "ct" attribute provides a 2836 hint about the Content-Formats this resource returns. Note that this 2837 is only a hint, and does not override the Content-Format Option of a 2838 CoAP response obtained by actually requesting the representation of 2839 the resource. The value is in the CoAP identifier code format as a 2840 decimal ASCII integer and MUST be in the range of 0-65535 (16-bit 2841 unsigned integer). For example application/xml would be indicated as 2842 "ct=41". If no Content-Format code attribute is present then nothing 2843 about the type can be assumed. The Content-Format code attribute MAY 2844 include a space-separated sequence of Content-Format codes, 2845 indicating that multiple content-formats are available. The syntax 2846 of the attribute value is summarized in the production ct-value in 2847 Figure 12, where cardinal, SP and DQUOTE are defined as in [RFC6690]. 2849 ct-value = cardinal 2850 / DQUOTE cardinal *( 1*SP cardinal ) DQUOTE 2852 Figure 12 2854 8. Multicast CoAP 2856 CoAP supports making requests to a IP multicast group. This is 2857 defined by a series of deltas to Unicast CoAP. 2859 CoAP endpoints that offer services that they want other endpoints to 2860 be able to find using multicast service discovery, join one or more 2861 of the appropriate all-CoAP-nodes multicast addresses (Section 12.8) 2862 and listen on the default CoAP port. Note that an endpoint might 2863 receive multicast requests on other multicast addresses, including 2864 the all-nodes IPv6 address (or via broadcast on IPv4); an endpoint 2865 MUST therefore be prepared to receive such messages but MAY ignore 2866 them if multicast service discovery is not desired. 2868 8.1. Messaging Layer 2870 A multicast request is characterized by being transported in a CoAP 2871 message that is addressed to an IP multicast address instead of a 2872 CoAP endpoint. Such multicast requests MUST be Non-confirmable. 2874 A server SHOULD be aware that a request arrived via multicast, e.g. 2875 by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 2876 available. 2878 When a server is aware that a request arrived via multicast, it MUST 2879 NOT return a RST in reply to NON. If it is not aware, it MAY return 2880 a RST in reply to NON as usual. Because such a Reset message will 2881 look identical to an RST for a unicast message from the sender, the 2882 sender MUST avoid using a Message ID that is also still active from 2883 this endpoint with any unicast endpoint that might receive the 2884 multicast message. 2886 8.2. Request/Response Layer 2888 When a server is aware that a request arrived via multicast, the 2889 server MAY always pretend it did not receive the request, in 2890 particular if it doesn't have anything useful to respond (e.g., if it 2891 only has an empty payload or an error response). The decision for 2892 this may depend on the application. (For example, in [RFC6690] query 2893 filtering, a server should not respond to a multicast request if the 2894 filter does not match.) 2896 If a server does decide to respond to a multicast request, it should 2897 not respond immediately. Instead, it should pick a duration for the 2898 period of time during which it intends to respond. For purposes of 2899 this exposition, we call the length of this period the Leisure. The 2900 specific value of this Leisure may depend on the application, or MAY 2901 be derived as described below. The server SHOULD then pick a random 2902 point of time within the chosen Leisure period to send back the 2903 unicast response to the multicast request. If further responses need 2904 to be sent based on the same multicast address membership, a new 2905 leisure period starts at the earliest after the previous one 2906 finishes. 2908 To compute a value for Leisure, the server should have a group size 2909 estimate G, a target data transfer rate R (which both should be 2910 chosen conservatively) and an estimated response size S; a rough 2911 lower bound for Leisure can then be computed as 2912 lb_Leisure = S * G / R 2914 E.g., for a multicast request with link-local scope on an 2.4 GHz 2915 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 2916 conservatively) set to 100, S to 100 bytes, and the target rate to 8 2917 kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10 2918 seconds. 2920 If a CoAP endpoint does not have suitable data to compute a value for 2921 Leisure, it MAY resort to DEFAULT_LEISURE. 2923 When matching a response to a multicast request, only the token MUST 2924 match; the source endpoint of the response does not need to (and will 2925 not) be the same as the destination endpoint of the original request. 2927 For the purposes of interpreting the Location-* options and any links 2928 embedded in the representation and, the request URI (base URI) 2929 relative to which the response is interpreted, is formed by replacing 2930 the multicast address in the Host component of the original request 2931 URI by the literal IP address of the endpoint actually responding. 2933 8.2.1. Caching 2935 When a client makes a multicast request, it always makes a new 2936 request to the multicast group (since there may be new group members 2937 that joined meanwhile or ones that did not get the previous request). 2938 It MAY update the cache with the received responses. Then it uses 2939 both cached-still-fresh and 'new' responses as the result of the 2940 request. 2942 A response received in reply to a GET request to a multicast group 2943 MAY be used to satisfy a subsequent request on the related unicast 2944 request URI. The unicast request URI is obtained by replacing the 2945 authority part of the request URI with the transport layer source 2946 address of the response message. 2948 A cache MAY revalidate a response by making a GET request on the 2949 related unicast request URI. 2951 A GET request to a multicast group MUST NOT contain an ETag option. 2952 A mechanism to suppress responses the client already has is left for 2953 further study. 2955 8.2.2. Proxying 2957 When a forward-proxy receives a request with a Proxy-Uri or URI 2958 constructed from Proxy-Scheme that indicates a multicast address, the 2959 proxy obtains a set of responses as described above and sends all 2960 responses (both cached-still-fresh and new) back to the original 2961 client. 2963 This specification does not provide a way to indicate the unicast- 2964 modified request URI (base URI) in responses thus forwarded. A 2965 proposal to address this can be found in section 3 of 2966 [I-D.bormann-coap-misc]. 2968 9. Securing CoAP 2970 This section defines the DTLS binding for CoAP. 2972 During the provisioning phase, a CoAP device is provided with the 2973 security information that it needs, including keying materials and 2974 access control lists. This specification defines provisioning for 2975 the RawPublicKey mode in Section 9.1.3.2.1. At the end of the 2976 provisioning phase, the device will be in one of four security modes 2977 with the following information for the given mode. The NoSec and 2978 RawPublicKey modes are mandatory to implement for this specification. 2980 NoSec: There is no protocol level security (DTLS is disabled). 2981 Alternative techniques to provide lower layer security SHOULD be 2982 used when appropriate. The use of IPsec is discussed in 2983 [I-D.bormann-core-ipsec-for-coap]. 2985 PreSharedKey: DTLS is enabled and there is a list of pre-shared keys 2986 [RFC4279] and each key includes a list of which nodes it can be 2987 used to communicate with as described in Section 9.1.3.1. At the 2988 extreme there may be one key for each node this CoAP node needs to 2989 communicate with (1:1 node/key ratio). 2991 RawPublicKey: DTLS is enabled and the device has an asymmetric key 2992 pair without a certificate (a raw public key) that is validated 2993 using an out-of-band mechanism [I-D.ietf-tls-oob-pubkey] as 2994 described in Section 9.1.3.2. The device also has an identity 2995 calculated from the public key and a list of identities of the 2996 nodes it can communicate with. 2998 Certificate: DTLS is enabled and the device has an asymmetric key 2999 pair with an X.509 certificate [RFC5280] that binds it to its 3000 Authority Name and is signed by some common trust root as 3001 described in Section 9.1.3.3. The device also has a list of root 3002 trust anchors that can be used for validating a certificate. 3004 In the "NoSec" mode, the system simply sends the packets over normal 3005 UDP over IP and is indicated by the "coap" scheme and the CoAP 3006 default port. The system is secured only by keeping attackers from 3007 being able to send or receive packets from the network with the CoAP 3008 nodes; see Section 11.5 for an additional complication with this 3009 approach. 3011 The other three security modes are achieved using DTLS and are 3012 indicated by the "coaps" scheme and DTLS-secured CoAP default port. 3013 The result is a security association that can be used to authenticate 3014 (within the limits of the security model) and, based on this 3015 authentication, authorize the communication partner. CoAP itself 3016 does not provide protocol primitives for authentication or 3017 authorization; where this is required, it can either be provided by 3018 communication security (i.e., IPsec or DTLS) or by object security 3019 (within the payload). Devices that require authorization for certain 3020 operations are expected to require one of these two forms of 3021 security. Necessarily, where an intermediary is involved, 3022 communication security only works when that intermediary is part of 3023 the trust relationships; CoAP does not provide a way to forward 3024 different levels of authorization that clients may have with an 3025 intermediary to further intermediaries or origin servers -- it 3026 therefore may be required to perform all authorization at the first 3027 intermediary. 3029 9.1. DTLS-secured CoAP 3031 Just as HTTP is secured using Transport Layer Security (TLS) over 3032 TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP 3033 (see Figure 13). This section defines the CoAP binding to DTLS, 3034 along with the minimal mandatory-to-implement configurations 3035 appropriate for constrained environments. The binding is defined by 3036 a series of deltas to Unicast CoAP. DTLS is in practice TLS with 3037 added features to deal with the unreliable nature of the UDP 3038 transport. 3040 +----------------------+ 3041 | Application | 3042 +----------------------+ 3043 +----------------------+ 3044 | Requests/Responses | 3045 |----------------------| CoAP 3046 | Messages | 3047 +----------------------+ 3048 +----------------------+ 3049 | DTLS | 3050 +----------------------+ 3051 +----------------------+ 3052 | UDP | 3053 +----------------------+ 3055 Figure 13: Abstract layering of DTLS-secured CoAP 3057 In some constrained nodes (limited flash and/or RAM) and networks 3058 (limited bandwidth or high scalability requirements), and depending 3059 on the specific cipher suites in use, all modes of DTLS may not be 3060 applicable. Some DTLS cipher suites can add significant 3061 implementation complexity as well as some initial handshake overhead 3062 needed when setting up the security association. Once the initial 3063 handshake is completed, DTLS adds a limited per-datagram overhead of 3064 approximately 13 bytes, not including any initialization vectors/ 3065 nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]), 3066 integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 3067 [RFC6655]) and padding required by the cipher suite. Whether and 3068 which mode of using DTLS is applicable for a CoAP-based application 3069 should be carefully weighed considering the specific cipher suites 3070 that may be applicable, and whether the session maintenance makes it 3071 compatible with application flows and sufficient resources are 3072 available on the constrained nodes and for the added network 3073 overhead. (For some modes of using DTLS, this specification 3074 identifies a mandatory to implement cipher suite. This is an 3075 implementation requirement to maximize interoperability in those 3076 cases where these cipher suites are indeed appropriate. The specific 3077 security policies of an application may determine the actual (set of) 3078 cipher suites that can be used.) DTLS is not applicable to group 3079 keying (multicast communication); however, it may be a component in a 3080 future group key management protocol. 3082 9.1.1. Messaging Layer 3084 The endpoint acting as the CoAP client should also act as the DTLS 3085 client. It should initiate a session to the server on the 3086 appropriate port. When the DTLS handshake has finished, the client 3087 may initiate the first CoAP request. All CoAP messages MUST be sent 3088 as DTLS "application data". 3090 The following rules are added for matching an ACK or RST to a CON 3091 message or a RST to a NON message: The DTLS session MUST be the same 3092 and the epoch MUST be the same. 3094 A message is the same when it is sent within the same DTLS session 3095 and same epoch and has the same Message ID. 3097 Note: When a Confirmable message is retransmitted, a new DTLS 3098 sequence_number is used for each attempt, even though the CoAP 3099 Message ID stays the same. So a recipient still has to perform 3100 deduplication as described in Section 4.5. Retransmissions MUST NOT 3101 be performed across epochs. 3103 DTLS connections in RawPublicKey and Certificate mode are set up 3104 using mutual authentication so they can remain up and be reused for 3105 future message exchanges in either direction. Devices can close a 3106 DTLS connection when they need to recover resources but in general 3107 they should keep the connection up for as long as possible. Closing 3108 the DTLS connection after every CoAP message exchange is very 3109 inefficient. 3111 9.1.2. Request/Response Layer 3113 The following rules are added for matching a response to a request: 3114 The DTLS session MUST be the same and the epoch MUST be the same. 3116 9.1.3. Endpoint Identity 3118 Devices SHOULD support the Server Name Indication (SNI) to indicate 3119 their Authority Name in the SNI HostName field as defined in Section 3120 3 of [RFC6066]. This is needed so that when a host that acts as a 3121 virtual server for multiple Authorities receives a new DTLS 3122 connection, it knows which keys to use for the DTLS session. 3124 9.1.3.1. Pre-Shared Keys 3126 When forming a connection to a new node, the system selects an 3127 appropriate key based on which nodes it is trying to reach and then 3128 forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. 3129 Implementations in these modes MUST support the mandatory to 3130 implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in 3131 [RFC6655]. 3133 The security considerations of [RFC4279] (Section 7) apply. In 3134 particular, applications should carefully weigh whether they need 3135 Perfect Forward Secrecy (PFS) or not and select an appropriate cipher 3136 suite (7.1). The entropy of the PSK must be sufficient to mitigate 3137 against brute-force and (where the PSK is not chosen randomly but by 3138 a human) dictionary attacks (7.2). The cleartext communication of 3139 client identities may leak data or compromise privacy (7.3). 3141 9.1.3.2. Raw Public Key Certificates 3143 In this mode the device has an asymmetric key pair but without an 3144 X.509 certificate (called a raw public key). A device MAY be 3145 configured with multiple raw public keys. The type and length of the 3146 raw public key depends on the cipher suite used. Implementations in 3147 RawPublicKey mode MUST support the mandatory to implement cipher 3148 suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in 3149 [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. Some guidance 3150 relevant to the implementation of this cipher suite can be found in 3151 [W3CXMLSEC]. The mechanism for using raw public keys with TLS is 3152 specified in [I-D.ietf-tls-oob-pubkey]. 3154 9.1.3.2.1. Provisioning 3156 The RawPublicKey mode was designed to be easily provisioned in M2M 3157 deployments. It is assumed that each device has an appropriate 3158 asymmetric public key pair installed. An identifier is calculated 3159 from the public key as described in Section 2 of 3160 [I-D.farrell-decade-ni]. All implementations that support checking 3161 RawPublicKey identities MUST support at least the sha-256-120 mode 3162 (SHA-256 truncated to 120 bits). Implementations SHOULD support also 3163 longer length identifiers and MAY support shorter lengths. Note that 3164 the shorter lengths provide less security against attacks and their 3165 use is NOT RECOMMENDED. 3167 Depending on how identifiers are given to the system that verifies 3168 them, support for URI, binary, and/or human-speakable format 3169 [I-D.farrell-decade-ni] needs to be implemented. All implementations 3170 SHOULD support the binary mode and implementations that have a user 3171 interface SHOULD also support the human-speakable format. 3173 During provisioning, the identifier of each node is collected, for 3174 example by reading a barcode on the outside of the device or by 3175 obtaining a pre-compiled list of the identifiers. These identifiers 3176 are then installed in the corresponding endpoint, for example an M2M 3177 data collection server. The identifier is used for two purposes, to 3178 associate the endpoint with further device information and to perform 3179 access control. During provisioning, an access control list of 3180 identifiers the device may start DTLS sessions with SHOULD also be 3181 installed. 3183 9.1.3.3. X.509 Certificates 3185 Implementations in Certificate Mode MUST support the mandatory to 3186 implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as 3187 specified in [RFC5246]. 3189 The Authority Name in the certificate is the name that would be used 3190 in the Host part of a CoAP URI. It is worth noting that this would 3191 typically not be either an IP address or DNS name built in the usual 3192 way but would instead be built out of a long term unique identifier 3193 for the device such as the EUI-64 [EUI64]. The discovery process 3194 used in the system would build up the mapping between IP addresses of 3195 the given devices and the Authority Name for each device. Some 3196 devices could have more than one Authority and would need more than a 3197 single certificate. 3199 When a new connection is formed, the certificate from the remote 3200 device needs to be verified. If the CoAP node has a source of 3201 absolute time, then the node SHOULD check that the validity dates of 3202 the certificate are within range. The certificate MUST also be 3203 signed by an appropriate chain of trust. If the certificate contains 3204 a SubjectAltName, then the Authority Name MUST match at least one of 3205 the authority names of any CoAP URI found in a field of URI type in 3206 the SubjectAltName set. If there is no SubjectAltName in the 3207 certificate, then the Authoritative Name must match the CN found in 3208 the certificate using the matching rules defined in [RFC2818] with 3209 the exception that certificates with wildcards are not allowed. 3211 If the system has a shared key in addition to the certificate, then a 3212 cipher suite that includes the shared key such as 3213 TLS_RSA_PSK_WITH_AES_128_CBC_SHA [RFC4279] SHOULD be used. 3215 10. Cross-Protocol Proxying between CoAP and HTTP 3217 CoAP supports a limited subset of HTTP functionality, and thus cross- 3218 protocol proxying to HTTP is straightforward. There might be several 3219 reasons for proxying between CoAP and HTTP, for example when 3220 designing a web interface for use over either protocol or when 3221 realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied 3222 to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the 3223 definition of these mechanisms is out of scope of this specification. 3225 There are two possible directions to access a resource via a forward- 3226 proxy: 3228 CoAP-HTTP Proxying: Enables CoAP clients to access resources on HTTP 3229 servers through an intermediary. This is initiated by including 3230 the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI 3231 in a CoAP request to a CoAP-HTTP proxy. 3233 HTTP-CoAP Proxying: Enables HTTP clients to access resources on CoAP 3234 servers through an intermediary. This is initiated by specifying 3235 a "coap" or "coaps" URI in the Request-Line of an HTTP request to 3236 an HTTP-CoAP proxy. 3238 Either way, only the Request/Response model of CoAP is mapped to 3239 HTTP. The underlying model of Confirmable or Non-confirmable 3240 messages, etc., is invisible and MUST have no effect on a proxy 3241 function. The following sections describe the handling of requests 3242 to a forward-proxy. Reverse proxies are not specified as the proxy 3243 function is transparent to the client with the proxy acting as if it 3244 was the origin server. However, similar considerations apply to 3245 reverse-proxies as to forward-proxies, and there generally will be an 3246 expectation that reverse-proxies operate in a similar way forward- 3247 proxies would. As an implementation note, HTTP client libraries may 3248 make it hard to operate an HTTP-CoAP forward proxy by not providing a 3249 way to put a CoAP URI on the HTTP Request-Line; reverse-proxying may 3250 therefore lead to wider applicability of a proxy. A separate 3251 specification may define a convention for URIs operating such a HTTP- 3252 CoAP reverse proxy [I-D.castellani-core-http-mapping]. 3254 10.1. CoAP-HTTP Proxying 3256 If a request contains a Proxy-Uri or Proxy-Scheme Option with an 3257 'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint 3258 (called "the proxy" henceforth) is requested to perform the operation 3259 specified by the request method on the indicated HTTP resource and 3260 return the result to the client. 3262 This section specifies for any CoAP request the CoAP response that 3263 the proxy should return to the client. How the proxy actually 3264 satisfies the request is an implementation detail, although the 3265 typical case is expected to be the proxy translating and forwarding 3266 the request to an HTTP origin server. 3268 Since HTTP and CoAP share the basic set of request methods, 3269 performing a CoAP request on an HTTP resource is not so different 3270 from performing it on a CoAP resource. The meanings of the 3271 individual CoAP methods when performed on HTTP resources are 3272 explained in the subsections of this section. 3274 If the proxy is unable or unwilling to service a request with an HTTP 3275 URI, a 5.05 (Proxying Not Supported) response is returned to the 3276 client. If the proxy services the request by interacting with a 3277 third party (such as the HTTP origin server) and is unable to obtain 3278 a result within a reasonable time frame, a 5.04 (Gateway Timeout) 3279 response is returned; if a result can be obtained but is not 3280 understood, a 5.02 (Bad Gateway) response is returned. 3282 10.1.1. GET 3284 The GET method requests the proxy to return a representation of the 3285 HTTP resource identified by the request URI. 3287 Upon success, a 2.05 (Content) response code SHOULD be returned. The 3288 payload of the response MUST be a representation of the target HTTP 3289 resource, and the Content-Format Option be set accordingly. The 3290 response MUST indicate a Max-Age value that is no greater than the 3291 remaining time the representation can be considered fresh. If the 3292 HTTP entity has an entity tag, the proxy SHOULD include an ETag 3293 Option in the response and process ETag Options in requests as 3294 described below. 3296 A client can influence the processing of a GET request by including 3297 the following option: 3299 Accept: The request MAY include an Accept Option, identifying the 3300 preferred response content-format. 3302 ETag: The request MAY include one or more ETag Options, identifying 3303 responses that the client has stored. This requests the proxy to 3304 send a 2.03 (Valid) response whenever it would send a 2.05 3305 (Content) response with an entity tag in the requested set 3306 otherwise. Note that CoAP ETags are always strong ETags in the 3307 HTTP sense; CoAP does not have the equivalent of HTTP weak ETags, 3308 and there is no good way to make use of these in a cross-proxy. 3310 10.1.2. PUT 3312 The PUT method requests the proxy to update or create the HTTP 3313 resource identified by the request URI with the enclosed 3314 representation. 3316 If a new resource is created at the request URI, a 2.01 (Created) 3317 response MUST be returned to the client. If an existing resource is 3318 modified, a 2.04 (Changed) response MUST be returned to indicate 3319 successful completion of the request. 3321 10.1.3. DELETE 3323 The DELETE method requests the proxy to delete the HTTP resource 3324 identified by the request URI at the HTTP origin server. 3326 A 2.02 (Deleted) response MUST be returned to client upon success or 3327 if the resource does not exist at the time of the request. 3329 10.1.4. POST 3331 The POST method requests the proxy to have the representation 3332 enclosed in the request be processed by the HTTP origin server. The 3333 actual function performed by the POST method is determined by the 3334 origin server and dependent on the resource identified by the request 3335 URI. 3337 If the action performed by the POST method does not result in a 3338 resource that can be identified by a URI, a 2.04 (Changed) response 3339 MUST be returned to the client. If a resource has been created on 3340 the origin server, a 2.01 (Created) response MUST be returned. 3342 10.2. HTTP-CoAP Proxying 3344 If an HTTP request contains a Request-URI with a 'coap' or 'coaps' 3345 URI, then the receiving HTTP endpoint (called "the proxy" henceforth) 3346 is requested to perform the operation specified by the request method 3347 on the indicated CoAP resource and return the result to the client. 3349 This section specifies for any HTTP request the HTTP response that 3350 the proxy should return to the client. Unless otherwise specified 3351 all the statements made are RECOMMENDED behavior; some highly 3352 constrained implementations may need to resort to shortcuts. How the 3353 proxy actually satisfies the request is an implementation detail, 3354 although the typical case is expected to be the proxy translating and 3355 forwarding the request to a CoAP origin server. The meanings of the 3356 individual HTTP methods when performed on CoAP resources are 3357 explained in the subsections of this section. 3359 If the proxy is unable or unwilling to service a request with a CoAP 3360 URI, a 501 (Not Implemented) response is returned to the client. If 3361 the proxy services the request by interacting with a third party 3362 (such as the CoAP origin server) and is unable to obtain a result 3363 within a reasonable time frame, a 504 (Gateway Timeout) response is 3364 returned; if a result can be obtained but is not understood, a 502 3365 (Bad Gateway) response is returned. 3367 10.2.1. OPTIONS and TRACE 3369 As the OPTIONS and TRACE methods are not supported in CoAP a 501 (Not 3370 Implemented) error MUST be returned to the client. 3372 10.2.2. GET 3374 The GET method requests the proxy to return a representation of the 3375 CoAP resource identified by the Request-URI. 3377 Upon success, a 200 (OK) response is returned. The payload of the 3378 response MUST be a representation of the target CoAP resource, and 3379 the Content-Type and Content-Encoding header fields be set 3380 accordingly. The response MUST indicate a max-age directive that 3381 indicates a value no greater than the remaining time the 3382 representation can be considered fresh. If the CoAP response has an 3383 ETag option, the proxy should include an ETag header field in the 3384 response. 3386 A client can influence the processing of a GET request by including 3387 the following options: 3389 Accept: The most preferred Media-type of the HTTP Accept header 3390 field in a request is mapped to a CoAP Accept option. HTTP Accept 3391 Media-type ranges, parameters and extensions are not supported by 3392 the CoAP Accept option. If the proxy cannot send a response which 3393 is acceptable according to the combined Accept field value, then 3394 the proxy sends a 406 (not acceptable) response. The proxy MAY 3395 then retry the request with further Media-types from the HTTP 3396 Accept header field. 3398 Conditional GETs: Conditional HTTP GET requests that include an "If- 3399 Match" or "If-None-Match" request-header field can be mapped to a 3400 corresponding CoAP request. The "If-Modified-Since" and "If- 3401 Unmodified-Since" request-header fields are not directly supported 3402 by CoAP, but are implemented locally by a caching proxy. 3404 10.2.3. HEAD 3406 The HEAD method is identical to GET except that the server MUST NOT 3407 return a message-body in the response. 3409 Although there is no direct equivalent of HTTP's HEAD method in CoAP, 3410 an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and 3411 the HTTP headers are returned without a message-body. 3413 Implementation Note: An HTTP-CoAP proxy may want to try using a 3414 block-wise transfer [I-D.ietf-core-block] option to minimize the 3415 amount of data actually transferred, but needs to be prepared for 3416 the case that the origin server does not support block-wise 3417 transfers. 3419 10.2.4. POST 3421 The POST method requests the proxy to have the representation 3422 enclosed in the request be processed by the CoAP origin server. The 3423 actual function performed by the POST method is determined by the 3424 origin server and dependent on the resource identified by the request 3425 URI. 3427 If the action performed by the POST method does not result in a 3428 resource that can be identified by a URI, a 200 (OK) or 204 (No 3429 Content) response MUST be returned to the client. If a resource has 3430 been created on the origin server, a 201 (Created) response MUST be 3431 returned. 3433 If any of the Location-* Options are present in the CoAP response, a 3434 Location header field constructed from the values of these options is 3435 returned. 3437 10.2.5. PUT 3439 The PUT method requests the proxy to update or create the CoAP 3440 resource identified by the Request-URI with the enclosed 3441 representation. 3443 If a new resource is created at the Request-URI, a 201 (Created) 3444 response is returned to the client. If an existing resource is 3445 modified, either the 200 (OK) or 204 (No Content) response codes is 3446 sent to indicate successful completion of the request. 3448 10.2.6. DELETE 3450 The DELETE method requests the proxy to delete the CoAP resource 3451 identified by the Request-URI at the CoAP origin server. 3453 A successful response is 200 (OK) if the response includes an entity 3454 describing the status or 204 (No Content) if the action has been 3455 enacted but the response does not include an entity. 3457 10.2.7. CONNECT 3459 This method can not currently be satisfied by an HTTP-CoAP proxy 3460 function as TLS to DTLS tunneling has not yet been specified. For 3461 now, a 501 (Not Implemented) error is returned to the client. 3463 11. Security Considerations 3465 This section analyzes the possible threats to the protocol. It is 3466 meant to inform protocol and application developers about the 3467 security limitations of CoAP as described in this document. As CoAP 3468 realizes a subset of the features in HTTP/1.1, the security 3469 considerations in Section 15 of [RFC2616] are also pertinent to CoAP. 3470 This section concentrates on describing limitations specific to CoAP. 3472 11.1. Protocol Parsing, Processing URIs 3474 A network-facing application can exhibit vulnerabilities in its 3475 processing logic for incoming packets. Complex parsers are well- 3476 known as a likely source of such vulnerabilities, such as the ability 3477 to remotely crash a node, or even remotely execute arbitrary code on 3478 it. CoAP attempts to narrow the opportunities for introducing such 3479 vulnerabilities by reducing parser complexity, by giving the entire 3480 range of encodable values a meaning where possible, and by 3481 aggressively reducing complexity that is often caused by unnecessary 3482 choice between multiple representations that mean the same thing. 3483 Much of the URI processing has been moved to the clients, further 3484 reducing the opportunities for introducing vulnerabilities into the 3485 servers. Even so, the URI processing code in CoAP implementations is 3486 likely to be a large source of remaining vulnerabilities and should 3487 be implemented with special care. The most complex parser remaining 3488 could be the one for the CoRE Link Format, although this also has 3489 been designed with a goal of reduced implementation complexity 3490 [RFC6690]. (See also section 15.2 of [RFC2616].) 3492 11.2. Proxying and Caching 3494 As mentioned in 15.7 of [RFC2616], proxies are by their very nature 3495 men-in-the-middle, breaking any IPsec or DTLS protection that a 3496 direct CoAP message exchange might have. They are therefore 3497 interesting targets for breaking confidentiality or integrity of CoAP 3498 message exchanges. As noted in [RFC2616], they are also interesting 3499 targets for breaking availability. 3501 The threat to confidentiality and integrity of request/response data 3502 is amplified where proxies also cache. Note that CoAP does not 3503 define any of the cache-suppressing Cache-Control options that 3504 HTTP/1.1 provides to better protect sensitive data. 3506 For a caching implementation, any access control considerations that 3507 would apply to making the request that generated the cache entry also 3508 need to be applied to the value in the cache. This is relevant for 3509 clients that implement multiple security domains, as well as for 3510 proxies that may serve multiple clients. Also, a caching proxy MUST 3511 NOT make cached values available to requests that have lesser 3512 transport security properties than to which it would make available 3513 the process of forwarding the request in the first place. 3515 Unlike the "coap" scheme, responses to "coaps" identified requests 3516 are never "public" and thus MUST NOT be reused for shared caching 3517 unless the cache is able to make equivalent access control decisions 3518 to the ones that led to the cached entry. They can, however, be 3519 reused in a private cache if the message is cacheable by default in 3520 CoAP. 3522 Finally, a proxy that fans out Separate Responses (as opposed to 3523 Piggy-backed Responses) to multiple original requesters may provide 3524 additional amplification (see Section 11.3). 3526 11.3. Risk of amplification 3528 CoAP servers generally reply to a request packet with a response 3529 packet. This response packet may be significantly larger than the 3530 request packet. An attacker might use CoAP nodes to turn a small 3531 attack packet into a larger attack packet, an approach known as 3532 amplification. There is therefore a danger that CoAP nodes could 3533 become implicated in denial of service (DoS) attacks by using the 3534 amplifying properties of the protocol: An attacker that is attempting 3535 to overload a victim but is limited in the amount of traffic it can 3536 generate, can use amplification to generate a larger amount of 3537 traffic. 3539 This is particularly a problem in nodes that enable NoSec access, 3540 that are accessible from an attacker and can access potential victims 3541 (e.g. on the general Internet), as the UDP protocol provides no way 3542 to verify the source address given in the request packet. An 3543 attacker need only place the IP address of the victim in the source 3544 address of a suitable request packet to generate a larger packet 3545 directed at the victim. Such large amplification factors SHOULD NOT 3546 be done in the response if the request is not authenticated. 3548 As a mitigating factor, many constrained networks will only be able 3549 to generate a small amount of traffic, which may make CoAP nodes less 3550 attractive for this attack. However, the limited capacity of the 3551 constrained network makes the network itself a likely victim of an 3552 amplification attack. 3554 A CoAP server can reduce the amount of amplification it provides to 3555 an attacker by using slicing/blocking modes of CoAP 3557 [I-D.ietf-core-block] and offering large resource representations 3558 only in relatively small slices. E.g., for a 1000 byte resource, a 3559 10-byte request might result in an 80-byte response (with a 64-byte 3560 block) instead of a 1016-byte response, considerably reducing the 3561 amplification provided. 3563 CoAP also supports the use of multicast IP addresses in requests, an 3564 important requirement for M2M. Multicast CoAP requests may be the 3565 source of accidental or deliberate denial of service attacks, 3566 especially over constrained networks. This specification attempts to 3567 reduce the amplification effects of multicast requests by limiting 3568 when a response is returned. To limit the possibility of malicious 3569 use, CoAP servers SHOULD NOT accept multicast requests that can not 3570 be authenticated in some way, cryptographically or by some multicast 3571 boundary limiting the potential sources. If possible a CoAP server 3572 SHOULD limit the support for multicast requests to the specific 3573 resources where the feature is required. 3575 On some general purpose operating systems providing a Posix-style 3576 API, it is not straightforward to find out whether a packet received 3577 was addressed to a multicast address. While many implementations 3578 will know whether they have joined a multicast group, this creates a 3579 problem for packets addressed to multicast addresses of the form 3580 FF0x::1, which are received by every IPv6 node. Implementations 3581 SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 3582 available, to make this determination. 3584 11.4. IP Address Spoofing Attacks 3586 Due to the lack of a handshake in UDP, a rogue endpoint which is free 3587 to read and write messages carried by the constrained network (i.e. 3588 NoSec or PreSharedKey deployments with nodes/key ratio > 1:1), may 3589 easily attack a single endpoint, a group of endpoints, as well as the 3590 whole network e.g. by: 3592 1. spoofing RST in response to a CON or NON message, thus making an 3593 endpoint "deaf"; or 3595 2. spoofing the entire response with forged payload/options (this 3596 has different levels of impact: from single response disruption, 3597 to much bolder attacks on the supporting infrastructure, e.g. 3598 poisoning proxy caches, or tricking validation / lookup 3599 interfaces in resource directories and, more generally, any 3600 component that stores global network state and uses CoAP as the 3601 messaging facility to handle state set/update's is a potential 3602 target.); or 3604 3. spoofing a multicast request for a target node which may result 3605 in both network congestion/collapse and victim DoS'ing / forced 3606 wakeup from sleeping; or 3608 4. spoofing observe messages, etc. 3610 Response spoofing by off-path attackers can be detected and mitigated 3611 even without transport layer security by choosing a non-trivial, 3612 randomized token in the request (Section 5.3.1). [RFC4086] discusses 3613 randomness requirements for security. 3615 In principle, other kinds of spoofing can be detected by CoAP only in 3616 case CON semantics is used, because of unexpected ACK/RSTs coming 3617 from the deceived endpoint. But this imposes keeping track of the 3618 used Message IDs which is not always possible, and moreover detection 3619 becomes available usually after the damage is already done. This 3620 kind of attack can be prevented using security modes other than 3621 NoSec. 3623 With or without source address spoofing, a client can attempt to 3624 overload a server by sending requests, preferably complex ones, to a 3625 server; address spoofing makes tracing back, and blocking, this 3626 attack harder. Given that the cost of a CON request is small, this 3627 attack can easily be executed. Under this attack, a constrained node 3628 with limited total energy available may exhaust that energy much more 3629 quickly than planned (battery depletion attack). Also, if the client 3630 uses a Confirmable message and the server responds with a Confirmable 3631 separate response to a (possibly spoofed) address that does not 3632 respond, the server will have to allocate buffer and retransmission 3633 logic for each response up to the exhaustion of MAX_TRANSMIT_SPAN, 3634 making it more likely that it runs out of resources for processing 3635 legitimate traffic. The latter problem can be mitigated somewhat by 3636 limiting the rate of responses as discussed in Section 4.7. An 3637 attacker could also spoof the address of a legitimate client, which, 3638 if the server uses separate responses, might block legitimate 3639 responses to that client because of NSTART=1. All these attacks can 3640 be prevented using a security mode other than NoSec, leaving only 3641 attacks on the security protocol. 3643 11.5. Cross-Protocol Attacks 3645 The ability to incite a CoAP endpoint to send packets to a fake 3646 source address can be used not only for amplification, but also for 3647 cross-protocol attacks against a victim listening to UDP packets at a 3648 given address (IP address and port): 3650 o the attacker sends a message to a CoAP endpoint with the given 3651 address as the fake source address, 3653 o the CoAP endpoint replies with a message to the given source 3654 address, 3656 o the victim at the given address receives a UDP packet that it 3657 interprets according to the rules of a different protocol. 3659 This may be used to circumvent firewall rules that prevent direct 3660 communication from the attacker to the victim, but happen to allow 3661 communication from the CoAP endpoint (which may also host a valid 3662 role in the other protocol) to the victim. 3664 Also, CoAP endpoints may be the victim of a cross-protocol attack 3665 generated through an endpoint of another UDP-based protocol such as 3666 DNS. In both cases, attacks are possible if the security properties 3667 of the endpoints rely on checking IP addresses (and firewalling off 3668 direct attacks sent from outside using fake IP addresses). In 3669 general, because of their lack of context, UDP-based protocols are 3670 relatively easy targets for cross-protocol attacks. 3672 Finally, CoAP URIs transported by other means could be used to incite 3673 clients to send messages to endpoints of other protocols. 3675 One mitigation against cross-protocol attacks is strict checking of 3676 the syntax of packets received, combined with sufficient difference 3677 in syntax. As an example, it might help if it were difficult to 3678 incite a DNS server to send a DNS response that would pass the checks 3679 of a CoAP endpoint. Unfortunately, the first two bytes of a DNS 3680 reply are an ID that can be chosen by the attacker, which map into 3681 the interesting part of the CoAP header, and the next two bytes are 3682 then interpreted as CoAP's Message ID (i.e., any value is 3683 acceptable). The DNS count words may be interpreted as multiple 3684 instances of a (non-existent, but elective) CoAP option 0, or 3685 possibly as a Token. The echoed query finally may be manufactured by 3686 the attacker to achieve a desired effect on the CoAP endpoint; the 3687 response added by the server (if any) might then just be interpreted 3688 as added payload. 3690 1 1 1 1 1 1 3691 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 3692 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3693 | ID | T, TKL, code 3694 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3695 |QR| Opcode |AA|TC|RD|RA| Z | RCODE | Message ID 3696 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3697 | QDCOUNT | (options 0) 3698 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3699 | ANCOUNT | (options 0) 3700 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3701 | NSCOUNT | (options 0) 3702 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3703 | ARCOUNT | (options 0) 3704 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3706 Figure 14: DNS Header vs. CoAP Message 3708 In general, for any pair of protocols, one of the protocols can very 3709 well have been designed in a way that enables an attacker to cause 3710 the generation of replies that look like messages of the other 3711 protocol. It is often much harder to ensure or prove the absence of 3712 viable attacks than to generate examples that may not yet completely 3713 enable an attack but might be further developed by more creative 3714 minds. Cross-protocol attacks can therefore only be completely 3715 mitigated if endpoints don't authorize actions desired by an attacker 3716 just based on trusting the source IP address of a packet. 3717 Conversely, a NoSec environment that completely relies on a firewall 3718 for CoAP security not only needs to firewall off the CoAP endpoints 3719 but also all other endpoints that might be incited to send UDP 3720 messages to CoAP endpoints using some other UDP-based protocol. 3722 In addition to the considerations above, the security considerations 3723 for DTLS with respect to cross-protocol attacks apply. E.g., if the 3724 same DTLS security association ("connection") is used to carry data 3725 of multiple protocols, DTLS no longer provides protection against 3726 cross-protocol attacks between these protocols. 3728 12. IANA Considerations 3730 12.1. CoAP Code Registry 3732 This document defines a registry for the values of the Code field in 3733 the CoAP header. The name of the registry is "CoAP Codes". 3735 All values are assigned by sub-registries according to the following 3736 ranges: 3738 0 Indicates an empty message (see Section 4.1). 3740 1-31 Indicates a request. Values in this range are assigned by 3741 the "CoAP Method Codes" sub-registry (see Section 12.1.1). 3743 32-63 Reserved 3745 64-191 Indicates a response. Values in this range are assigned by 3746 the "CoAP Response Codes" sub-registry (see 3747 Section 12.1.2). 3749 192-255 Reserved 3751 12.1.1. Method Codes 3753 The name of the sub-registry is "CoAP Method Codes". 3755 Each entry in the sub-registry must include the Method Code in the 3756 range 1-31, the name of the method, and a reference to the method's 3757 documentation. 3759 Initial entries in this sub-registry are as follows: 3761 +------+--------+-----------+ 3762 | Code | Name | Reference | 3763 +------+--------+-----------+ 3764 | 1 | GET | [RFCXXXX] | 3765 | 2 | POST | [RFCXXXX] | 3766 | 3 | PUT | [RFCXXXX] | 3767 | 4 | DELETE | [RFCXXXX] | 3768 +------+--------+-----------+ 3770 Table 4: CoAP Method Codes 3772 All other Method Codes are Unassigned. 3774 The IANA policy for future additions to this registry is "IETF Review 3775 or IESG approval" as described in [RFC5226]. 3777 The documentation of a method code should specify the semantics of a 3778 request with that code, including the following properties: 3780 o The response codes the method returns in the success case. 3782 o Whether the method is idempotent, safe, or both. 3784 12.1.2. Response Codes 3786 The name of the sub-registry is "CoAP Response Codes". 3788 Each entry in the sub-registry must include the Response Code in the 3789 range 64-191, a description of the Response Code, and a reference to 3790 the Response Code's documentation. 3792 Initial entries in this sub-registry are as follows: 3794 +------+---------------------------------+-----------+ 3795 | Code | Description | Reference | 3796 +------+---------------------------------+-----------+ 3797 | 65 | 2.01 Created | [RFCXXXX] | 3798 | 66 | 2.02 Deleted | [RFCXXXX] | 3799 | 67 | 2.03 Valid | [RFCXXXX] | 3800 | 68 | 2.04 Changed | [RFCXXXX] | 3801 | 69 | 2.05 Content | [RFCXXXX] | 3802 | 128 | 4.00 Bad Request | [RFCXXXX] | 3803 | 129 | 4.01 Unauthorized | [RFCXXXX] | 3804 | 130 | 4.02 Bad Option | [RFCXXXX] | 3805 | 131 | 4.03 Forbidden | [RFCXXXX] | 3806 | 132 | 4.04 Not Found | [RFCXXXX] | 3807 | 133 | 4.05 Method Not Allowed | [RFCXXXX] | 3808 | 134 | 4.06 Not Acceptable | [RFCXXXX] | 3809 | 140 | 4.12 Precondition Failed | [RFCXXXX] | 3810 | 141 | 4.13 Request Entity Too Large | [RFCXXXX] | 3811 | 143 | 4.15 Unsupported Content-Format | [RFCXXXX] | 3812 | 160 | 5.00 Internal Server Error | [RFCXXXX] | 3813 | 161 | 5.01 Not Implemented | [RFCXXXX] | 3814 | 162 | 5.02 Bad Gateway | [RFCXXXX] | 3815 | 163 | 5.03 Service Unavailable | [RFCXXXX] | 3816 | 164 | 5.04 Gateway Timeout | [RFCXXXX] | 3817 | 165 | 5.05 Proxying Not Supported | [RFCXXXX] | 3818 +------+---------------------------------+-----------+ 3820 Table 5: CoAP Response Codes 3822 The Response Codes 96-127 are Reserved for future use. All other 3823 Response Codes are Unassigned. 3825 The IANA policy for future additions to this registry is "IETF Review 3826 or IESG approval" as described in [RFC5226]. 3828 The documentation of a response code should specify the semantics of 3829 a response with that code, including the following properties: 3831 o The methods the response code applies to. 3833 o Whether payload is required, optional or not allowed. 3835 o The semantics of the payload. For example, the payload of a 2.05 3836 (Content) response is a representation of the target resource; the 3837 payload in an error response is a human-readable diagnostic 3838 payload. 3840 o The format of the payload. For example, the format in a 2.05 3841 (Content) response is indicated by the Content-Format Option; the 3842 format of the payload in an error response is always Net-Unicode 3843 text. 3845 o Whether the response is cacheable according to the freshness 3846 model. 3848 o Whether the response is validatable according to the validation 3849 model. 3851 o Whether the response causes a cache to mark responses stored for 3852 the request URI as not fresh. 3854 12.2. Option Number Registry 3856 This document defines a registry for the Option Numbers used in CoAP 3857 options. The name of the registry is "CoAP Option Numbers". 3859 Each entry in the registry must include the Option Number, the name 3860 of the option and a reference to the option's documentation. 3862 Initial entries in this registry are as follows: 3864 +--------+----------------+-----------+ 3865 | Number | Name | Reference | 3866 +--------+----------------+-----------+ 3867 | 0 | (Reserved) | | 3868 | 1 | If-Match | [RFCXXXX] | 3869 | 3 | Uri-Host | [RFCXXXX] | 3870 | 4 | ETag | [RFCXXXX] | 3871 | 5 | If-None-Match | [RFCXXXX] | 3872 | 7 | Uri-Port | [RFCXXXX] | 3873 | 8 | Location-Path | [RFCXXXX] | 3874 | 11 | Uri-Path | [RFCXXXX] | 3875 | 12 | Content-Format | [RFCXXXX] | 3876 | 14 | Max-Age | [RFCXXXX] | 3877 | 15 | Uri-Query | [RFCXXXX] | 3878 | 16 | Accept | [RFCXXXX] | 3879 | 20 | Location-Query | [RFCXXXX] | 3880 | 35 | Proxy-Uri | [RFCXXXX] | 3881 | 39 | Proxy-Scheme | [RFCXXXX] | 3882 | 128 | (Reserved) | [RFCXXXX] | 3883 | 132 | (Reserved) | [RFCXXXX] | 3884 | 136 | (Reserved) | [RFCXXXX] | 3885 | 140 | (Reserved) | [RFCXXXX] | 3886 +--------+----------------+-----------+ 3888 Table 6: CoAP Option Numbers 3890 The IANA policy for future additions to this registry is split into 3891 three tiers as follows. The range of 0..255 is reserved for options 3892 defined by the IETF (IETF Review or IESG approval). The range of 3893 256..2047 is reserved for commonly used options with public 3894 specifications (Specification Required). The range of 2048..64999 is 3895 for all other options including private or vendor specific ones, 3896 which undergo a Designated Expert review to help ensure that the 3897 option semantics are defined correctly. The option numbers between 3898 65000 and 65535 inclusive are reserved for experiments. They are not 3899 meant for vendor specific use of any kind and MUST NOT be used in 3900 operational deployments. 3902 +---------------+------------------------------+ 3903 | Option Number | Policy [RFC5226] | 3904 +---------------+------------------------------+ 3905 | 0..255 | IETF Review or IESG approval | 3906 | 256..2047 | Specification Required | 3907 | 2048..64999 | Designated Expert | 3908 | 65000..65535 | Reserved for experiments | 3909 +---------------+------------------------------+ 3911 Table 7: CoAP Option Number Registry Policy 3913 The documentation of an Option Number should specify the semantics of 3914 an option with that number, including the following properties: 3916 o The meaning of the option in a request. 3918 o The meaning of the option in a response. 3920 o Whether the option is critical or elective, as determined by the 3921 Option Number. 3923 o Whether the option is Safe, and, if yes, whether it is part of the 3924 Cache-Key, as determined by the Option Number (see Section 5.4.2). 3926 o The format and length of the option's value. 3928 o Whether the option must occur at most once or whether it can occur 3929 multiple times. 3931 o The default value, if any. For a critical option with a default 3932 value, a discussion on how the default value enables processing by 3933 implementations not implementing the critical option 3934 (Section 5.4.4). 3936 12.3. Content-Format Registry 3938 Internet media types are identified by a string, such as 3939 "application/xml" [RFC2046]. In order to minimize the overhead of 3940 using these media types to indicate the format of payloads, this 3941 document defines a registry for a subset of Internet media types to 3942 be used in CoAP and assigns each, in combination with a content- 3943 coding, a numeric identifier. The name of the registry is "CoAP 3944 Content-Formats". 3946 Each entry in the registry must include the media type registered 3947 with IANA, the numeric identifier in the range 0-65535 to be used for 3948 that media type in CoAP, the content-coding associated with this 3949 identifier, and a reference to a document describing what a payload 3950 with that media type means semantically. 3952 CoAP does not include a separate way to convey content-encoding 3953 information with a request or response, and for that reason the 3954 content-encoding is also specified for each identifier (if any). If 3955 multiple content-encodings will be used with a media type, then a 3956 separate Content-Format identifier for each is to be registered. 3957 Similarly, other parameters related to an Internet media type, such 3958 as level, can be defined for a CoAP Content-Format entry. 3960 Initial entries in this registry are as follows: 3962 +--------------------+----------+-----+-----------------------------+ 3963 | Media type | Encoding | Id. | Reference | 3964 +--------------------+----------+-----+-----------------------------+ 3965 | text/plain; | - | 0 | [RFC2046][RFC3676][RFC5147] | 3966 | charset=utf-8 | | | | 3967 | application/ | - | 40 | [RFC6690] | 3968 | link-format | | | | 3969 | application/xml | - | 41 | [RFC3023] | 3970 | application/ | - | 42 | [RFC2045][RFC2046] | 3971 | octet-stream | | | | 3972 | application/exi | - | 47 | [EXIMIME] | 3973 | application/json | - | 50 | [RFC4627] | 3974 +--------------------+----------+-----+-----------------------------+ 3976 Table 8: CoAP Content-Formats 3978 The identifiers between 65000 and 65535 inclusive are reserved for 3979 experiments. They are not meant for vendor specific use of any kind 3980 and MUST NOT be used in operational deployments. The identifiers 3981 between 256 and 9999 are reserved for future use in IETF 3982 specifications (IETF review or IESG approval). All other identifiers 3983 are Unassigned. 3985 Because the name space of single-byte identifiers is so small, the 3986 IANA policy for future additions in the range 0-255 inclusive to the 3987 registry is "Expert Review" as described in [RFC5226]. The IANA 3988 policy for additions in the range 10000-64999 inclusive is "First 3989 Come First Served" as described in [RFC5226]. 3991 In machine to machine applications, it is not expected that generic 3992 Internet media types such as text/plain, application/xml or 3993 application/octet-stream are useful for real applications in the long 3994 term. It is recommended that M2M applications making use of CoAP 3995 will request new Internet media types from IANA indicating semantic 3996 information about how to create or parse a payload. For example, a 3997 Smart Energy application payload carried as XML might request a more 3998 specific type like application/se+xml or application/se-exi. 4000 12.4. URI Scheme Registration 4002 This document requests the registration of the Uniform Resource 4003 Identifier (URI) scheme "coap". The registration request complies 4004 with [RFC4395]. 4006 URI scheme name. 4007 coap 4009 Status. 4010 Permanent. 4012 URI scheme syntax. 4013 Defined in Section 6.1 of [RFCXXXX]. 4015 URI scheme semantics. 4016 The "coap" URI scheme provides a way to identify resources that 4017 are potentially accessible over the Constrained Application 4018 Protocol (CoAP). The resources can be located by contacting the 4019 governing CoAP server and operated on by sending CoAP requests to 4020 the server. This scheme can thus be compared to the "http" URI 4021 scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of 4022 operation. 4024 Encoding considerations. 4025 The scheme encoding conforms to the encoding rules established for 4026 URIs in [RFC3986], i.e. internationalized and reserved characters 4027 are expressed using UTF-8-based percent-encoding. 4029 Applications/protocols that use this URI scheme name. 4030 The scheme is used by CoAP endpoints to access CoAP resources. 4032 Interoperability considerations. 4033 None. 4035 Security considerations. 4036 See Section 11.1 of [RFCXXXX]. 4038 Contact. 4039 IETF Chair 4041 Author/Change controller. 4042 IESG 4044 References. 4045 [RFCXXXX] 4047 12.5. Secure URI Scheme Registration 4049 This document requests the registration of the Uniform Resource 4050 Identifier (URI) scheme "coaps". The registration request complies 4051 with [RFC4395]. 4053 URI scheme name. 4054 coaps 4056 Status. 4057 Permanent. 4059 URI scheme syntax. 4060 Defined in Section 6.2 of [RFCXXXX]. 4062 URI scheme semantics. 4063 The "coaps" URI scheme provides a way to identify resources that 4064 are potentially accessible over the Constrained Application 4065 Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for 4066 transport security. The resources can be located by contacting 4067 the governing CoAP server and operated on by sending CoAP requests 4068 to the server. This scheme can thus be compared to the "https" 4069 URI scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details 4070 of operation. 4072 Encoding considerations. 4073 The scheme encoding conforms to the encoding rules established for 4074 URIs in [RFC3986], i.e. internationalized and reserved characters 4075 are expressed using UTF-8-based percent-encoding. 4077 Applications/protocols that use this URI scheme name. 4078 The scheme is used by CoAP endpoints to access CoAP resources 4079 using DTLS. 4081 Interoperability considerations. 4082 None. 4084 Security considerations. 4085 See Section 11.1 of [RFCXXXX]. 4087 Contact. 4088 IETF Chair 4090 Author/Change controller. 4091 IESG 4093 References. 4094 [RFCXXXX] 4096 12.6. Service Name and Port Number Registration 4098 One of the functions of CoAP is resource discovery: a CoAP client can 4099 ask a CoAP server about the resources offered by it (see Section 7). 4100 To enable resource discovery just based on the knowledge of an IP 4101 address, the CoAP port for resource discovery needs to be 4102 standardized. 4104 IANA has assigned the port number 5683 and the service name "coap", 4105 in accordance with [RFC6335]. 4107 Besides unicast, CoAP can be used with both multicast and anycast. 4109 Service Name. 4110 coap 4112 Transport Protocol. 4113 UDP 4115 Assignee. 4116 IESG 4118 Contact. 4119 IETF Chair 4121 Description. 4122 Constrained Application Protocol (CoAP) 4124 Reference. 4125 [RFCXXXX] 4127 Port Number. 4128 5683 4130 12.7. Secure Service Name and Port Number Registration 4132 CoAP resource discovery may also be provided using the DTLS-secured 4133 CoAP "coaps" scheme. Thus the CoAP port for secure resource 4134 discovery needs to be standardized. 4136 This document requests the assignment of the port number 4137 [IANA_TBD_PORT] and the service name "coaps", in accordance with 4138 [RFC6335]. 4140 Besides unicast, DTLS-secured CoAP can be used with anycast. 4142 Service Name. 4143 coaps 4145 Transport Protocol. 4146 UDP 4148 Assignee. 4149 IESG 4151 Contact. 4152 IETF Chair 4154 Description. 4155 DTLS-secured CoAP 4157 Reference. 4158 [RFCXXXX] 4160 Port Number. 4161 [IANA_TBD_PORT] 4163 12.8. Multicast Address Registration 4165 Section 8, "Multicast CoAP", defines the use of multicast. This 4166 document requests the assignment of the following multicast addresses 4167 for use by CoAP nodes: 4169 IPv4 -- "All CoAP Nodes" address [TBD1], from the IPv4 Multicast 4170 Address Space Registry. As the address is used for discovery that 4171 may span beyond a single network, it should come from the 4172 Internetwork Control Block (224.0.1.x, RFC 5771). 4174 IPv6 -- "All CoAP Nodes" address [TBD2], from the IPv6 Multicast 4175 Address Space Registry, in the Variable Scope Multicast Addresses 4176 space (RFC3307). Note that there is a distinct multicast address 4177 for each scope that interested CoAP nodes should listen to; CoAP 4178 needs the Link-Local and Site-Local scopes only. The address 4179 should be of the form FF0x::nn, where nn is a single byte, to 4180 ensure good compression of the local-scope address with [RFC6282]. 4182 [The explanatory text to be removed upon allocation of the addresses, 4183 except for the note about the distinct multicast addresses.] 4185 13. Acknowledgements 4187 Brian Frank was a contributor to and co-author of previous drafts of 4188 this specification. 4190 Special thanks to Peter Bigot, Esko Dijk and Cullen Jennings for 4191 substantial contributions to the ideas and text in the document, 4192 along with countless detailed reviews and discussions. 4194 Thanks to Ed Beroset, Angelo P. Castellani, Gilbert Clark, Robert 4195 Cragie, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas Fossati, Tom 4196 Herbst, Richard Kelsey, Ari Keranen, Matthias Kovatsch, Salvatore 4197 Loreto, Kerry Lynn, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin 4198 O'Flynn, Charles Palmer, Adriano Pezzuto, Robert Quattlebaum, Akbar 4199 Rahman, Eric Rescorla, Dan Romascanu, David Ryan, Szymon Sasin, 4200 Michael Scharf, Dale Seed, Robby Simpson, Peter van der Stok, Michael 4201 Stuber, Linyi Tian, Gilman Tolle, Matthieu Vial and Alper Yegin for 4202 helpful comments and discussions that have shaped the document. 4204 Some of the text has been borrowed from the working documents of the 4205 IETF httpbis working group. 4207 14. References 4209 14.1. Normative References 4211 [I-D.farrell-decade-ni] 4212 Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 4213 Keraenen, A., and P. Hallam-Baker, "Naming Things with 4214 Hashes", draft-farrell-decade-ni-10 (work in progress), 4215 August 2012. 4217 [I-D.ietf-tls-oob-pubkey] 4218 Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and 4219 T. Kivinen, "Out-of-Band Public Key Validation for 4220 Transport Layer Security (TLS)", 4221 draft-ietf-tls-oob-pubkey-07 (work in progress), 4222 February 2013. 4224 [I-D.mcgrew-tls-aes-ccm-ecc] 4225 McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 4226 CCM ECC Cipher Suites for TLS", 4227 draft-mcgrew-tls-aes-ccm-ecc-06 (work in progress), 4228 February 2013. 4230 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4231 August 1980. 4233 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4234 Extensions (MIME) Part One: Format of Internet Message 4235 Bodies", RFC 2045, November 1996. 4237 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4238 Extensions (MIME) Part Two: Media Types", RFC 2046, 4239 November 1996. 4241 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4242 Requirement Levels", BCP 14, RFC 2119, March 1997. 4244 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 4245 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 4246 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 4248 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 4249 Types", RFC 3023, January 2001. 4251 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 4252 10646", STD 63, RFC 3629, November 2003. 4254 [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", 4255 RFC 3676, February 2004. 4257 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4258 Resource Identifier (URI): Generic Syntax", STD 66, 4259 RFC 3986, January 2005. 4261 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 4262 for Transport Layer Security (TLS)", RFC 4279, 4263 December 2005. 4265 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 4266 Registration Procedures for New URI Schemes", BCP 35, 4267 RFC 4395, February 2006. 4269 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 4270 text/plain Media Type", RFC 5147, April 2008. 4272 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 4273 Interchange", RFC 5198, March 2008. 4275 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4276 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 4277 May 2008. 4279 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 4280 Specifications: ABNF", STD 68, RFC 5234, January 2008. 4282 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4283 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 4285 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4286 Housley, R., and W. Polk, "Internet X.509 Public Key 4287 Infrastructure Certificate and Certificate Revocation List 4288 (CRL) Profile", RFC 5280, May 2008. 4290 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4291 Uniform Resource Identifiers (URIs)", RFC 5785, 4292 April 2010. 4294 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 4295 Address Text Representation", RFC 5952, August 2010. 4297 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 4299 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 4300 Extension Definitions", RFC 6066, January 2011. 4302 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4303 Security Version 1.2", RFC 6347, January 2012. 4305 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 4306 Format", RFC 6690, August 2012. 4308 14.2. Informative References 4310 [EUI64] "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) 4311 REGISTRATION AUTHORITY", April 2010, . 4314 [EXIMIME] "Efficient XML Interchange (EXI) Format 1.0", 4315 December 2009, . 4318 [HHGTTG] Adams, D., "The Hitchhiker's Guide to the Galaxy", 4319 October 1979. 4321 [I-D.allman-tcpm-rto-consider] 4322 Allman, M., "Retransmission Timeout Considerations", 4323 draft-allman-tcpm-rto-consider-01 (work in progress), 4324 May 2012. 4326 [I-D.bormann-coap-misc] 4327 Bormann, C. and K. Hartke, "Miscellaneous additions to 4328 CoAP", draft-bormann-coap-misc-24 (work in progress), 4329 March 2013. 4331 [I-D.bormann-core-ipsec-for-coap] 4332 Bormann, C., "Using CoAP with IPsec", 4333 draft-bormann-core-ipsec-for-coap-00 (work in progress), 4334 December 2012. 4336 [I-D.castellani-core-http-mapping] 4337 Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 4338 E. Dijk, "Best Practices for HTTP-CoAP Mapping 4339 Implementation", draft-castellani-core-http-mapping-07 4340 (work in progress), February 2013. 4342 [I-D.ietf-core-block] 4343 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 4344 draft-ietf-core-block-11 (work in progress), March 2013. 4346 [I-D.ietf-core-observe] 4347 Hartke, K., "Observing Resources in CoAP", 4348 draft-ietf-core-observe-08 (work in progress), 4349 February 2013. 4351 [I-D.ietf-lwig-terminology] 4352 Bormann, C., Ersue, M., and A. Keraenen, "Terminology for 4353 Constrained Node Networks", draft-ietf-lwig-terminology-03 4354 (work in progress), March 2013. 4356 [REST] Fielding, R., "Architectural Styles and the Design of 4357 Network-based Software Architectures", Ph.D. Dissertation, 4358 University of California, Irvine, 2000, . 4362 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 4363 October 1969. 4365 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 4366 RFC 793, September 1981. 4368 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 4370 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 4371 with Session Description Protocol (SDP)", RFC 3264, 4372 June 2002. 4374 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4375 "Advanced Sockets Application Program Interface (API) for 4376 IPv6", RFC 3542, May 2003. 4378 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 4379 Requirements for Security", BCP 106, RFC 4086, June 2005. 4381 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 4382 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 4383 for Transport Layer Security (TLS)", RFC 4492, May 2006. 4385 [RFC4627] Crockford, D., "The application/json Media Type for 4386 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 4388 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 4389 "Transmission of IPv6 Packets over IEEE 802.15.4 4390 Networks", RFC 4944, September 2007. 4392 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 4393 for Application Designers", BCP 145, RFC 5405, 4394 November 2008. 4396 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 4397 Protocol (XMPP): Core", RFC 6120, March 2011. 4399 [RFC6282] Hui, J. and P. Thubert, "Compression Format for IPv6 4400 Datagrams over IEEE 802.15.4-Based Networks", RFC 6282, 4401 September 2011. 4403 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 4404 Cheshire, "Internet Assigned Numbers Authority (IANA) 4405 Procedures for the Management of the Service Name and 4406 Transport Protocol Port Number Registry", BCP 165, 4407 RFC 6335, August 2011. 4409 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 4410 Transport Layer Security (TLS)", RFC 6655, July 2012. 4412 [W3CXMLSEC] 4413 Wenning, R., "Report of the XML Security PAG", 4414 October 2012, 4415 . 4417 Appendix A. Examples 4419 This section gives a number of short examples with message flows for 4420 GET requests. These examples demonstrate the basic operation, the 4421 operation in the presence of retransmissions, and multicast. 4423 Figure 15 shows a basic GET request causing a piggy-backed response: 4424 The client sends a Confirmable GET request for the resource 4425 coap://server/temperature to the server with a Message ID of 0x7d34. 4426 The request includes one Uri-Path Option (Delta 0 + 11 = 11, Length 4427 11, Value "temperature"); the Token is left empty. This request is a 4428 total of 16 bytes long. A 2.05 (Content) response is returned in the 4429 Acknowledgement message that acknowledges the Confirmable request, 4430 echoing both the Message ID 0x7d34 and the empty Token value. The 4431 response includes a Payload of "22.3 C" and is 11 bytes long. 4433 Client Server 4434 | | 4435 | | 4436 +----->| Header: GET (T=CON, Code=1, MID=0x7d34) 4437 | GET | Uri-Path: "temperature" 4438 | | 4439 | | 4440 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d34) 4441 | 2.05 | Payload: "22.3 C" 4442 | | 4444 0 1 2 3 4445 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 4446 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4447 | 1 | 0 | 0 | GET=1 | MID=0x7d34 | 4448 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4449 | 11 | 11 | "temperature" (11 B) ... 4450 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4452 0 1 2 3 4453 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 4454 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4455 | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | 4456 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4457 |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... 4458 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4460 Figure 15: Confirmable request; piggy-backed response 4462 Figure 16 shows a similar example, but with the inclusion of an non- 4463 empty Token (Value 0x20) in the request and the response, increasing 4464 the sizes to 17 and 12 bytes, respectively. 4466 Client Server 4467 | | 4468 | | 4469 +----->| Header: GET (T=CON, Code=1, MID=0x7d35) 4470 | GET | Token: 0x20 4471 | | Uri-Path: "temperature" 4472 | | 4473 | | 4474 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d35) 4475 | 2.05 | Token: 0x20 4476 | | Payload: "22.3 C" 4477 | | 4479 0 1 2 3 4480 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 4481 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4482 | 1 | 0 | 1 | GET=1 | MID=0x7d35 | 4483 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4484 | 0x20 | 4485 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4486 | 11 | 11 | "temperature" (11 B) ... 4487 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4489 0 1 2 3 4490 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 4491 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4492 | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | 4493 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4494 | 0x20 | 4495 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4496 |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... 4497 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4499 Figure 16: Confirmable request; piggy-backed response 4501 In Figure 17, the Confirmable GET request is lost. After ACK_TIMEOUT 4502 seconds, the client retransmits the request, resulting in a piggy- 4503 backed response as in the previous example. 4505 Client Server 4506 | | 4507 | | 4508 +----X | Header: GET (T=CON, Code=1, MID=0x7d36) 4509 | GET | Token: 0x31 4510 | | Uri-Path: "temperature" 4511 TIMEOUT | 4512 | | 4513 +----->| Header: GET (T=CON, Code=1, MID=0x7d36) 4514 | GET | Token: 0x31 4515 | | Uri-Path: "temperature" 4516 | | 4517 | | 4518 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d36) 4519 | 2.05 | Token: 0x31 4520 | | Payload: "22.3 C" 4521 | | 4523 Figure 17: Confirmable request (retransmitted); piggy-backed response 4525 In Figure 18, the first Acknowledgement message from the server to 4526 the client is lost. After ACK_TIMEOUT seconds, the client 4527 retransmits the request. 4529 Client Server 4530 | | 4531 | | 4532 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 4533 | GET | Token: 0x42 4534 | | Uri-Path: "temperature" 4535 | | 4536 | | 4537 | X----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 4538 | 2.05 | Token: 0x42 4539 | | Payload: "22.3 C" 4540 TIMEOUT | 4541 | | 4542 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 4543 | GET | Token: 0x42 4544 | | Uri-Path: "temperature" 4545 | | 4546 | | 4547 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 4548 | 2.05 | Token: 0x42 4549 | | Payload: "22.3 C" 4550 | | 4552 Figure 18: Confirmable request; piggy-backed response (retransmitted) 4553 In Figure 19, the server acknowledges the Confirmable request and 4554 sends a 2.05 (Content) response separately in a Confirmable message. 4555 Note that the Acknowledgement message and the Confirmable response do 4556 not necessarily arrive in the same order as they were sent. The 4557 client acknowledges the Confirmable response. 4559 Client Server 4560 | | 4561 | | 4562 +----->| Header: GET (T=CON, Code=1, MID=0x7d38) 4563 | GET | Token: 0x53 4564 | | Uri-Path: "temperature" 4565 | | 4566 | | 4567 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d38) 4568 | | 4569 | | 4570 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7b) 4571 | 2.05 | Token: 0x53 4572 | | Payload: "22.3 C" 4573 | | 4574 | | 4575 +- - ->| Header: (T=ACK, Code=0, MID=0xad7b) 4576 | | 4578 Figure 19: Confirmable request; separate response 4580 Figure 20 shows an example where the client loses its state (e.g., 4581 crashes and is rebooted) right after sending a Confirmable request, 4582 so the separate response arriving some time later comes unexpected. 4583 In this case, the client rejects the Confirmable response with a 4584 Reset message. Note that the unexpected ACK is silently ignored. 4586 Client Server 4587 | | 4588 | | 4589 +----->| Header: GET (T=CON, Code=1, MID=0x7d39) 4590 | GET | Token: 0x64 4591 | | Uri-Path: "temperature" 4592 CRASH | 4593 | | 4594 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d39) 4595 | | 4596 | | 4597 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7c) 4598 | 2.05 | Token: 0x64 4599 | | Payload: "22.3 C" 4600 | | 4601 | | 4602 +- - ->| Header: (T=RST, Code=0, MID=0xad7c) 4603 | | 4605 Figure 20: Confirmable request; separate response (unexpected) 4607 Figure 21 shows a basic GET request where the request and the 4608 response are Non-confirmable, so both may be lost without notice. 4610 Client Server 4611 | | 4612 | | 4613 +----->| Header: GET (T=NON, Code=1, MID=0x7d40) 4614 | GET | Token: 0x75 4615 | | Uri-Path: "temperature" 4616 | | 4617 | | 4618 |<-----+ Header: 2.05 Content (T=NON, Code=69, MID=0xad7d) 4619 | 2.05 | Token: 0x75 4620 | | Payload: "22.3 C" 4621 | | 4623 Figure 21: Non-confirmable request; Non-confirmable response 4625 In Figure 22, the client sends a Non-confirmable GET request to a 4626 multicast address: all nodes in link-local scope. There are 3 4627 servers on the link: A, B and C. Servers A and B have a matching 4628 resource, therefore they send back a Non-confirmable 2.05 (Content) 4629 response. The response sent by B is lost. C does not have matching 4630 response, therefore it sends a Non-confirmable 4.04 (Not Found) 4631 response. 4633 Client ff02::1 A B C 4634 | | | | | 4635 | | | | | 4636 +------>| | | | Header: GET (T=NON, Code=1, MID=0x7d41) 4637 | GET | | | | Token: 0x86 4638 | | | | Uri-Path: "temperature" 4639 | | | | 4640 | | | | 4641 |<------------+ | | Header: 2.05 (T=NON, Code=69, MID=0x60b1) 4642 | 2.05 | | | Token: 0x86 4643 | | | | Payload: "22.3 C" 4644 | | | | 4645 | | | | 4646 | X------------+ | Header: 2.05 (T=NON, Code=69, MID=0x01a0) 4647 | 2.05 | | | Token: 0x86 4648 | | | | Payload: "20.9 C" 4649 | | | | 4650 | | | | 4651 |<------------------+ Header: 4.04 (T=NON, Code=132, MID=0x952a) 4652 | 4.04 | | | Token: 0x86 4653 | | | | 4655 Figure 22: Non-confirmable request (multicast); Non-confirmable 4656 response 4658 Appendix B. URI Examples 4660 The following examples demonstrate different sets of Uri options, and 4661 the result after constructing an URI from them. In addition to the 4662 options, Section 6.5 refers to the destination IP address and port, 4663 but not all paths of the algorithm cause the destination IP address 4664 and port to be included in the URI. 4666 o Input: 4668 Destination IP Address = [2001:db8::2:1] 4669 Destination UDP Port = 5683 4671 Output: 4673 coap://[2001:db8::2:1]/ 4675 o Input: 4677 Destination IP Address = [2001:db8::2:1] 4678 Destination UDP Port = 5683 4679 Uri-Host = "example.net" 4681 Output: 4683 coap://example.net/ 4685 o Input: 4687 Destination IP Address = [2001:db8::2:1] 4688 Destination UDP Port = 5683 4689 Uri-Host = "example.net" 4690 Uri-Path = ".well-known" 4691 Uri-Path = "core" 4693 Output: 4695 coap://example.net/.well-known/core 4697 o Input: 4699 Destination IP Address = [2001:db8::2:1] 4700 Destination UDP Port = 5683 4701 Uri-Host = "xn--18j4d.example" 4702 Uri-Path = the string composed of the Unicode characters U+3053 4703 U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as 4704 E38193E38293E381ABE381A1E381AF hexadecimal 4706 Output: 4708 coap:// 4709 xn--18j4d.example/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF 4711 (The line break has been inserted for readability; it is not 4712 part of the URI.) 4714 o Input: 4716 Destination IP Address = 198.51.100.1 4717 Destination UDP Port = 61616 4718 Uri-Path = "" 4719 Uri-Path = "/" 4720 Uri-Path = "" 4721 Uri-Path = "" 4722 Uri-Query = "//" 4723 Uri-Query = "?&" 4725 Output: 4727 coap://198.51.100.1:61616//%2F//?%2F%2F&?%26 4729 Appendix C. Changelog 4731 (To be removed by RFC editor before publication.) 4733 Changes from ietf-14 to ietf-15: Address comments from IETF last- 4734 call, mostly implementation notes and editorial improvements. These 4735 should not impact interoperability. 4737 o Clarify bytes/characters and UTF-8/ASCII in "Decomposing URIs into 4738 Options" (#282). 4740 o Make reference to ECC/CCM DTLS ciphersuite normative (#286). 4742 o Add a quick warning that bytewise scanning for a payload marker is 4743 not a good idea (#287). 4745 o Make reference to PROBING_RATE explicit for saturation discussion 4746 (#288). 4748 o Mention PROCESSING_DELAY when discussion piggy-backing (#290). 4750 o Various editorial nits: Clarify use of noun "service" (#283), 4751 Reference terminology from lwig-terminology (#284), make reference 4752 to HTTP terms more explicit (#285), add a forward reference to 4753 5.9.2.9 (#289), 8 kbit/s is not "conservative" (#291). 4755 o Add description of resource depletion attack (#292). 4757 o Add description of DoS attack on congestion control (#293). 4759 o Add discussion of using non-trivial token for protecting against 4760 hijacking (#294). 4762 o Clarify implementation note about per-destination Message ID 4763 generation. 4765 Changed from ietf-13 to ietf-14: 4767 o Made Accept option non-repeatable. 4769 o Clarified that Safe options in a 2.03 Valid response update the 4770 cache. 4772 o Clarified that payload sniffing is acceptable only if no Content- 4773 Format was supplied. 4775 o Clarified URI examples (Appendix B). 4777 o Numerous editorial improvements and clarifications. 4779 Changed from ietf-12 to ietf-13: 4781 o Simplified message format. 4783 * Removed the OC (Option Count) field in the CoAP Header. 4785 * Changed the End-of-Options Marker into the Payload Marker. 4787 * Changed the format of Options: use 4 bits for option length and 4788 delta; insert one or two additional bytes after the option 4789 header if necessary. 4791 * Promoted the Token Option to a field following the CoAP Header. 4793 o Clarified when a payload is a diagnostic payload (#264). 4795 o Moved IPsec discussion to separate draft (#262). 4797 o Added a reference to a separate draft on reverse-proxy URI 4798 embedding (#259). 4800 o Clarified the use of ETags and of 2.03 responses (#265, #254, 4801 #256). 4803 o Added reserved Location-* numbers and clarified Location-*. 4805 o Added Proxy-Scheme proposal. 4807 o Clarified terms such as content negotiation, selected 4808 representation, representation-format, message format error. 4810 o Numerous clarifications and a few bugfixes. 4812 Changed from ietf-11 to ietf-12: 4814 o Extended options to support lengths of up to 1034 bytes (#202). 4816 o Added new Jump mechanism for options and removed Fenceposting 4817 (#214). 4819 o Added new IANA option number registration policy (#214). 4821 o Added Proxy Unsafe/Safe and Cache-Key masking to option numbers 4822 (#241). 4824 o Re-numbered option numbers to use Unsafe/Safe and Cache-Key 4825 compliant numbers (#241). 4827 o Defined NSTART and restricted the value to 1 with a MUST (#215). 4829 o Defined PROBING_RATE and set it to 1 Byte/second (#215). 4831 o Defined DEFAULT_LEISURE (#246). 4833 o Renamed Content-Type into Content-Format, and Media Type registry 4834 into Content-Format registry. 4836 o A large number of small editorial changes, clarifications and 4837 improvements have been made. 4839 Changed from ietf-10 to ietf-11: 4841 o Expanded section 4.8 on Transmission Parameters, and used the 4842 derived values defined there (#201). Changed parameter names to 4843 be shorter and more to the point. 4845 o Several more small editorial changes, clarifications and 4846 improvements have been made. 4848 Changed from ietf-09 to ietf-10: 4850 o Option deltas are restricted to 0 to 14; the option delta 15 is 4851 used exclusively for the end-of-options marker (#239). 4853 o Option numbers that are a multiple of 14 are not reserved, but are 4854 required to have an empty default value (#212). 4856 o Fixed misleading language that was introduced in 5.10.2 in coap-07 4857 re Uri-Host and Uri-Port (#208). 4859 o Segments and arguments can have a length of zero characters 4860 (#213). 4862 o The Location-* options describe together describe one location. 4863 The location is a relative URI, not an "absolute path URI" (#218). 4865 o The value of the Location-Path Option must not be '.' or '..' 4866 (#218). 4868 o Added a sentence on constructing URIs from Location-* options 4869 (#231). 4871 o Reserved option numbers for future Location-* options (#230). 4873 o Fixed response codes with payload inconsistency (#233). 4875 o Added advice on default values for critical options (#207). 4877 o Clarified use of identifiers in RawPublicKey Mode Provisioning 4878 (#222). 4880 o Moved "Securing CoAP" out of the "Security Considerations" (#229). 4882 o Added "All CoAP Nodes" multicast addresses to "IANA 4883 Considerations" (#216). 4885 o Over 100 small editorial changes, clarifications and improvements 4886 have been made. 4888 Changed from ietf-08 to ietf-09: 4890 o Improved consistency of statements about RST on NON: RST is a 4891 valid response to a NON message (#183). 4893 o Clarified that the protocol constants can be configured for 4894 specific application environments. 4896 o Added implementation note recommending piggy-backing whenever 4897 possible (#182). 4899 o Added a content-encoding column to the media type registry (#181). 4901 o Minor improvements to Appendix D. 4903 o Added text about multicast response suppression (#177). 4905 o Included the new End-of-options Marker (#176). 4907 o Added a reference to draft-ietf-tls-oob-pubkey and updated the RPK 4908 text accordingly. 4910 Changed from ietf-07 to ietf-08: 4912 o Clarified matching rules for messages (#175) 4914 o Fixed a bug in Section 8.2.2 on Etags (#168) 4916 o Added an IP address spoofing threat analysis contribution (#167) 4917 o Re-focused the security section on raw public keys (#166) 4919 o Added an 4.06 error to Accept (#165) 4921 Changed from ietf-06 to ietf-07: 4923 o application/link-format added to Media types registration (#160) 4925 o Moved content-type attribute to the document from link-format. 4927 o Added coaps scheme and DTLS-secured CoAP default port (#154) 4929 o Allowed 0-length Content-type options (#150) 4931 o Added congestion control recommendations (#153) 4933 o Improved text on PUT/POST response payloads (#149) 4935 o Added an Accept option for content-negotiation (#163) 4937 o Added If-Match and If-None-Match options (#155) 4939 o Improved Token Option explanation (#147) 4941 o Clarified mandatory to implement security (#156) 4943 o Added first come first server policy for 2-byte Media type codes 4944 (#161) 4946 o Clarify matching rules for messages and tokens (#151) 4948 o Changed OPTIONS and TRACE to always return 501 in HTTP-CoAP 4949 mapping (#164) 4951 Changed from ietf-05 to ietf-06: 4953 o HTTP mapping section improved with the minimal protocol standard 4954 text for CoAP-HTTP and HTTP-CoAP forward proxying (#137). 4956 o Eradicated percent-encoding by including one Uri-Query Option per 4957 &-delimited argument in a query. 4959 o Allowed RST message in reply to a NON message with unexpected 4960 token (#135). 4962 o Cache Invalidation only happens upon successful responses (#134). 4964 o 50% jitter added to the initial retransmit timer (#142). 4966 o DTLS cipher suites aligned with ZigBee IP, DTLS clarified as 4967 default CoAP security mechanism (#138, #139) 4969 o Added a minimal reference to draft-kivinen-ipsecme-ikev2-minimal 4970 (#140). 4972 o Clarified the comparison of UTF-8s (#136). 4974 o Minimized the initial media type registry (#101). 4976 Changed from ietf-04 to ietf-05: 4978 o Renamed Immediate into Piggy-backed and Deferred into Separate -- 4979 should finally end the confusion on what this is about. 4981 o GET requests now return a 2.05 (Content) response instead of 2.00 4982 (OK) response (#104). 4984 o Added text to allow 2.02 (Deleted) responses in reply to POST 4985 requests (#105). 4987 o Improved message deduplication rules (#106). 4989 o Section added on message size implementation considerations 4990 (#103). 4992 o Clarification made on human readable error payloads (#109). 4994 o Definition of CoAP methods improved (#108). 4996 o Max-Age removed from requests (#107). 4998 o Clarified uniqueness of tokens (#112). 5000 o Location-Query Option added (#113). 5002 o ETag length set to 1-8 bytes (#123). 5004 o Clarified relation between elective/critical and option numbers 5005 (#110). 5007 o Defined when to update Version header field (#111). 5009 o URI scheme registration improved (#102). 5011 o Added review guidelines for new CoAP codes and numbers. 5013 Changes from ietf-03 to ietf-04: 5015 o Major document reorganization (#51, #63, #71, #81). 5017 o Max-age length set to 0-4 bytes (#30). 5019 o Added variable unsigned integer definition (#31). 5021 o Clarification made on human readable error payloads (#50). 5023 o Definition of POST improved (#52). 5025 o Token length changed to 0-8 bytes (#53). 5027 o Section added on multiplexing CoAP, DTLS and STUN (#56). 5029 o Added cross-protocol attack considerations (#61). 5031 o Used new Immediate/Deferred response definitions (#73). 5033 o Improved request/response matching rules (#74). 5035 o Removed unnecessary media types and added recommendations for 5036 their use in M2M (#76). 5038 o Response codes changed to base 32 coding, new Y.XX naming (#77). 5040 o References updated as per AD review (#79). 5042 o IANA section completed (#80). 5044 o Proxy-Uri Option added to disambiguate between proxy and non-proxy 5045 requests (#82). 5047 o Added text on critical options in cached states (#83). 5049 o HTTP mapping sections improved (#88). 5051 o Added text on reverse proxies (#72). 5053 o Some security text on multicast added (#54). 5055 o Trust model text added to introduction (#58, #60). 5057 o AES-CCM vs. AES-CCB text added (#55). 5059 o Text added about device capabilities (#59). 5061 o DTLS section improvements (#87). 5063 o Caching semantics aligned with RFC2616 (#78). 5065 o Uri-Path Option split into multiple path segments. 5067 o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. 5069 Changes from ietf-02 to ietf-03: 5071 o Token Option and related use in asynchronous requests added (#25). 5073 o CoAP specific error codes added (#26). 5075 o Erroring out on unknown critical options changed to a MUST (#27). 5077 o Uri-Query Option added. 5079 o Terminology and definitions of URIs improved. 5081 o Security section completed (#22). 5083 Changes from ietf-01 to ietf-02: 5085 o Sending an error on a critical option clarified (#18). 5087 o Clarification on behavior of PUT and idempotent operations (#19). 5089 o Use of Uri-Authority clarified along with server processing rules; 5090 Uri-Scheme Option removed (#20, #23). 5092 o Resource discovery section removed to a separate CoRE Link Format 5093 draft (#21). 5095 o Initial security section outline added. 5097 Changes from ietf-00 to ietf-01: 5099 o New cleaner transaction message model and header (#5). 5101 o Removed subscription while being designed (#1). 5103 o Section 2 re-written (#3). 5105 o Text added about use of short URIs (#4). 5107 o Improved header option scheme (#5, #14). 5109 o Date option removed whiled being designed (#6). 5111 o New text for CoAP default port (#7). 5113 o Completed proxying section (#8). 5115 o Completed resource discovery section (#9). 5117 o Completed HTTP mapping section (#10). 5119 o Several new examples added (#11). 5121 o URI split into 3 options (#12). 5123 o MIME type defined for link-format (#13, #16). 5125 o New text on maximum message size (#15). 5127 o Location Option added. 5129 Changes from shelby-01 to ietf-00: 5131 o Removed the TCP binding section, left open for the future. 5133 o Fixed a bug in the example. 5135 o Marked current Sub/Notify as (Experimental) while under WG 5136 discussion. 5138 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 5139 CoAP-CoAP proxying to work). 5141 o Temporarily removed the Magic Byte header as TCP is no longer 5142 included as a binding. 5144 o Removed the Uri-code Option as different URI encoding schemes are 5145 being discussed. 5147 o Changed the rel= field to desc= for resource discovery. 5149 o Changed the maximum message size to 1024 bytes to allow for IP/UDP 5150 headers. 5152 o Made the URI slash optimization and method idempotence MUSTs 5153 o Minor editing and bug fixing. 5155 Changes from shelby-00 to shelby-01: 5157 o Unified the message header and added a notify message type. 5159 o Renamed methods with HTTP names and removed the NOTIFY method. 5161 o Added a number of options field to the header. 5163 o Combines the Option Type and Length into an 8-bit field. 5165 o Added the magic byte header. 5167 o Added new ETag Option. 5169 o Added new Date Option. 5171 o Added new Subscription Option. 5173 o Completed the HTTP Code - CoAP Code mapping table appendix. 5175 o Completed the Content-type Identifier appendix and tables. 5177 o Added more simplifications for URI support. 5179 o Initial subscription and discovery sections. 5181 o A Flag requirements simplified. 5183 Authors' Addresses 5185 Zach Shelby 5186 Sensinode 5187 Kidekuja 2 5188 Vuokatti 88600 5189 Finland 5191 Phone: +358407796297 5192 Email: zach@sensinode.com 5193 Klaus Hartke 5194 Universitaet Bremen TZI 5195 Postfach 330440 5196 Bremen D-28359 5197 Germany 5199 Phone: +49-421-218-63905 5200 Email: hartke@tzi.org 5202 Carsten Bormann 5203 Universitaet Bremen TZI 5204 Postfach 330440 5205 Bremen D-28359 5206 Germany 5208 Phone: +49-421-218-63921 5209 Email: cabo@tzi.org