idnits 2.17.1 draft-ietf-core-coap-18.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 4927 has weird spacing: '... Client ff02:...' -- The document date (June 28, 2013) is 3954 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 506, but not defined == Missing Reference: '0x01a0' is mentioned on line 521, but not defined == Missing Reference: '0xbc90' is mentioned on line 567, but not defined == Missing Reference: '0xbc91' is mentioned on line 567, but not defined == Missing Reference: '0x7a10' is mentioned on line 591, but not defined == Missing Reference: '0x23bb' is mentioned on line 602, but not defined == Missing Reference: '0x7a11' is mentioned on line 615, but not defined == Missing Reference: '0x23bc' is mentioned on line 620, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 4411, but not defined == Missing Reference: 'TBD1' is mentioned on line 4422, but not defined == Missing Reference: 'TBD2' is mentioned on line 4427, 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-22 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-10 == Outdated reference: A later version (-25) exists of draft-ietf-core-groupcomm-06 == 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-04 -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 2560 (Obsoleted by RFC 6960) -- 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 (~~), 22 warnings (==), 8 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: December 30, 2013 C. Bormann 6 Universitaet Bremen TZI 7 June 28, 2013 9 Constrained Application Protocol (CoAP) 10 draft-ietf-core-coap-18 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 is designed to easily interface with HTTP 27 for integration with the Web while meeting specialized requirements 28 such 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 December 30, 2013. 48 Copyright Notice 50 Copyright (c) 2013 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 66 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 5 67 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 68 2. Constrained Application Protocol . . . . . . . . . . . . . . 9 69 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 10 70 2.2. Request/Response Model . . . . . . . . . . . . . . . . . 12 71 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 14 72 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . 15 73 3. Message Format . . . . . . . . . . . . . . . . . . . . . . . 15 74 3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 17 75 3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 19 76 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 20 77 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20 78 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 20 79 4.3. Messages Transmitted Without Reliability . . . . . . . . 22 80 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 23 81 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 24 82 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 24 83 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 25 84 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 26 85 4.8.1. Changing The Parameters . . . . . . . . . . . . . . . 27 86 4.8.2. Time Values derived from Transmission Parameters . . 28 87 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 30 88 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 30 89 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 30 90 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 32 91 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 32 92 5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 33 93 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 33 94 5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 34 95 5.3.2. Request/Response Matching Rules . . . . . . . . . . . 35 97 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 35 98 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 36 99 5.4.2. Proxy Unsafe/Safe-to-Forward and NoCacheKey . . . . . 37 100 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 38 101 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 38 102 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 38 103 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 38 104 5.5. Payloads and Representations . . . . . . . . . . . . . . 39 105 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 39 106 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 40 107 5.5.3. Selected Representation . . . . . . . . . . . . . . . 40 108 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 40 109 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 41 110 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 42 111 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 42 112 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 43 113 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 43 114 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 45 115 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 45 116 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 46 117 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 46 118 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 46 119 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 46 120 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 47 121 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 47 122 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 47 123 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 49 124 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 50 125 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 51 126 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 52 127 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 53 128 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 53 129 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 54 130 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . 54 131 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 54 132 5.10.7. Location-Path and Location-Query . . . . . . . . . . 55 133 5.10.8. Conditional Request Options . . . . . . . . . . . . 56 134 5.10.9. Size1 Option . . . . . . . . . . . . . . . . . . . . 57 135 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 57 136 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 58 137 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 59 138 6.3. Normalization and Comparison Rules . . . . . . . . . . . 59 139 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 60 140 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 61 141 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 62 142 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 62 143 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 63 144 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 63 146 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 64 147 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 64 148 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 65 149 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 66 150 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 66 151 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 66 152 9.1. DTLS-secured CoAP . . . . . . . . . . . . . . . . . . . . 68 153 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 69 154 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 69 155 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 70 156 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 73 157 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 74 158 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 74 159 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . 75 160 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 75 161 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 75 162 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 76 163 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . 76 164 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . 76 165 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 77 166 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 77 167 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . 78 168 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 78 169 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . 78 170 11. Security Considerations . . . . . . . . . . . . . . . . . . . 78 171 11.1. Protocol Parsing, Processing URIs . . . . . . . . . . . 78 172 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 79 173 11.3. Risk of amplification . . . . . . . . . . . . . . . . . 80 174 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . 81 175 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 82 176 11.6. Constrained node considerations . . . . . . . . . . . . 84 177 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 84 178 12.1. CoAP Code Registries . . . . . . . . . . . . . . . . . . 84 179 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 85 180 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 85 181 12.2. Option Number Registry . . . . . . . . . . . . . . . . . 87 182 12.3. Content-Format Registry . . . . . . . . . . . . . . . . 89 183 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . 90 184 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 91 185 12.6. Service Name and Port Number Registration . . . . . . . 92 186 12.7. Secure Service Name and Port Number Registration . . . . 93 187 12.8. Multicast Address Registration . . . . . . . . . . . . . 94 188 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 94 189 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 95 190 14.1. Normative References . . . . . . . . . . . . . . . . . . 95 191 14.2. Informative References . . . . . . . . . . . . . . . . . 97 192 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 100 193 Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 105 194 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . 107 195 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 117 197 1. Introduction 199 The use of web services (web APIs) on the Internet has become 200 ubiquitous in most applications, and depends on the fundamental 201 Representational State Transfer [REST] architecture of the web. 203 The Constrained RESTful Environments (CoRE) work aims at realizing 204 the REST architecture in a suitable form for the most constrained 205 nodes (e.g. 8-bit microcontrollers with limited RAM and ROM) and 206 networks (e.g. 6LoWPAN, [RFC4944]). Constrained networks such as 207 6LoWPAN support the fragmentation of IPv6 packets into small link- 208 layer frames, however incurring significant reduction in packet 209 delivery probability. One design goal of CoAP has been to keep 210 message overhead small, thus limiting the need for fragmentation. 212 One of the main goals of CoAP is to design a generic web protocol for 213 the special requirements of this constrained environment, especially 214 considering energy, building automation and other machine-to-machine 215 (M2M) applications. The goal of CoAP is not to blindly compress HTTP 216 [RFC2616], but rather to realize a subset of REST common with HTTP 217 but optimized for M2M applications. Although CoAP could be used for 218 refashioning simple HTTP interfaces into a more compact protocol, it 219 more importantly also offers features for M2M such as built-in 220 discovery, multicast support and asynchronous message exchanges. 222 This document specifies the Constrained Application Protocol (CoAP), 223 which easily translates to HTTP for integration with the existing web 224 while meeting specialized requirements such as multicast support, 225 very low overhead and simplicity for constrained environments and M2M 226 applications. 228 1.1. Features 230 CoAP has the following main features: 232 o Constrained web protocol fulfilling M2M requirements. 234 o UDP [RFC0768] binding with optional reliability supporting unicast 235 and multicast requests. 237 o Asynchronous message exchanges. 239 o Low header overhead and parsing complexity. 241 o URI and Content-type support. 243 o Simple proxy and caching capabilities. 245 o A stateless HTTP mapping, allowing proxies to be built providing 246 access to CoAP resources via HTTP in a uniform way or for HTTP 247 simple interfaces to be realized alternatively over CoAP. 249 o Security binding to Datagram Transport Layer Security (DTLS) 250 [RFC6347]. 252 1.2. Terminology 254 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 255 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 256 "OPTIONAL" in this document are to be interpreted as described in 257 [RFC2119] when they appear in ALL CAPS. These words may also appear 258 in this document in lower case as plain English words, absent their 259 normative meanings. 261 This specification requires readers to be familiar with all the terms 262 and concepts that are discussed in [RFC2616], including "resource", 263 "representation", "cache", and "fresh". In addition, this 264 specification defines the following terminology: 266 Endpoint 267 An entity participating in the CoAP protocol. Colloquially, an 268 endpoint lives on a "Node", although "Host" would be more 269 consistent with Internet standards usage, and is further 270 identified by transport layer multiplexing information that can 271 include a UDP port number and a security association 272 (Section 4.1). 274 Sender 275 The originating endpoint of a message. When the aspect of 276 identification of the specific sender is in focus, also "source 277 endpoint". 279 Recipient 280 The destination endpoint of a message. When the aspect of 281 identification of the specific recipient is in focus, also 282 "destination endpoint". 284 Client 285 The originating endpoint of a request; the destination endpoint of 286 a response. 288 Server 289 The destination endpoint of a request; the originating endpoint of 290 a response. 292 Origin Server 293 The server on which a given resource resides or is to be created. 295 Intermediary 296 A CoAP endpoint that acts both as a server and as a client towards 297 (possibly via further intermediaries) an origin server. A common 298 form of an intermediary is a proxy; several classes of such 299 proxies are discussed in this specification. 301 Proxy 302 An intermediary that mainly is concerned with forwarding requests 303 and relaying back responses, possibly performing caching, 304 namespace translation, or protocol translation in the process. As 305 opposed to intermediaries in the general sense, proxies generally 306 do not implement specific application semantics. Based on the 307 position in the overall structure of the request forwarding, there 308 are two common forms of proxy: forward-proxy and reverse-proxy. 309 In some cases, a single endpoint might act as an origin server, 310 forward-proxy, or reverse-proxy, switching behavior based on the 311 nature of each request. 313 Forward-Proxy 314 A "forward-proxy" is an endpoint selected by a client, usually via 315 local configuration rules, to perform requests on behalf of the 316 client, doing any necessary translations. Some translations are 317 minimal, such as for proxy requests for "coap" URIs, whereas other 318 requests might require translation to and from entirely different 319 application-layer protocols. 321 Reverse-Proxy 322 A "reverse-proxy" is an endpoint that stands in for one or more 323 other server(s) and satisfies requests on behalf of these, doing 324 any necessary translations. Unlike a forward-proxy, the client 325 may not be aware that it is communicating with a reverse-proxy; a 326 reverse-proxy receives requests as if it was the origin server for 327 the target resource. 329 CoAP-to-CoAP Proxy 330 A proxy that maps from a CoAP request to a CoAP request, i.e. 331 uses the CoAP protocol both on the server and the client side. 332 Contrast to cross-proxy. 334 Cross-Proxy 335 A cross-protocol proxy, or "cross-proxy" for short, is a proxy 336 that translates between different protocols, such as a CoAP-to- 337 HTTP proxy or an HTTP-to-CoAP proxy. While this specification 338 makes very specific demands of CoAP-to-CoAP proxies, there is more 339 variation possible in cross-proxies. 341 Confirmable Message 342 Some messages require an acknowledgement. These messages are 343 called "Confirmable". When no packets are lost, each Confirmable 344 message elicits exactly one return message of type Acknowledgement 345 or type Reset. 347 Non-confirmable Message 348 Some other messages do not require an acknowledgement. This is 349 particularly true for messages that are repeated regularly for 350 application requirements, such as repeated readings from a sensor. 352 Acknowledgement Message 353 An Acknowledgement message acknowledges that a specific 354 Confirmable message arrived. By itself, an Acknowledgement 355 message does not indicate success or failure of any request 356 encapsulated in the Confirmable message, but the Acknowledgement 357 message may also carry a Piggy-Backed Response (q.v.). 359 Reset Message 360 A Reset message indicates that a specific message (Confirmable or 361 Non-confirmable) was received, but some context is missing to 362 properly process it. This condition is usually caused when the 363 receiving node has rebooted and has forgotten some state that 364 would be required to interpret the message. Provoking a Reset 365 message (e.g., by sending an Empty Confirmable message) is also 366 useful as an inexpensive check of the liveness of an endpoint 367 ("CoAP ping"). 369 Piggy-backed Response 370 A Piggy-backed Response is included right in a CoAP 371 Acknowledgement (ACK) message that is sent to acknowledge receipt 372 of the Request for this Response (Section 5.2.1). 374 Separate Response 375 When a Confirmable message carrying a Request is acknowledged with 376 an Empty message (e.g., because the server doesn't have the answer 377 right away), a Separate Response is sent in a separate message 378 exchange (Section 5.2.2). 380 Empty Message 381 A message with a Code of 0.00; neither a request nor a response. 382 An Empty message only contains the four-byte header. 384 Critical Option 385 An option that would need to be understood by the endpoint 386 ultimately receiving the message in order to properly process the 387 message (Section 5.4.1). Note that the implementation of critical 388 options is, as the name "Option" implies, generally optional: 390 unsupported critical options lead to an error response or summary 391 rejection of the message. 393 Elective Option 394 An option that is intended to be ignored by an endpoint that does 395 not understand it. Processing the message even without 396 understanding the option is acceptable (Section 5.4.1). 398 Unsafe Option 399 An option that would need to be understood by a proxy receiving 400 the message in order to safely forward the message 401 (Section 5.4.2). Not every critical option is an unsafe option. 403 Safe-to-Forward Option 404 An option that is intended to be safe for forwarding by a proxy 405 that does not understand it. Forwarding the message even without 406 understanding the option is acceptable (Section 5.4.2). 408 Resource Discovery 409 The process where a CoAP client queries a server for its list of 410 hosted resources (i.e., links, Section 7). 412 Content-Format 413 The combination of an Internet media type, potentially with 414 specific parameters given, and a content-coding (which is often 415 the identity content-coding), identified by a numeric identifier 416 defined by the CoAP Content-Format Registry. When the focus is 417 less on the numeric identifier than on the combination of these 418 characteristics of a resource representation, this is also called 419 "representation format". 421 Additional terminology for constrained nodes and constrained node 422 networks can be found in [I-D.ietf-lwig-terminology]. 424 In this specification, the term "byte" is used in its now customary 425 sense as a synonym for "octet". 427 All multi-byte integers in this protocol are interpreted in network 428 byte order. 430 Where arithmetic is used, this specification uses the notation 431 familiar from the programming language C, except that the operator 432 "**" stands for exponentiation. 434 2. Constrained Application Protocol 436 The interaction model of CoAP is similar to the client/server model 437 of HTTP. However, machine-to-machine interactions typically result 438 in a CoAP implementation acting in both client and server roles. A 439 CoAP request is equivalent to that of HTTP, and is sent by a client 440 to request an action (using a method code) on a resource (identified 441 by a URI) on a server. The server then sends a response with a 442 response code; this response may include a resource representation. 444 Unlike HTTP, CoAP deals with these interchanges asynchronously over a 445 datagram-oriented transport such as UDP. This is done logically 446 using a layer of messages that supports optional reliability (with 447 exponential back-off). CoAP defines four types of messages: 448 Confirmable, Non-confirmable, Acknowledgement, Reset; method codes 449 and response codes included in some of these messages make them carry 450 requests or responses. The basic exchanges of the four types of 451 messages are somewhat orthogonal to the request/response 452 interactions; requests can be carried in Confirmable and Non- 453 confirmable messages, and responses can be carried in these as well 454 as piggy-backed in Acknowledgement messages. 456 One could think of CoAP logically as using a two-layer approach, a 457 CoAP messaging layer used to deal with UDP and the asynchronous 458 nature of the interactions, and the request/response interactions 459 using Method and Response codes (see Figure 1). CoAP is however a 460 single protocol, with messaging and request/response just features of 461 the CoAP header. 463 +----------------------+ 464 | Application | 465 +----------------------+ 466 +----------------------+ \ 467 | Requests/Responses | | 468 |----------------------| | CoAP 469 | Messages | | 470 +----------------------+ / 471 +----------------------+ 472 | UDP | 473 +----------------------+ 475 Figure 1: Abstract layering of CoAP 477 2.1. Messaging Model 479 The CoAP messaging model is based on the exchange of messages over 480 UDP between endpoints. 482 CoAP uses a short fixed-length binary header (4 bytes) that may be 483 followed by compact binary options and a payload. This message 484 format is shared by requests and responses. The CoAP message format 485 is specified in Section 3. Each message contains a Message ID used 486 to detect duplicates and for optional reliability. (The Message ID 487 is compact; its 16-bit size enables up to about 250 messages per 488 second from one endpoint to another with default protocol 489 parameters.) 491 Reliability is provided by marking a message as Confirmable (CON). A 492 Confirmable message is retransmitted using a default timeout and 493 exponential back-off between retransmissions, until the recipient 494 sends an Acknowledgement message (ACK) with the same Message ID (in 495 this example, 0x7d34) from the corresponding endpoint; see Figure 2. 496 When a recipient is not at all able to process a Confirmable message 497 (i.e., not even able to provide a suitable error response), it 498 replies with a Reset message (RST) instead of an Acknowledgement 499 (ACK). 501 Client Server 502 | | 503 | CON [0x7d34] | 504 +----------------->| 505 | | 506 | ACK [0x7d34] | 507 |<-----------------+ 508 | | 510 Figure 2: Reliable message transmission 512 A message that does not require reliable transmission, for example 513 each single measurement out of a stream of sensor data, can be sent 514 as a Non-confirmable message (NON). These are not acknowledged, but 515 still have a Message ID for duplicate detection (in this example, 516 0x01a0); see Figure 3. When a recipient is not able to process a 517 Non-confirmable message, it may reply with a Reset message (RST). 519 Client Server 520 | | 521 | NON [0x01a0] | 522 +----------------->| 523 | | 525 Figure 3: Unreliable message transmission 527 See Section 4 for details of CoAP messages. 529 As CoAP runs over UDP, it also supports the use of multicast IP 530 destination addresses, enabling multicast CoAP requests. Section 8 531 discusses the proper use of CoAP messages with multicast addresses 532 and precautions for avoiding response congestion. 534 Several security modes are defined for CoAP in Section 9 ranging from 535 no security to certificate-based security. This document specifies a 536 binding to DTLS for securing the protocol; the use of IPsec with CoAP 537 is discussed in [I-D.bormann-core-ipsec-for-coap]. 539 2.2. Request/Response Model 541 CoAP request and response semantics are carried in CoAP messages, 542 which include either a Method code or Response code, respectively. 543 Optional (or default) request and response information, such as the 544 URI and payload media type are carried as CoAP options. A Token is 545 used to match responses to requests independently from the underlying 546 messages (Section 5.3). (Note that the Token is a concept separate 547 from the Message ID.) 549 A request is carried in a Confirmable (CON) or Non-confirmable (NON) 550 message, and if immediately available, the response to a request 551 carried in a Confirmable message is carried in the resulting 552 Acknowledgement (ACK) message. This is called a piggy-backed 553 response, detailed in Section 5.2.1. (There is no need for 554 separately acknowledging a piggy-backed response, as the client will 555 retransmit the request if the Acknowledgement message carrying the 556 piggy-backed response is lost.) Two examples for a basic GET request 557 with piggy-backed response are shown in Figure 4, one successful, one 558 resulting in a 4.04 (Not Found) response. 560 Client Server Client Server 561 | | | | 562 | CON [0xbc90] | | CON [0xbc91] | 563 | GET /temperature | | GET /temperature | 564 | (Token 0x71) | | (Token 0x72) | 565 +----------------->| +----------------->| 566 | | | | 567 | ACK [0xbc90] | | ACK [0xbc91] | 568 | 2.05 Content | | 4.04 Not Found | 569 | (Token 0x71) | | (Token 0x72) | 570 | "22.5 C" | | "Not found" | 571 |<-----------------+ |<-----------------+ 572 | | | | 574 Figure 4: Two GET requests with piggy-backed responses 576 If the server is not able to respond immediately to a request carried 577 in a Confirmable message, it simply responds with an Empty 578 Acknowledgement message so that the client can stop retransmitting 579 the request. When the response is ready, the server sends it in a 580 new Confirmable message (which then in turn needs to be acknowledged 581 by the client). This is called a separate response, as illustrated 582 in Figure 5 and described in more detail in Section 5.2.2. 584 Client Server 585 | | 586 | CON [0x7a10] | 587 | GET /temperature | 588 | (Token 0x73) | 589 +----------------->| 590 | | 591 | ACK [0x7a10] | 592 |<-----------------+ 593 | | 594 ... Time Passes ... 595 | | 596 | CON [0x23bb] | 597 | 2.05 Content | 598 | (Token 0x73) | 599 | "22.5 C" | 600 |<-----------------+ 601 | | 602 | ACK [0x23bb] | 603 +----------------->| 604 | | 606 Figure 5: A GET request with a separate response 608 If a request is sent in a Non-confirmable message, then the response 609 is sent using a new Non-confirmable message, although the server may 610 instead send a Confirmable message. This type of exchange is 611 illustrated in Figure 6. 613 Client Server 614 | | 615 | NON [0x7a11] | 616 | GET /temperature | 617 | (Token 0x74) | 618 +----------------->| 619 | | 620 | NON [0x23bc] | 621 | 2.05 Content | 622 | (Token 0x74) | 623 | "22.5 C" | 624 |<-----------------+ 625 | | 627 Figure 6: A NON request and response 629 CoAP makes use of GET, PUT, POST and DELETE methods in a similar 630 manner to HTTP, with the semantics specified in Section 5.8. (Note 631 that the detailed semantics of CoAP methods are "almost, but not 632 entirely unlike" [HHGTTG] those of HTTP methods: Intuition taken from 633 HTTP experience generally does apply well, but there are enough 634 differences that make it worthwhile to actually read the present 635 specification.) 637 Methods beyond the basic four can be added to CoAP in separate 638 specifications. New methods do not necessarily have to use requests 639 and responses in pairs. Even for existing methods, a single request 640 may yield multiple responses, e.g. for a multicast request 641 (Section 8) or with the Observe option [I-D.ietf-core-observe]. 643 URI support in a server is simplified as the client already parses 644 the URI and splits it into host, port, path and query components, 645 making use of default values for efficiency. Response codes relate 646 to a small subset of HTTP response codes with a few CoAP specific 647 codes added, as defined in Section 5.9. 649 2.3. Intermediaries and Caching 651 The protocol supports the caching of responses in order to 652 efficiently fulfill requests. Simple caching is enabled using 653 freshness and validity information carried with CoAP responses. A 654 cache could be located in an endpoint or an intermediary. Caching 655 functionality is specified in Section 5.6. 657 Proxying is useful in constrained networks for several reasons, 658 including network traffic limiting, to improve performance, to access 659 resources of sleeping devices or for security reasons. The proxying 660 of requests on behalf of another CoAP endpoint is supported in the 661 protocol. When using a proxy, the URI of the resource to request is 662 included in the request, while the destination IP address is set to 663 the address of the proxy. See Section 5.7 for more information on 664 proxy functionality. 666 As CoAP was designed according to the REST architecture [REST] and 667 thus exhibits functionality similar to that of the HTTP protocol, it 668 is quite straightforward to map from CoAP to HTTP and from HTTP to 669 CoAP. Such a mapping may be used to realize an HTTP REST interface 670 using CoAP, or for converting between HTTP and CoAP. This conversion 671 can be carried out by a cross-protocol proxy ("cross-proxy"), which 672 converts the method or response code, media type, and options to the 673 corresponding HTTP feature. Section 10 provides more detail about 674 HTTP mapping. 676 2.4. Resource Discovery 678 Resource discovery is important for machine-to-machine interactions, 679 and is supported using the CoRE Link Format [RFC6690] as discussed in 680 Section 7. 682 3. Message Format 684 CoAP is based on the exchange of compact messages which, by default, 685 are transported over UDP (i.e. each CoAP message occupies the data 686 section of one UDP datagram). CoAP may also be used over Datagram 687 Transport Layer Security (DTLS) (see Section 9.1). It could also be 688 used over other transports such as SMS, TCP or SCTP, the 689 specification of which is out of this document's scope. (UDP-lite 690 [RFC3828] and UDP zero checksum [RFC6936] are not supported by CoAP.) 692 CoAP messages are encoded in a simple binary format. The message 693 format starts with a fixed-size 4-byte header. This is followed by a 694 variable-length Token value which can be between 0 and 8 bytes long. 695 Following the Token value comes a sequence of zero or more CoAP 696 Options in Type-Length-Value (TLV) format, optionally followed by a 697 payload which takes up the rest of the datagram. 699 0 1 2 3 700 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 701 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 702 |Ver| T | TKL | Code | Message ID | 703 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 704 | Token (if any, TKL bytes) ... 705 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 706 | Options (if any) ... 707 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 708 |1 1 1 1 1 1 1 1| Payload (if any) ... 709 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 710 Figure 7: Message Format 712 The fields in the header are defined as follows: 714 Version (Ver): 2-bit unsigned integer. Indicates the CoAP version 715 number. Implementations of this specification MUST set this field 716 to 1 (01 binary). Other values are reserved for future versions. 717 Messages with unknown version numbers MUST be silently ignored. 719 Type (T): 2-bit unsigned integer. Indicates if this message is of 720 type Confirmable (0), Non-confirmable (1), Acknowledgement (2) or 721 Reset (3). The semantics of these message types are defined in 722 Section 4. 724 Token Length (TKL): 4-bit unsigned integer. Indicates the length of 725 the variable-length Token field (0-8 bytes). Lengths 9-15 are 726 reserved, MUST NOT be sent, and MUST be processed as a message 727 format error. 729 Code: 8-bit unsigned integer, split into a 3-bit class (most 730 significant bits) and a 5-bit detail (least significant bits), 731 documented as c.dd where c is a digit from 0 to 7 for the 3-bit 732 subfield and dd are two digits from 00 to 31 for the 5-bit 733 subfield. The class can indicate a request (0), a success 734 response (2), a client error response (4), or a server error 735 response (5). (All other class values are reserved.) As a 736 special case, Code 0.00 indicates an Empty message. In case of a 737 request, the Code field indicates the Request Method; in case of a 738 response a Response Code. Possible values are maintained in the 739 CoAP Code Registries (Section 12.1). The semantics of requests 740 and responses are defined in Section 5. 742 Message ID: 16-bit unsigned integer in network byte order. Used for 743 the detection of message duplication, and to match messages of 744 type Acknowledgement/Reset to messages of type Confirmable/Non- 745 confirmable. The rules for generating a Message ID and matching 746 messages are defined in Section 4. 748 The header is followed by the Token value, which may be 0 to 8 bytes, 749 as given by the Token Length field. The Token value is used to 750 correlate requests and responses. The rules for generating a Token 751 and correlating requests and responses are defined in Section 5.3.1. 753 Header and Token are followed by zero or more Options (Section 3.1). 754 An Option can be followed by the end of the message, by another 755 Option, or by the Payload Marker and the payload. 757 Following the header, token, and options, if any, comes the optional 758 payload. If present and of non-zero length, it is prefixed by a 759 fixed, one-byte Payload Marker (0xFF) which indicates the end of 760 options and the start of the payload. The payload data extends from 761 after the marker to the end of the UDP datagram, i.e., the Payload 762 Length is calculated from the datagram size. The absence of the 763 Payload Marker denotes a zero-length payload. The presence of a 764 marker followed by a zero-length payload MUST be processed as a 765 message format error. 767 Implementation Note: The byte value 0xFF may also occur within an 768 option length or value, so simple byte-wise scanning for 0xFF is 769 not a viable technique for finding the payload marker. The byte 770 0xFF has the meaning of a payload marker only where the beginning 771 of another option could occur. 773 3.1. Option Format 775 CoAP defines a number of options which can be included in a message. 776 Each option instance in a message specifies the Option Number of the 777 defined CoAP option, the length of the Option Value and the Option 778 Value itself. 780 Instead of specifying the Option Number directly, the instances MUST 781 appear in order of their Option Numbers and a delta encoding is used 782 between them: The Option Number for each instance is calculated as 783 the sum of its delta and the Option Number of the preceding instance 784 in the message. For the first instance in a message, a preceding 785 option instance with Option Number zero is assumed. Multiple 786 instances of the same option can be included by using a delta of 787 zero. 789 Option Numbers are maintained in the CoAP Option Number Registry 790 (Section 12.2). See Section 5.4 for the semantics of the options 791 defined in this document. 793 0 1 2 3 4 5 6 7 794 +---------------+---------------+ 795 | | | 796 | Option Delta | Option Length | 1 byte 797 | | | 798 +---------------+---------------+ 799 \ \ 800 / Option Delta / 0-2 bytes 801 \ (extended) \ 802 +-------------------------------+ 803 \ \ 804 / Option Length / 0-2 bytes 805 \ (extended) \ 806 +-------------------------------+ 807 \ \ 808 / / 809 \ \ 810 / Option Value / 0 or more bytes 811 \ \ 812 / / 813 \ \ 814 +-------------------------------+ 816 Figure 8: Option Format 818 The fields in an option are defined as follows: 820 Option Delta: 4-bit unsigned integer. A value between 0 and 12 821 indicates the Option Delta. Three values are reserved for special 822 constructs: 824 13: An 8-bit unsigned integer follows the initial byte and 825 indicates the Option Delta minus 13. 827 14: A 16-bit unsigned integer in network byte order follows the 828 initial byte and indicates the Option Delta minus 269. 830 15: Reserved for the Payload Marker. If the field is set to 831 this value but the entire byte is not the payload marker, 832 this MUST be processed as a message format error. 834 The resulting Option Delta is used as the difference between the 835 Option Number of this option and that of the previous option (or 836 zero for the first option). In other words, the Option Number is 837 calculated by simply summing the Option Delta values of this and 838 all previous options before it. 840 Option Length: 4-bit unsigned integer. A value between 0 and 12 841 indicates the length of the Option Value, in bytes. Three values 842 are reserved for special constructs: 844 13: An 8-bit unsigned integer precedes the Option Value and 845 indicates the Option Length minus 13. 847 14: A 16-bit unsigned integer in network byte order precedes the 848 Option Value and indicates the Option Length minus 269. 850 15: Reserved for future use. If the field is set to this value, 851 it MUST be processed as a message format error. 853 Value: A sequence of exactly Option Length bytes. The length and 854 format of the Option Value depend on the respective option, which 855 MAY define variable length values. See Section 3.2 for the 856 formats used in this document; options defined in other documents 857 MAY make use of other option value formats. 859 3.2. Option Value Formats 861 The options defined in this document make use of the following option 862 value formats. 864 empty: A zero-length sequence of bytes. 866 opaque: An opaque sequence of bytes. 868 uint: A non-negative integer which is represented in network byte 869 order using the number of bytes given by the Option Length 870 field. 872 An option definition may specify a range of permissible 873 numbers of bytes; if it has a choice, a sender SHOULD 874 represent the integer with as few bytes as possible, i.e., 875 without leading zero bytes. For example, the number 0 is 876 represented with an empty option value (a zero-length 877 sequence of bytes), and the number 1 by a single byte with 878 the numerical value of 1 (bit combination 00000001 in most 879 significant bit first notation). A recipient MUST be 880 prepared to process values with leading zero bytes. 882 Implementation Note: The exceptional behavior permitted 883 for the sender is intended for highly constrained, 884 templated implementations (e.g., hardware 885 implementations) that use fixed size options in the 886 templates. 888 string: A Unicode string which is encoded using UTF-8 [RFC3629] in 889 Net-Unicode form [RFC5198]. 891 Note that here and in all other places where UTF-8 encoding 892 is used in the CoAP protocol, the intention is that the 893 encoded strings can be directly used and compared as opaque 894 byte strings by CoAP protocol implementations. There is no 895 expectation and no need to perform normalization within a 896 CoAP implementation (except where Unicode strings that are 897 not known to be normalized are imported from sources 898 outside the CoAP protocol). Note also that ASCII strings 899 (that do not make use of special control characters) are 900 always valid UTF-8 Net-Unicode strings. 902 4. Message Transmission 904 CoAP messages are exchanged asynchronously between CoAP endpoints. 905 They are used to transport CoAP requests and responses, the semantics 906 of which are defined in Section 5. 908 As CoAP is bound to non-reliable transports such as UDP, CoAP 909 messages may arrive out of order, appear duplicated, or go missing 910 without notice. For this reason, CoAP implements a lightweight 911 reliability mechanism, without trying to re-create the full feature 912 set of a transport like TCP. It has the following features: 914 o Simple stop-and-wait retransmission reliability with exponential 915 back-off for Confirmable messages. 917 o Duplicate detection for both Confirmable and Non-confirmable 918 messages. 920 4.1. Messages and Endpoints 922 A CoAP endpoint is the source or destination of a CoAP message. The 923 specific definition of an endpoint depends on the transport being 924 used for CoAP. For the transports defined in this specification, the 925 endpoint is identified depending on the security mode used (see 926 Section 9): With no security, the endpoint is solely identified by an 927 IP address and a UDP port number. With other security modes, the 928 endpoint is identified as defined by the security mode. 930 There are different types of messages. The type of a message is 931 specified by the Type field of the CoAP Header. 933 Separate from the message type, a message may carry a request, a 934 response, or be Empty. This is signaled by the Request/Response Code 935 field in the CoAP Header and is relevant to the request/response 936 model. Possible values for the field are maintained in the CoAP Code 937 Registries (Section 12.1). 939 An Empty message has the Code field set to 0.00. The Token Length 940 field MUST be set to 0 and bytes of data MUST NOT be present after 941 the Message ID field. If there are any bytes, they MUST be processed 942 as a message format error. 944 4.2. Messages Transmitted Reliably 946 The reliable transmission of a message is initiated by marking the 947 message as Confirmable in the CoAP header. A Confirmable message 948 always carries either a request or response, unless it is used only 949 to elicit a Reset message in which case it is Empty. A recipient 950 MUST acknowledge a Confirmable message with an Acknowledgement 951 message or, if it lacks context to process the message properly 952 (including the case where the message is Empty, uses a code with a 953 reserved class (1, 6 or 7), or has a message format error), MUST 954 reject it; rejecting a Confirmable message is effected by sending a 955 matching Reset message and otherwise ignoring it. The 956 Acknowledgement message MUST echo the Message ID of the Confirmable 957 message, and MUST carry a response or be Empty (see Section 5.2.1 and 958 Section 5.2.2). The Reset message MUST echo the Message ID of the 959 Confirmable message, and MUST be Empty. Rejecting an Acknowledgement 960 or Reset message (including the case where the Acknowledgement 961 carries a request or a code with a reserved class, or the Reset 962 message is not Empty) is effected by silently ignoring it. More 963 generally, recipients of Acknowledgement and Reset messages MUST NOT 964 respond with either Acknowledgement or Reset messages. 966 The sender retransmits the Confirmable message at exponentially 967 increasing intervals, until it receives an acknowledgement (or Reset 968 message), or runs out of attempts. 970 Retransmission is controlled by two things that a CoAP endpoint MUST 971 keep track of for each Confirmable message it sends while waiting for 972 an acknowledgement (or reset): a timeout and a retransmission 973 counter. For a new Confirmable message, the initial timeout is set 974 to a random duration (often not an integral number of seconds) 975 between ACK_TIMEOUT and (ACK_TIMEOUT * ACK_RANDOM_FACTOR) (see 976 Section 4.8), and the retransmission counter is set to 0. When the 977 timeout is triggered and the retransmission counter is less than 978 MAX_RETRANSMIT, the message is retransmitted, the retransmission 979 counter is incremented, and the timeout is doubled. If the 980 retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the 981 endpoint receives a Reset message, then the attempt to transmit the 982 message is canceled and the application process informed of failure. 983 On the other hand, if the endpoint receives an acknowledgement in 984 time, transmission is considered successful. 986 This specification makes no strong requirements on the accuracy of 987 the clocks used to implement the above binary exponential backoff 988 algorithm. In particular, an endpoint may be late for a specific 989 retransmission due to its sleep schedule, and maybe catch up on the 990 next one. However, the minimum spacing before another retransmission 991 is ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST 992 stay in the envelope of MAX_TRANSMIT_SPAN (see Section 4.8.2), even 993 if that means a sender may miss an opportunity to transmit. 995 A CoAP endpoint that sent a Confirmable message MAY give up in 996 attempting to obtain an ACK even before the MAX_RETRANSMIT counter 997 value is reached: E.g., the application has canceled the request as 998 it no longer needs a response, or there is some other indication that 999 the CON message did arrive. In particular, a CoAP request message 1000 may have elicited a separate response, in which case it is clear to 1001 the requester that only the ACK was lost and a retransmission of the 1002 request would serve no purpose. However, a responder MUST NOT in 1003 turn rely on this cross-layer behavior from a requester, i.e. it 1004 MUST retain the state to create the ACK for the request, if needed, 1005 even if a Confirmable response was already acknowledged by the 1006 requester. 1008 Another reason for giving up retransmission MAY be the receipt of 1009 ICMP errors. If it is desired to take account of ICMP errors, to 1010 mitigate potential spoofing attacks, implementations SHOULD take care 1011 to check the information about the original datagram in the ICMP 1012 message, including port numbers and CoAP header information such as 1013 message type and code, Message ID, and Token; if this is not possible 1014 due to limitations of the UDP service API, ICMP errors SHOULD be 1015 ignored. Packet Too Big errors [RFC4443] ("fragmentation needed and 1016 DF set" for IPv4 [RFC0792]) cannot properly occur and SHOULD be 1017 ignored if the implementation note in Section 4.6 is followed; 1018 otherwise, they SHOULD feed into a path MTU discovery algorithm 1019 [RFC4821]. Source Quench and Time Exceeded ICMP messages SHOULD be 1020 ignored. Host, network, port or protocol unreachable errors, or 1021 parameter problem errors MAY, after appropriate vetting, be used to 1022 inform the application of a failure in sending. 1024 4.3. Messages Transmitted Without Reliability 1026 Some messages do not require an acknowledgement. This is 1027 particularly true for messages that are repeated regularly for 1028 application requirements, such as repeated readings from a sensor 1029 where eventual success is sufficient. 1031 As a more lightweight alternative, a message can be transmitted less 1032 reliably by marking the message as Non-confirmable. A Non- 1033 confirmable message always carries either a request or response and 1034 MUST NOT be Empty. A Non-confirmable message MUST NOT be 1035 acknowledged by the recipient. If a recipient lacks context to 1036 process the message properly (including the case where the message is 1037 Empty, uses a code with a reserved class (1, 6 or 7), or has a 1038 message format error), it MUST reject the message; rejecting a Non- 1039 confirmable message MAY involve sending a matching Reset message, and 1040 apart from the Reset message the rejected message MUST be silently 1041 ignored. 1043 At the CoAP level, there is no way for the sender to detect if a Non- 1044 confirmable message was received or not. A sender MAY choose to 1045 transmit multiple copies of a Non-confirmable message within 1046 MAX_TRANSMIT_SPAN (limited by the provisions of Section 4.7, in 1047 particular by PROBING_RATE if no response is received), or the 1048 network may duplicate the message in transit. To enable the receiver 1049 to act only once on the message, Non-confirmable messages specify a 1050 Message ID as well. (This Message ID is drawn from the same number 1051 space as the Message IDs for Confirmable messages.) 1053 Summarizing Section 4.2 and Section 4.3, the four message types can 1054 be used as in Table 1. "*" means that the combination is not used in 1055 normal operation, but only to elicit a Reset message ("CoAP ping"). 1057 +----------+-----+-----+-----+-----+ 1058 | | CON | NON | ACK | RST | 1059 +----------+-----+-----+-----+-----+ 1060 | Request | X | X | - | - | 1061 | Response | X | X | X | - | 1062 | Empty | * | - | X | X | 1063 +----------+-----+-----+-----+-----+ 1065 Table 1: Usage of message types 1067 4.4. Message Correlation 1069 An Acknowledgement or Reset message is related to a Confirmable 1070 message or Non-confirmable message by means of a Message ID along 1071 with additional address information of the corresponding endpoint. 1072 The Message ID is a 16-bit unsigned integer that is generated by the 1073 sender of a Confirmable or Non-confirmable message and included in 1074 the CoAP header. The Message ID MUST be echoed in the 1075 Acknowledgement or Reset message by the recipient. 1077 The same Message ID MUST NOT be re-used (in communicating with the 1078 same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2). 1080 Implementation Note: Several implementation strategies can be 1081 employed for generating Message IDs. In the simplest case a CoAP 1082 endpoint generates Message IDs by keeping a single Message ID 1083 variable, which is changed each time a new Confirmable or Non- 1084 confirmable message is sent regardless of the destination address 1085 or port. Endpoints dealing with large numbers of transactions 1086 could keep multiple Message ID variables, for example per prefix 1087 or destination address (note that some receiving endpoints may not 1088 be able to distinguish unicast and multicast packets addressed to 1089 it, so endpoints generating Message IDs need to make sure these do 1090 not overlap). It is strongly recommended that the initial value 1091 of the variable (e.g., on startup) be randomized, in order to make 1092 successful off-path attacks on the protocol less likely. 1094 For an Acknowledgement or Reset message to match a Confirmable or 1095 Non-confirmable message, the Message ID and source endpoint of the 1096 Acknowledgement or Reset message MUST match the Message ID and 1097 destination endpoint of the Confirmable or Non-confirmable message. 1099 4.5. Message Deduplication 1101 A recipient might receive the same Confirmable message (as indicated 1102 by the Message ID and source endpoint) multiple times within the 1103 EXCHANGE_LIFETIME (Section 4.8.2), for example, when its 1104 Acknowledgement went missing or didn't reach the original sender 1105 before the first timeout. The recipient SHOULD acknowledge each 1106 duplicate copy of a Confirmable message using the same 1107 Acknowledgement or Reset message, but SHOULD process any request or 1108 response in the message only once. This rule MAY be relaxed in case 1109 the Confirmable message transports a request that is idempotent (see 1110 Section 5.1) or can be handled in an idempotent fashion. Examples 1111 for relaxed message deduplication: 1113 o A server might relax the requirement to answer all retransmissions 1114 of an idempotent request with the same response (Section 4.2), so 1115 that it does not have to maintain state for Message IDs. For 1116 example, an implementation might want to process duplicate 1117 transmissions of a GET, PUT or DELETE request as separate requests 1118 if the effort incurred by duplicate processing is less expensive 1119 than keeping track of previous responses would be. 1121 o A constrained server might even want to relax this requirement for 1122 certain non-idempotent requests if the application semantics make 1123 this trade-off favorable. For example, if the result of a POST 1124 request is just the creation of some short-lived state at the 1125 server, it may be less expensive to incur this effort multiple 1126 times for a request than keeping track of whether a previous 1127 transmission of the same request already was processed. 1129 A recipient might receive the same Non-confirmable message (as 1130 indicated by the Message ID and source endpoint) multiple times 1131 within NON_LIFETIME (Section 4.8.2). As a general rule that MAY be 1132 relaxed based on the specific semantics of a message, the recipient 1133 SHOULD silently ignore any duplicated Non-confirmable message, and 1134 SHOULD process any request or response in the message only once. 1136 4.6. Message Size 1138 While specific link layers make it beneficial to keep CoAP messages 1139 small enough to fit into their link layer packets (see Section 1), 1140 this is a matter of implementation quality. The CoAP specification 1141 itself provides only an upper bound to the message size. Messages 1142 larger than an IP packet result in undesirable packet fragmentation. 1143 A CoAP message, appropriately encapsulated, SHOULD fit within a 1144 single IP packet (i.e., avoid IP fragmentation) and (by fitting into 1145 one UDP payload) obviously needs to fit within a single IP datagram. 1146 If the Path MTU is not known for a destination, an IP MTU of 1280 1147 bytes SHOULD be assumed; if nothing is known about the size of the 1148 headers, good upper bounds are 1152 bytes for the message size and 1149 1024 bytes for the payload size. 1151 Implementation Note: CoAP's choice of message size parameters works 1152 well with IPv6 and with most of today's IPv4 paths. (However, 1153 with IPv4, it is harder to absolutely ensure that there is no IP 1154 fragmentation. If IPv4 support on unusual networks is a 1155 consideration, implementations may want to limit themselves to 1156 more conservative IPv4 datagram sizes such as 576 bytes; worse, 1157 the absolute minimum value of the IP MTU for IPv4 is as low as 68 1158 bytes, which would leave only 40 bytes minus security overhead for 1159 a UDP payload. Implementations extremely focused on this problem 1160 set might also set the IPv4 DF bit and perform some form of path 1161 MTU discovery [RFC4821]; this should generally be unnecessary in 1162 most realistic use cases for CoAP, however.) A more important 1163 kind of fragmentation in many constrained networks is that on the 1164 adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 1165 bytes including various overheads); this may motivate 1166 implementations to be frugal in their packet sizes and to move to 1167 block-wise transfers [I-D.ietf-core-block] when approaching three- 1168 digit message sizes. 1170 Message sizes are also of considerable importance to 1171 implementations on constrained nodes. Many implementations will 1172 need to allocate a buffer for incoming messages. If an 1173 implementation is too constrained to allow for allocating the 1174 above-mentioned upper bound, it could apply the following 1175 implementation strategy for messages not using DTLS security: 1176 Implementations receiving a datagram into a buffer that is too 1177 small are usually able to determine if the trailing portion of a 1178 datagram was discarded and to retrieve the initial portion. So, 1179 if not all of the payload, at least the CoAP header and options 1180 are likely to fit within the buffer. A server can thus fully 1181 interpret a request and return a 4.13 (Request Entity Too Large, 1182 see Section 5.9.2.9) response code if the payload was truncated. 1183 A client sending an idempotent request and receiving a response 1184 larger than would fit in the buffer can repeat the request with a 1185 suitable value for the Block Option [I-D.ietf-core-block]. 1187 4.7. Congestion Control 1188 Basic congestion control for CoAP is provided by the exponential 1189 back-off mechanism in Section 4.2. 1191 In order not to cause congestion, Clients (including proxies) MUST 1192 strictly limit the number of simultaneous outstanding interactions 1193 that they maintain to a given server (including proxies) to NSTART. 1194 An outstanding interaction is either a CON for which an ACK has not 1195 yet been received but is still expected (message layer) or a request 1196 for which neither a response nor an Acknowledgment message has yet 1197 been received but is still expected (which may both occur at the same 1198 time, counting as one outstanding interaction). The default value of 1199 NSTART for this specification is 1. 1201 Further congestion control optimizations and considerations are 1202 expected in the future, which may for example provide automatic 1203 initialization of the CoAP transmission parameters defined in 1204 Section 4.8, and thus may allow a value for NSTART greater than one. 1206 A client stops expecting a response to a Confirmable request for 1207 which no acknowledgment message was received, after 1208 EXCHANGE_LIFETIME. The specific algorithm by which a client stops to 1209 "expect" a response to a Confirmable request that was acknowledged, 1210 or to a Non-confirmable request, is not defined. Unless this is 1211 modified by additional congestion control optimizations, it MUST be 1212 chosen in such a way that an endpoint does not exceed an average data 1213 rate of PROBING_RATE in sending to another endpoint that does not 1214 respond. 1216 Note: CoAP places the onus of congestion control mostly on the 1217 clients. However, clients may malfunction or actually be 1218 attackers, e.g. to perform amplification attacks (Section 11.3). 1219 To limit the damage (to the network and to its own energy 1220 resources), a server SHOULD implement some rate limiting for its 1221 response transmission based on reasonable assumptions about 1222 application requirements. This is most helpful if the rate limit 1223 can be made effective for the misbehaving endpoints, only. 1225 4.8. Transmission Parameters 1227 Message transmission is controlled by the following parameters: 1229 +-------------------+---------------+ 1230 | name | default value | 1231 +-------------------+---------------+ 1232 | ACK_TIMEOUT | 2 seconds | 1233 | ACK_RANDOM_FACTOR | 1.5 | 1234 | MAX_RETRANSMIT | 4 | 1235 | NSTART | 1 | 1236 | DEFAULT_LEISURE | 5 seconds | 1237 | PROBING_RATE | 1 Byte/second | 1238 +-------------------+---------------+ 1240 Table 2: CoAP Protocol Parameters 1242 4.8.1. Changing The Parameters 1244 The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT, 1245 NSTART, DEFAULT_LEISURE (Section 8.2), and PROBING_RATE may be 1246 configured to values specific to the application environment 1247 (including dynamically adjusted values), however the configuration 1248 method is out of scope of this document. It is RECOMMENDED that an 1249 application environment use consistent values for these parameters; 1250 the specific effects of operating with inconsistent values in an 1251 application environment are outside the scope of the present 1252 specification. 1254 The transmission parameters have been chosen to achieve a behavior in 1255 the presence of congestion that is safe in the Internet. If a 1256 configuration desires to use different values, the onus is on the 1257 configuration to ensure these congestion control properties are not 1258 violated. In particular, a decrease of ACK_TIMEOUT below 1 second 1259 would violate the guidelines of [RFC5405]. 1260 ([I-D.allman-tcpm-rto-consider] provides some additional background.) 1261 CoAP was designed to enable implementations that do not maintain 1262 round-trip-time (RTT) measurements. However, where it is desired to 1263 decrease the ACK_TIMEOUT significantly or increase NSTART, this can 1264 only be done safely when maintaining such measurements. 1265 Configurations MUST NOT decrease ACK_TIMEOUT or increase NSTART 1266 without using mechanisms that ensure congestion control safety, 1267 either defined in the configuration or in future standards documents. 1269 ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have 1270 a value that is sufficiently different from 1.0 to provide some 1271 protection from synchronization effects. 1273 MAX_RETRANSMIT can be freely adjusted, but a too small value will 1274 reduce the probability that a Confirmable message is actually 1275 received, while a larger value than given here will require further 1276 adjustments in the time values (see Section 4.8.2). 1278 If the choice of transmission parameters leads to an increase of 1279 derived time values (see Section 4.8.2), the configuration mechanism 1280 MUST ensure the adjusted value is also available to all the endpoints 1281 that these adjusted values are to be used to communicate with. 1283 4.8.2. Time Values derived from Transmission Parameters 1285 The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR and MAX_RETRANSMIT 1286 influences the timing of retransmissions, which in turn influences 1287 how long certain information items need to be kept by an 1288 implementation. To be able to unambiguously reference these derived 1289 time values, we give them names as follows: 1291 o MAX_TRANSMIT_SPAN is the maximum time from the first transmission 1292 of a Confirmable message to its last retransmission. For the 1293 default transmission parameters, the value is (2+4+8+16)*1.5 = 45 1294 seconds, or more generally: 1296 ACK_TIMEOUT * ((2 ** MAX_RETRANSMIT) - 1) * ACK_RANDOM_FACTOR 1298 o MAX_TRANSMIT_WAIT is the maximum time from the first transmission 1299 of a Confirmable message to the time when the sender gives up on 1300 receiving an acknowledgement or reset. For the default 1301 transmission parameters, the value is (2+4+8+16+32)*1.5 = 93 1302 seconds, or more generally: 1304 ACK_TIMEOUT * ((2 ** (MAX_RETRANSMIT + 1)) - 1) * 1305 ACK_RANDOM_FACTOR 1307 In addition, some assumptions need to be made on the characteristics 1308 of the network and the nodes. 1310 o MAX_LATENCY is the maximum time a datagram is expected to take 1311 from the start of its transmission to the completion of its 1312 reception. This constant is related to the MSL (Maximum Segment 1313 Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 1314 minutes" ([RFC0793] glossary, page 81). Note that this is not 1315 necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not 1316 intended to describe a situation when the protocol works well, but 1317 the worst case situation against which the protocol has to guard. 1318 We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart 1319 from being reasonably realistic for the bulk of configurations as 1320 well as close to the historic choice for TCP, this value also 1321 allows Message ID lifetime timers to be represented in 8 bits 1322 (when measured in seconds). In these calculations, there is no 1323 assumption that the direction of the transmission is irrelevant 1324 (i.e. that the network is symmetric), just that the same value 1325 can reasonably be used as a maximum value for both directions. If 1326 that is not the case, the following calculations become only 1327 slightly more complex. 1329 o PROCESSING_DELAY is the time a node takes to turn around a 1330 Confirmable message into an acknowledgement. We assume the node 1331 will attempt to send an ACK before having the sender time out, so 1332 as a conservative assumption we set it equal to ACK_TIMEOUT. 1334 o MAX_RTT is the maximum round-trip time, or: 1336 (2 * MAX_LATENCY) + PROCESSING_DELAY 1338 From these values, we can derive the following values relevant to the 1339 protocol operation: 1341 o EXCHANGE_LIFETIME is the time from starting to send a Confirmable 1342 message to the time when an acknowledgement is no longer expected, 1343 i.e. message layer information about the message exchange can be 1344 purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a 1345 MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the 1346 way back. Note that there is no need to consider 1347 MAX_TRANSMIT_WAIT if the configuration is chosen such that the 1348 last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the 1349 difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is 1350 less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY 1351 is a worst case value unlikely to be met in the real world. In 1352 this case, EXCHANGE_LIFETIME simplifies to: 1354 MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY 1356 or 247 seconds with the default transmission parameters. 1358 o NON_LIFETIME is the time from sending a Non-confirmable message to 1359 the time its Message ID can be safely reused. If multiple 1360 transmission of a NON message is not used, its value is 1361 MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a 1362 NON message multiple times, in particular for multicast 1363 applications. While the period of re-use is not bounded by the 1364 specification, an expectation of reliable detection of duplication 1365 at the receiver is in the timescales of MAX_TRANSMIT_SPAN. 1366 Therefore, for this purpose, it is safer to use the value: 1368 MAX_TRANSMIT_SPAN + MAX_LATENCY 1370 or 145 seconds with the default transmission parameters; however, 1371 an implementation that just wants to use a single timeout value 1372 for retiring Message IDs can safely use the larger value for 1373 EXCHANGE_LIFETIME. 1375 Table 3 summarizes the derived parameters introduced in this 1376 subsection with their default values. 1378 +-------------------+---------------+ 1379 | name | default value | 1380 +-------------------+---------------+ 1381 | MAX_TRANSMIT_SPAN | 45 s | 1382 | MAX_TRANSMIT_WAIT | 93 s | 1383 | MAX_LATENCY | 100 s | 1384 | PROCESSING_DELAY | 2 s | 1385 | MAX_RTT | 202 s | 1386 | EXCHANGE_LIFETIME | 247 s | 1387 | NON_LIFETIME | 145 s | 1388 +-------------------+---------------+ 1390 Table 3: Derived Protocol Parameters 1392 5. Request/Response Semantics 1394 CoAP operates under a similar request/response model as HTTP: a CoAP 1395 endpoint in the role of a "client" sends one or more CoAP requests to 1396 a "server", which services the requests by sending CoAP responses. 1397 Unlike HTTP, requests and responses are not sent over a previously 1398 established connection, but exchanged asynchronously over CoAP 1399 messages. 1401 5.1. Requests 1403 A CoAP request consists of the method to be applied to the resource, 1404 the identifier of the resource, a payload and Internet media type (if 1405 any), and optional meta-data about the request. 1407 CoAP supports the basic methods of GET, POST, PUT, DELETE, which are 1408 easily mapped to HTTP. They have the same properties of safe (only 1409 retrieval) and idempotent (you can invoke it multiple times with the 1410 same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method 1411 is safe, therefore it MUST NOT take any other action on a resource 1412 other than retrieval. The GET, PUT and DELETE methods MUST be 1413 performed in such a way that they are idempotent. POST is not 1414 idempotent, because its effect is determined by the origin server and 1415 dependent on the target resource; it usually results in a new 1416 resource being created or the target resource being updated. 1418 A request is initiated by setting the Code field in the CoAP header 1419 of a Confirmable or a Non-confirmable message to a Method Code and 1420 including request information. 1422 The methods used in requests are described in detail in Section 5.8. 1424 5.2. Responses 1425 After receiving and interpreting a request, a server responds with a 1426 CoAP response, which is matched to the request by means of a client- 1427 generated token (Section 5.3, note that this is different from the 1428 Message ID that matches a Confirmable message to its 1429 Acknowledgement). 1431 A response is identified by the Code field in the CoAP header being 1432 set to a Response Code. Similar to the HTTP Status Code, the CoAP 1433 Response Code indicates the result of the attempt to understand and 1434 satisfy the request. These codes are fully defined in Section 5.9. 1435 The Response Code numbers to be set in the Code field of the CoAP 1436 header are maintained in the CoAP Response Code Registry 1437 (Section 12.1.2). 1439 0 1440 0 1 2 3 4 5 6 7 1441 +-+-+-+-+-+-+-+-+ 1442 |class| detail | 1443 +-+-+-+-+-+-+-+-+ 1445 Figure 9: Structure of a Response Code 1447 The upper three bits of the 8-bit Response Code number define the 1448 class of response. The lower five bits do not have any 1449 categorization role; they give additional detail to the overall class 1450 (Figure 9). 1452 As a human readable notation for specifications and protocol 1453 diagnostics, CoAP code numbers including the response code are 1454 documented in the format "c.dd", where "c" is the class in decimal, 1455 and "dd" is the detail as a two-digit decimal. For example, 1456 "Forbidden" is written as 4.03 -- indicating an 8-bit code value of 1457 hexadecimal 0x83 (4*0x20+3) or decimal 131 (4*32+3). 1459 There are 3 classes of response codes: 1461 2 - Success: The request was successfully received, understood, and 1462 accepted. 1464 4 - Client Error: The request contains bad syntax or cannot be 1465 fulfilled. 1467 5 - Server Error: The server failed to fulfill an apparently valid 1468 request. 1470 The response codes are designed to be extensible: Response Codes in 1471 the Client Error and Server Error class that are unrecognized by an 1472 endpoint are treated as being equivalent to the generic Response Code 1473 of that class (4.00 and 5.00, respectively). However, there is no 1474 generic Response Code indicating success, so a Response Code in the 1475 Success class that is unrecognized by an endpoint can only be used to 1476 determine that the request was successful without any further 1477 details. 1479 The possible response codes are described in detail in Section 5.9. 1481 Responses can be sent in multiple ways, which are defined in the 1482 following subsections. 1484 5.2.1. Piggy-backed 1486 In the most basic case, the response is carried directly in the 1487 Acknowledgement message that acknowledges the request (which requires 1488 that the request was carried in a Confirmable message). This is 1489 called a "Piggy-backed" Response. 1491 The response is returned in the Acknowledgement message independent 1492 of whether the response indicates success or failure. In effect, the 1493 response is piggy-backed on the Acknowledgement message, and no 1494 separate message is required to return the response. 1496 Implementation Note: The protocol leaves the decision whether to 1497 piggy-back a response or not (i.e., send a separate response) to 1498 the server. The client MUST be prepared to receive either. On 1499 the quality of implementation level, there is a strong expectation 1500 that servers will implement code to piggy-back whenever possible 1501 -- saving resources in the network and both at the client and at 1502 the server. 1504 5.2.2. Separate 1506 It may not be possible to return a piggy-backed response in all 1507 cases. For example, a server might need longer to obtain the 1508 representation of the resource requested than it can wait sending 1509 back the Acknowledgement message, without risking the client to 1510 repeatedly retransmit the request message (see also the discussion of 1511 PROCESSING_DELAY in Section 4.8.2). The Response to a request 1512 carried in a Non-confirmable message is always sent separately (as 1513 there is no Acknowledgement message). 1515 One way to implement this in a server is to initiate the attempt to 1516 obtain the resource representation and, while that is in progress, 1517 time out an acknowledgement timer. A server may also immediately 1518 send an acknowledgement knowing in advance that there will be no 1519 piggy-backed response. In both cases, the acknowledgement 1520 effectively is a promise that the request will be acted upon later. 1522 When the server finally has obtained the resource representation, it 1523 sends the response. When it is desired that this message is not 1524 lost, it is sent as a Confirmable message from the server to the 1525 client and answered by the client with an Acknowledgement, echoing 1526 the new Message ID chosen by the server. (It may also be sent as a 1527 Non-confirmable message; see Section 5.2.3.) 1529 When the server chooses to use a separate response, it sends the 1530 Acknowledgement to the Confirmable request as an Empty message. Once 1531 the server sends back an Empty Acknowledgement, it MUST NOT send back 1532 the response in another Acknowledgement, even if the client 1533 retransmits another identical request. If a retransmitted request is 1534 received (perhaps because the original Acknowledgement was delayed), 1535 another Empty Acknowledgement is sent and any response MUST be sent 1536 as a separate response. 1538 If the server then sends a Confirmable response, the client's 1539 Acknowledgement to that response MUST also be an Empty message (one 1540 that carries neither a request nor a response). The server MUST stop 1541 retransmitting its response on any matching Acknowledgement (silently 1542 ignoring any response code or payload) or Reset message. 1544 Implementation Notes: Note that, as the underlying datagram 1545 transport may not be sequence-preserving, the Confirmable message 1546 carrying the response may actually arrive before or after the 1547 Acknowledgement message for the request; for the purposes of 1548 terminating the retransmission sequence, this also serves as an 1549 acknowledgement. Note also that, while the CoAP protocol itself 1550 does not make any specific demands here, there is an expectation 1551 that the response will come within a time frame that is reasonable 1552 from an application point of view; as there is no underlying 1553 transport protocol that could be instructed to run a keep-alive 1554 mechanism, the requester may want to set up a timeout that is 1555 unrelated to CoAP's retransmission timers in case the server is 1556 destroyed or otherwise unable to send the response.) 1558 5.2.3. Non-confirmable 1560 If the request message is Non-confirmable, then the response SHOULD 1561 be returned in a Non-confirmable message as well. However, an 1562 endpoint MUST be prepared to receive a Non-confirmable response 1563 (preceded or followed by an Empty Acknowledgement message) in reply 1564 to a Confirmable request, or a Confirmable response in reply to a 1565 Non-confirmable request. 1567 5.3. Request/Response Matching 1568 Regardless of how a response is sent, it is matched to the request by 1569 means of a token that is included by the client in the request, along 1570 with additional address information of the corresponding endpoint. 1572 5.3.1. Token 1574 The Token is used to match a response with a request. The token 1575 value is a sequence of 0 to 8 bytes. (Note that every message 1576 carries a token, even if it is of zero length.) Every request 1577 carries a client-generated token, which the server MUST echo in any 1578 resulting response without modification. 1580 A token is intended for use as a client-local identifier for 1581 differentiating between concurrent requests (see Section 5.3); it 1582 could have been called a "request ID". 1584 The client SHOULD generate tokens in such a way that tokens currently 1585 in use for a given source/destination endpoint pair are unique. 1586 (Note that a client implementation can use the same token for any 1587 request if it uses a different endpoint each time, e.g. a different 1588 source port number.) An empty token value is appropriate e.g. when 1589 no other tokens are in use to a destination, or when requests are 1590 made serially per destination and receive piggy-backed responses. 1591 There are however multiple possible implementation strategies to 1592 fulfill this. 1594 A client sending a request without using transport layer security 1595 (Section 9) SHOULD use a non-trivial, randomized token to guard 1596 against spoofing of responses (Section 11.4). This protective use of 1597 tokens is the reason they are allowed to be up to 8 bytes in size. 1598 The actual size of the random component to be used for the Token 1599 depends on the security requirements of the client and the level of 1600 threat posed by spoofing of responses. A client that is connected to 1601 the general Internet SHOULD use at least 32 bits of randomness; 1602 keeping in mind that not being directly connected to the Internet is 1603 not necessarily sufficient protection against spoofing. (Note that 1604 the Message ID adds little in protection as it is usually 1605 sequentially assigned, i.e. guessable, and can be circumvented by 1606 spoofing a separate response.) Clients that want to optimize the 1607 Token length may further want to detect the level of ongoing attacks 1608 (e.g., by tallying recent Token mismatches in incoming messages) and 1609 adjust the Token length upwards appropriately. [RFC4086] discusses 1610 randomness requirements for security. 1612 An endpoint receiving a token it did not generate MUST treat it as 1613 opaque and make no assumptions about its content or structure. 1615 5.3.2. Request/Response Matching Rules 1617 The exact rules for matching a response to a request are as follows: 1619 1. The source endpoint of the response MUST be the same as the 1620 destination endpoint of the original request. 1622 2. In a piggy-backed response, both the Message ID of the 1623 Confirmable request and the Acknowledgement, and the token of the 1624 response and original request MUST match. In a separate 1625 response, just the token of the response and original request 1626 MUST match. 1628 In case a message carrying a response is unexpected (the client is 1629 not waiting for a response from the identified endpoint, at the 1630 endpoint addressed, and/or with the given token), the response is 1631 rejected (Section 4.2, Section 4.3). 1633 Implementation Note: A client that receives a response in a CON 1634 message may want to clean up the message state right after sending 1635 the ACK. If that ACK is lost and the server retransmits the CON, 1636 the client may no longer have any state to correlate this response 1637 to, making the retransmission an unexpected message; the client 1638 will likely send a Reset message so it does not receive any more 1639 retransmissions. This behavior is normal and not an indication of 1640 an error. (Clients that are not aggressively optimized in their 1641 state memory usage will still have message state that will 1642 identify the second CON as a retransmission. Clients that 1643 actually expect more messages from the server 1644 [I-D.ietf-core-observe] will have to keep state in any case.) 1646 5.4. Options 1648 Both requests and responses may include a list of one or more 1649 options. For example, the URI in a request is transported in several 1650 options, and meta-data that would be carried in an HTTP header in 1651 HTTP is supplied as options as well. 1653 CoAP defines a single set of options that are used in both requests 1654 and responses: 1656 o Content-Format 1658 o ETag 1660 o Location-Path 1662 o Location-Query 1663 o Max-Age 1665 o Proxy-Uri 1667 o Proxy-Scheme 1669 o Uri-Host 1671 o Uri-Path 1673 o Uri-Port 1675 o Uri-Query 1677 o Accept 1679 o If-Match 1681 o If-None-Match 1683 o Size1 1685 The semantics of these options along with their properties are 1686 defined in detail in Section 5.10. 1688 Not all options are defined for use with all methods and response 1689 codes. The possible options for methods and response codes are 1690 defined in Section 5.8 and Section 5.9 respectively. In case an 1691 option is not defined for a method or response code, it MUST NOT be 1692 included by a sender and MUST be treated like an unrecognized option 1693 by a recipient. 1695 5.4.1. Critical/Elective 1697 Options fall into one of two classes: "critical" or "elective". The 1698 difference between these is how an option unrecognized by an endpoint 1699 is handled: 1701 o Upon reception, unrecognized options of class "elective" MUST be 1702 silently ignored. 1704 o Unrecognized options of class "critical" that occur in a 1705 Confirmable request MUST cause the return of a 4.02 (Bad Option) 1706 response. This response SHOULD include a diagnostic payload 1707 describing the unrecognized option(s) (see Section 5.5.2). 1709 o Unrecognized options of class "critical" that occur in a 1710 Confirmable response, or piggy-backed in an Acknowledgement, MUST 1711 cause the response to be rejected (Section 4.2). 1713 o Unrecognized options of class "critical" that occur in a Non- 1714 confirmable message MUST cause the message to be rejected 1715 (Section 4.3). 1717 Note that, whether critical or elective, an option is never 1718 "mandatory" (it is always optional): These rules are defined in order 1719 to enable implementations to stop processing options they do not 1720 understand or implement. 1722 Critical/Elective rules apply to non-proxying endpoints. A proxy 1723 processes options based on Unsafe/Safe-to-Forward classes as defined 1724 in Section 5.7. 1726 5.4.2. Proxy Unsafe/Safe-to-Forward and NoCacheKey 1728 In addition to an option being marked as Critical or Elective, 1729 options are also classified based on how a proxy is to deal with the 1730 option if it does not recognize it. For this purpose, an option can 1731 either be considered Unsafe to Forward (UnSafe is set) or Safe-to- 1732 Forward (UnSafe is clear). 1734 In addition, for an option that is marked Safe-to-Forward, the option 1735 number indicates whether it is intended to be part of the Cache-Key 1736 (Section 5.6) in a request or not; if some of the NoCacheKey bits are 1737 0, it is, if all NoCacheKey bits are 1, it is not (see 1738 Section 5.4.6). 1740 Note: The Cache-Key indication is relevant only for proxies that do 1741 not implement the given option as a request option and instead 1742 rely on the Unsafe/Safe-to-Forward indication only. E.g., for 1743 ETag, actually using the request option as a part of the Cache-Key 1744 is grossly inefficient, but it is the best thing one can do if 1745 ETag is not implemented by a proxy, as the response is going to 1746 differ based on the presence of the request option. A more useful 1747 proxy that does implement the ETag request option is not using 1748 ETag as a part of the Cache-Key. 1750 NoCacheKey is indicated in three bits so that only one out of 1751 eight codepoints is qualified as NoCacheKey, assuming this is the 1752 less likely case. 1754 Proxy behavior with regard to these classes is defined in 1755 Section 5.7. 1757 5.4.3. Length 1759 Option values are defined to have a specific length, often in the 1760 form of an upper and lower bound. If the length of an option value 1761 in a request is outside the defined range, that option MUST be 1762 treated like an unrecognized option (see Section 5.4.1). 1764 5.4.4. Default Values 1766 Options may be defined to have a default value. If the value of 1767 option is intended to be this default value, the option SHOULD NOT be 1768 included in the message. If the option is not present, the default 1769 value MUST be assumed. 1771 Where a critical option has a default value, this is chosen in such a 1772 way that the absence of the option in a message can be processed 1773 properly both by implementations unaware of the critical option and 1774 by implementations that interpret this absence as the presence of the 1775 default value for the option. 1777 5.4.5. Repeatable Options 1779 The definition of some options specifies that those options are 1780 repeatable. An option that is repeatable MAY be included one or more 1781 times in a message. An option that is not repeatable MUST NOT be 1782 included more than once in a message. 1784 If a message includes an option with more occurrences than the option 1785 is defined for, each supernumerary option occurrence that appears 1786 subsequently in the message MUST be treated like an unrecognized 1787 option (see Section 5.4.1). 1789 5.4.6. Option Numbers 1791 An Option is identified by an option number, which also provides some 1792 additional semantics information: e.g., odd numbers indicate a 1793 critical option, while even numbers indicate an elective option. 1794 Note that this is not just a convention, it is a feature of the 1795 protocol: Whether an option is elective or critical is entirely 1796 determined by whether its option number is even or odd. 1798 More generally speaking, an Option number is constructed with a bit 1799 mask to indicate if an option is Critical/Elective, Unsafe/Safe-to- 1800 Forward and in the case of Safe-to-Forward, also a Cache-Key 1801 indication as shown by the following figure. In the following text, 1802 the bit mask is expressed as a single byte that is applied to the 1803 least significant byte of the option number in unsigned integer 1804 representation. When bit 7 (the least significant bit) is 1, an 1805 option is Critical (and likewise Elective when 0). When bit 6 is 1, 1806 an option is Unsafe (and likewise Safe-to-Forward when 0). When bit 1807 6 is 0, i.e., the option is not Unsafe, it is not a Cache-Key 1808 (NoCacheKey) if and only if bits 3-5 are all set to 1; all other bit 1809 combinations mean that it indeed is a Cache-Key. These classes of 1810 options are explained in the next sections. 1812 0 1 2 3 4 5 6 7 1813 +---+---+---+---+---+---+---+---+ 1814 | | NoCacheKey| U | C | 1815 +---+---+---+---+---+---+---+---+ 1817 Figure 10: Option Number Mask (Least Significant Byte) 1819 An endpoint may use an equivalent of the C code in Figure 11 to 1820 derive the characteristics of an option number "onum". 1822 Critical = (onum & 1); 1823 UnSafe = (onum & 2); 1824 NoCacheKey = ((onum & 0x1e) == 0x1c); 1826 Figure 11: Determining Characteristics from an Option Number 1828 The option numbers for the options defined in this document are 1829 listed in the CoAP Option Number Registry (Section 12.2). 1831 5.5. Payloads and Representations 1833 Both requests and responses may include a payload, depending on the 1834 method or response code respectively. If a method or response code 1835 is not defined to have a payload, then a sender MUST NOT include one, 1836 and a recipient MUST ignore it. 1838 5.5.1. Representation 1840 The payload of requests or of responses indicating success is 1841 typically a representation of a resource ("resource representation") 1842 or the result of the requested action ("action result"). Its format 1843 is specified by the Internet media type and content coding given by 1844 the Content-Format Option. In the absence of this option, no default 1845 value is assumed and the format will need to be inferred by the 1846 application (e.g., from the application context). Payload "sniffing" 1847 SHOULD only be attempted if no content type is given. 1849 Implementation Note: On a quality of implementation level, there is 1850 a strong expectation that a Content-Format indication will be 1851 provided with resource representations whenever possible. This is 1852 not a "SHOULD"-level requirement solely because it is not a 1853 protocol requirement, and it also would be difficult to outline 1854 exactly in what cases this expectation can be violated. 1856 For responses indicating a client or server error, the payload is 1857 considered a representation of the result of the requested action 1858 only if a Content-Format Option is given. In the absence of this 1859 option, the payload is a Diagnostic Payload (Section 5.5.2). 1861 5.5.2. Diagnostic Payload 1863 If no Content-Format option is given, the payload of responses 1864 indicating a client or server error is a brief human-readable 1865 diagnostic message, explaining the error situation. This diagnostic 1866 message MUST be encoded using UTF-8 [RFC3629], more specifically 1867 using Net-Unicode form [RFC5198]. 1869 The message is similar to the Reason-Phrase on an HTTP status line. 1870 It is not intended for end-users but for software engineers that 1871 during debugging need to interpret it in the context of the present, 1872 English-language specification; therefore no mechanism for language 1873 tagging is needed or provided. In contrast to what is usual in HTTP, 1874 the payload SHOULD be empty if there is no additional information 1875 beyond the response code. 1877 5.5.3. Selected Representation 1879 Not all responses carry a payload that provides a representation of 1880 the resource addressed by the request. It is, however, sometimes 1881 useful to be able to refer to such a representation in relation to a 1882 response, independent of whether it actually was enclosed. 1884 We use the term "selected representation" to refer to the current 1885 representation of a target resource that would have been selected in 1886 a successful response if the corresponding request had used the 1887 method GET and excluded any conditional request options 1888 (Section 5.10.8). 1890 Certain response options provide metadata about the selected 1891 representation, which might differ from the representation included 1892 in the message for responses to some state-changing methods. Of the 1893 response options defined in this specification, only the ETag 1894 response option (Section 5.10.6) is defined as selected 1895 representation metadata. 1897 5.5.4. Content Negotiation 1899 A server may be able to supply a representation for a resource in one 1900 of multiple representation formats. Without further information from 1901 the client, it will provide the representation in the format it 1902 prefers. 1904 By using the Accept Option (Section 5.10.4) in a request, the client 1905 can indicate which content-format it prefers to receive. 1907 5.6. Caching 1909 CoAP endpoints MAY cache responses in order to reduce the response 1910 time and network bandwidth consumption on future, equivalent 1911 requests. 1913 The goal of caching in CoAP is to reuse a prior response message to 1914 satisfy a current request. In some cases, a stored response can be 1915 reused without the need for a network request, reducing latency and 1916 network round-trips; a "freshness" mechanism is used for this purpose 1917 (see Section 5.6.1). Even when a new request is required, it is 1918 often possible to reuse the payload of a prior response to satisfy 1919 the request, thereby reducing network bandwidth usage; a "validation" 1920 mechanism is used for this purpose (see Section 5.6.2). 1922 Unlike HTTP, the cacheability of CoAP responses does not depend on 1923 the request method, but the Response Code. The cacheability of each 1924 Response Code is defined along the Response Code definitions in 1925 Section 5.9. Response Codes that indicate success and are 1926 unrecognized by an endpoint MUST NOT be cached. 1928 For a presented request, a CoAP endpoint MUST NOT use a stored 1929 response, unless: 1931 o the presented request method and that used to obtain the stored 1932 response match, 1934 o all options match between those in the presented request and those 1935 of the request used to obtain the stored response (which includes 1936 the request URI), except that there is no need for a match of any 1937 request options marked as NoCacheKey (Section 5.4) or recognized 1938 by the Cache and fully interpreted with respect to its specified 1939 cache behavior (such as the ETag request option, Section 5.10.6, 1940 see also Section 5.4.2), and 1942 o the stored response is either fresh or successfully validated as 1943 defined below. 1945 The set of request options that is used for matching the cache entry 1946 is also collectively referred to as the "Cache-Key". For URI schemes 1947 other than coap and coaps, matching of those options that constitute 1948 the request URI may be performed under rules specific to the URI 1949 scheme. 1951 5.6.1. Freshness Model 1953 When a response is "fresh" in the cache, it can be used to satisfy 1954 subsequent requests without contacting the origin server, thereby 1955 improving efficiency. 1957 The mechanism for determining freshness is for an origin server to 1958 provide an explicit expiration time in the future, using the Max-Age 1959 Option (see Section 5.10.5). The Max-Age Option indicates that the 1960 response is to be considered not fresh after its age is greater than 1961 the specified number of seconds. 1963 The Max-Age Option defaults to a value of 60. Thus, if it is not 1964 present in a cacheable response, then the response is considered not 1965 fresh after its age is greater than 60 seconds. If an origin server 1966 wishes to prevent caching, it MUST explicitly include a Max-Age 1967 Option with a value of zero seconds. 1969 If a client has a fresh stored response and makes a new request 1970 matching the request for that stored response, the new response 1971 invalidates the old response. 1973 5.6.2. Validation Model 1975 When an endpoint has one or more stored responses for a GET request, 1976 but cannot use any of them (e.g., because they are not fresh), it can 1977 use the ETag Option (Section 5.10.6) in the GET request to give the 1978 origin server an opportunity to both select a stored response to be 1979 used, and to update its freshness. This process is known as 1980 "validating" or "revalidating" the stored response. 1982 When sending such a request, the endpoint SHOULD add an ETag Option 1983 specifying the entity-tag of each stored response that is applicable. 1985 A 2.03 (Valid) response indicates the stored response identified by 1986 the entity-tag given in the response's ETag Option can be reused, 1987 after updating it as described in Section 5.9.1.3. 1989 Any other response code indicates that none of the stored responses 1990 nominated in the request is suitable. Instead, the response SHOULD 1991 be used to satisfy the request and MAY replace the stored response. 1993 5.7. Proxying 1995 A proxy is a CoAP endpoint that can be tasked by CoAP clients to 1996 perform requests on their behalf. This may be useful, for example, 1997 when the request could otherwise not be made, or to service the 1998 response from a cache in order to reduce response time and network 1999 bandwidth or energy consumption. 2001 In an overall architecture for a Constrained RESTful Environment, 2002 proxies can serve quite different purposes. Proxies can be 2003 explicitly selected by clients, a role that we term "forward-proxy". 2004 Proxies can also be inserted to stand in for origin servers, a role 2005 that we term "reverse-proxy". Orthogonal to this distinction, a 2006 proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP 2007 proxy) or translate from or to a different protocol ("cross-proxy"). 2008 Full definitions of these terms are provided in Section 1.2. 2010 Notes: The terminology in this specification has been selected to be 2011 culturally compatible with the terminology used in the wider Web 2012 application environments, without necessarily matching it in every 2013 detail (which may not even be relevant to Constrained RESTful 2014 Environments). Not too much semantics should be ascribed to the 2015 components of the terms (such as "forward", "reverse", or 2016 "cross"). 2018 HTTP proxies, besides acting as HTTP proxies, often offer a 2019 transport protocol proxying function ("CONNECT") to enable end-to- 2020 end transport layer security through the proxy. No such function 2021 is defined for CoAP-to-CoAP proxies in this specification, as 2022 forwarding of UDP packets is unlikely to be of much value in 2023 Constrained RESTful environments. See also Section 10.2.7 for the 2024 cross-proxy case. 2026 When a client uses a proxy to make a request that will use a secure 2027 URI scheme (e.g., coaps or https), the request towards the proxy 2028 SHOULD be sent using DTLS security except where equivalent lower 2029 layer security is used for the leg between the client and the proxy. 2031 5.7.1. Proxy Operation 2033 A proxy generally needs a way to determine potential request 2034 parameters for a request to a destination based on the request it 2035 received. This way is fully specified for a forward-proxy, but may 2036 depend on the specific configuration for a reverse-proxy. In 2037 particular, the client of a reverse-proxy generally does not indicate 2038 a locator for the destination, necessitating some form of namespace 2039 translation in the reverse-proxy. However, some aspects of the 2040 operation of proxies are common to all its forms. 2042 If a proxy does not employ a cache, then it simply forwards the 2043 translated request to the determined destination. Otherwise, if it 2044 does employ a cache but does not have a stored response that matches 2045 the translated request and is considered fresh, then it needs to 2046 refresh its cache according to Section 5.6. For options in the 2047 request that the proxy recognizes, it knows whether the option is 2048 intended to act as part of the key used in looking up the cached 2049 value or not. E.g., since requests for different Uri-Path values 2050 address different resources, Uri-Path values are always part of the 2051 Cache-Key, while, e.g., Token values are never part of the Cache-Key. 2052 For options that the proxy does not recognize but that are marked 2053 Safe-to-Forward in the option number, the option also indicates 2054 whether it is to be included in the Cache-Key (NoCacheKey is not all 2055 set) or not (NoCacheKey is all set). (Options that are unrecognized 2056 and marked Unsafe lead to 4.02 Bad Option.) 2058 If the request to the destination times out, then a 5.04 (Gateway 2059 Timeout) response MUST be returned. If the request to the 2060 destination returns a response that cannot be processed by the proxy 2061 (e.g, due to unrecognized critical options, message format errors), 2062 then a 5.02 (Bad Gateway) response MUST be returned. Otherwise, the 2063 proxy returns the response to the client. 2065 If a response is generated out of a cache, the generated (or implied) 2066 Max-Age Option MUST NOT extend the max-age originally set by the 2067 server, considering the time the resource representation spent in the 2068 cache. E.g., the Max-Age Option could be adjusted by the proxy for 2069 each response using the formula: 2071 proxy-max-age = original-max-age - cache-age 2073 For example if a request is made to a proxied resource that was 2074 refreshed 20 seconds ago and had an original Max-Age of 60 seconds, 2075 then that resource's proxied max-age is now 40 seconds. Considering 2076 potential network delays on the way from the origin server, a proxy 2077 should be conservative in the max-age values offered. 2079 All options present in a proxy request MUST be processed at the 2080 proxy. Unsafe options in a request that are not recognized by the 2081 proxy MUST lead to a 4.02 (Bad Option) response being returned by the 2082 proxy. A CoAP-to-CoAP proxy MUST forward to the origin server all 2083 Safe-to-Forward options that it does not recognize. Similarly, 2084 Unsafe options in a response that are not recognized by the CoAP-to- 2085 CoAP proxy server MUST lead to a 5.02 (Bad Gateway) response. Again, 2086 Safe-to-Forward options that are not recognized MUST be forwarded. 2088 Additional considerations for cross-protocol proxying between CoAP 2089 and HTTP are discussed in Section 10. 2091 5.7.2. Forward-Proxies 2093 CoAP distinguishes between requests made (as if) to an origin server 2094 and a request made through a forward-proxy. CoAP requests to a 2095 forward-proxy are made as normal Confirmable or Non-confirmable 2096 requests to the forward-proxy endpoint, but specify the request URI 2097 in a different way: The request URI in a proxy request is specified 2098 as a string in the Proxy-Uri Option (see Section 5.10.2), while the 2099 request URI in a request to an origin server is split into the Uri- 2100 Host, Uri-Port, Uri-Path and Uri-Query Options (see Section 5.10.1); 2101 alternatively the URI in a proxy request can be assembled from a 2102 Proxy-Scheme option and the split options mentioned. 2104 When a proxy request is made to an endpoint and the endpoint is 2105 unwilling or unable to act as proxy for the request URI, it MUST 2106 return a 5.05 (Proxying Not Supported) response. If the authority 2107 (host and port) is recognized as identifying the proxy endpoint 2108 itself (see Section 5.10.2), then the request MUST be treated as a 2109 local (non-proxied) request. 2111 Unless a proxy is configured to forward the proxy request to another 2112 proxy, it MUST translate the request as follows: The scheme of the 2113 request URI defines the outgoing protocol and its details (e.g., CoAP 2114 is used over UDP for the "coap" scheme and over DTLS for the "coaps" 2115 scheme.) For a CoAP-to-CoAP proxy, the origin server's IP address 2116 and port are determined by the authority component of the request 2117 URI, and the request URI is decoded and split into the Uri-Host, Uri- 2118 Port, Uri-Path and Uri-Query Options. This consumes the Proxy-Uri or 2119 Proxy-Scheme option, which is therefore not forwarded to the origin 2120 server. 2122 5.7.3. Reverse-Proxies 2124 Reverse-proxies do not make use of the Proxy-Uri or Proxy-Scheme 2125 options, but need to determine the destination (next hop) of a 2126 request from information in the request and information in their 2127 configuration. E.g., a reverse-proxy might offer various resources 2128 the existence of which it has learned through resource discovery as 2129 if they were its own resources. The reverse-proxy is free to build a 2130 namespace for the URIs that identify these resources. A reverse- 2131 proxy may also build a namespace that gives the client more control 2132 over where the request goes, e.g. by embedding host identifiers and 2133 port numbers into the URI path of the resources offered. 2135 In processing the response, a reverse-proxy has to be careful that 2136 ETag option values from different sources are not mixed up on one 2137 resource offered to its clients. In many cases, the ETag can be 2138 forwarded unchanged. If the mapping from a resource offered by the 2139 reverse-proxy to resources offered by its various origin servers is 2140 not unique, the reverse-proxy may need to generate a new ETag, making 2141 sure the semantics of this option are properly preserved. 2143 5.8. Method Definitions 2145 In this section each method is defined along with its behavior. A 2146 request with an unrecognized or unsupported Method Code MUST generate 2147 a 4.05 (Method Not Allowed) piggy-backed response. 2149 5.8.1. GET 2151 The GET method retrieves a representation for the information that 2152 currently corresponds to the resource identified by the request URI. 2153 If the request includes an Accept Option, that indicates the 2154 preferred content-format of a response. If the request includes an 2155 ETag Option, the GET method requests that ETag be validated and that 2156 the representation be transferred only if validation failed. Upon 2157 success a 2.05 (Content) or 2.03 (Valid) response code SHOULD be 2158 present in the response. 2160 The GET method is safe and idempotent. 2162 5.8.2. POST 2164 The POST method requests that the representation enclosed in the 2165 request be processed. The actual function performed by the POST 2166 method is determined by the origin server and dependent on the target 2167 resource. It usually results in a new resource being created or the 2168 target resource being updated. 2170 If a resource has been created on the server, the response returned 2171 by the server SHOULD have a 2.01 (Created) response code and SHOULD 2172 include the URI of the new resource in a sequence of one or more 2173 Location-Path and/or Location-Query Options (Section 5.10.7). If the 2174 POST succeeds but does not result in a new resource being created on 2175 the server, the response SHOULD have a 2.04 (Changed) response code. 2176 If the POST succeeds and results in the target resource being 2177 deleted, the response SHOULD have a 2.02 (Deleted) response code. 2179 POST is neither safe nor idempotent. 2181 5.8.3. PUT 2183 The PUT method requests that the resource identified by the request 2184 URI be updated or created with the enclosed representation. The 2185 representation format is specified by the media type and content 2186 coding given in the Content-Format Option, if provided. 2188 If a resource exists at the request URI the enclosed representation 2189 SHOULD be considered a modified version of that resource, and a 2.04 2190 (Changed) response code SHOULD be returned. If no resource exists 2191 then the server MAY create a new resource with that URI, resulting in 2192 a 2.01 (Created) response code. If the resource could not be created 2193 or modified, then an appropriate error response code SHOULD be sent. 2195 Further restrictions to a PUT can be made by including the If-Match 2196 (see Section 5.10.8.1) or If-None-Match (see Section 5.10.8.2) 2197 options in the request. 2199 PUT is not safe, but is idempotent. 2201 5.8.4. DELETE 2203 The DELETE method requests that the resource identified by the 2204 request URI be deleted. A 2.02 (Deleted) response code SHOULD be 2205 used on success or in case the resource did not exist before the 2206 request. 2208 DELETE is not safe, but is idempotent. 2210 5.9. Response Code Definitions 2212 Each response code is described below, including any options required 2213 in the response. Where appropriate, some of the codes will be 2214 specified in regards to related response codes in HTTP [RFC2616]; 2215 this does not mean that any such relationship modifies the HTTP 2216 mapping specified in Section 10. 2218 5.9.1. Success 2.xx 2220 This class of status code indicates that the clients request was 2221 successfully received, understood, and accepted. 2223 5.9.1.1. 2.01 Created 2225 Like HTTP 201 "Created", but only used in response to POST and PUT 2226 requests. The payload returned with the response, if any, is a 2227 representation of the action result. 2229 If the response includes one or more Location-Path and/or Location- 2230 Query Options, the values of these options specify the location at 2231 which the resource was created. Otherwise, the resource was created 2232 at the request URI. A cache receiving this response MUST mark any 2233 stored response for the created resource as not fresh. 2235 This response is not cacheable. 2237 5.9.1.2. 2.02 Deleted 2239 Like HTTP 204 "No Content", but only used in response to requests 2240 that cause the resource to cease being available, such as DELETE and 2241 in certain circumstances POST. The payload returned with the 2242 response, if any, is a representation of the action result. 2244 This response is not cacheable. However, a cache MUST mark any 2245 stored response for the deleted resource as not fresh. 2247 5.9.1.3. 2.03 Valid 2249 Related to HTTP 304 "Not Modified", but only used to indicate that 2250 the response identified by the entity-tag identified by the included 2251 ETag Option is valid. Accordingly, the response MUST include an ETag 2252 Option, and MUST NOT include a payload. 2254 When a cache that recognizes and processes the ETag response option 2255 receives a 2.03 (Valid) response, it MUST update the stored response 2256 with the value of the Max-Age Option included in the response 2257 (explicitly, or implicitly as a default value; see also 2258 Section 5.6.2). For each type of Safe-to-Forward option present in 2259 the response, the (possibly empty) set of options of this type that 2260 are present in the stored response MUST be replaced with the set of 2261 options of this type in the response received. (Unsafe options may 2262 trigger similar option specific processing as defined by the option.) 2264 5.9.1.4. 2.04 Changed 2266 Like HTTP 204 "No Content", but only used in response to POST and PUT 2267 requests. The payload returned with the response, if any, is a 2268 representation of the action result. 2270 This response is not cacheable. However, a cache MUST mark any 2271 stored response for the changed resource as not fresh. 2273 5.9.1.5. 2.05 Content 2275 Like HTTP 200 "OK", but only used in response to GET requests. 2277 The payload returned with the response is a representation of the 2278 target resource. 2280 This response is cacheable: Caches can use the Max-Age Option to 2281 determine freshness (see Section 5.6.1) and (if present) the ETag 2282 Option for validation (see Section 5.6.2). 2284 5.9.2. Client Error 4.xx 2286 This class of response code is intended for cases in which the client 2287 seems to have erred. These response codes are applicable to any 2288 request method. 2290 The server SHOULD include a diagnostic payload under the conditions 2291 detailed in Section 5.5.2. 2293 Responses of this class are cacheable: Caches can use the Max-Age 2294 Option to determine freshness (see Section 5.6.1). They cannot be 2295 validated. 2297 5.9.2.1. 4.00 Bad Request 2299 Like HTTP 400 "Bad Request". 2301 5.9.2.2. 4.01 Unauthorized 2303 The client is not authorized to perform the requested action. The 2304 client SHOULD NOT repeat the request without first improving its 2305 authentication status to the server. Which specific mechanism can be 2306 used for this is outside this document's scope; see also Section 9. 2308 5.9.2.3. 4.02 Bad Option 2310 The request could not be understood by the server due to one or more 2311 unrecognized or malformed options. The client SHOULD NOT repeat the 2312 request without modification. 2314 5.9.2.4. 4.03 Forbidden 2316 Like HTTP 403 "Forbidden". 2318 5.9.2.5. 4.04 Not Found 2320 Like HTTP 404 "Not Found". 2322 5.9.2.6. 4.05 Method Not Allowed 2324 Like HTTP 405 "Method Not Allowed", but with no parallel to the 2325 "Allow" header field. 2327 5.9.2.7. 4.06 Not Acceptable 2329 Like HTTP 406 "Not Acceptable", but with no response entity. 2331 5.9.2.8. 4.12 Precondition Failed 2333 Like HTTP 412 "Precondition Failed". 2335 5.9.2.9. 4.13 Request Entity Too Large 2337 Like HTTP 413 "Request Entity Too Large". 2339 The response SHOULD include a Size1 Option (Section 5.10.9) to 2340 indicate the maximum size of request entity the server is able and 2341 willing to handle, unless the server is not in a position to make 2342 this information available. 2344 5.9.2.10. 4.15 Unsupported Content-Format 2346 Like HTTP 415 "Unsupported Media Type". 2348 5.9.3. Server Error 5.xx 2350 This class of response code indicates cases in which the server is 2351 aware that it has erred or is incapable of performing the request. 2352 These response codes are applicable to any request method. 2354 The server SHOULD include a diagnostic payload under the conditions 2355 detailed in Section 5.5.2. 2357 Responses of this class are cacheable: Caches can use the Max-Age 2358 Option to determine freshness (see Section 5.6.1). They cannot be 2359 validated. 2361 5.9.3.1. 5.00 Internal Server Error 2363 Like HTTP 500 "Internal Server Error". 2365 5.9.3.2. 5.01 Not Implemented 2367 Like HTTP 501 "Not Implemented". 2369 5.9.3.3. 5.02 Bad Gateway 2371 Like HTTP 502 "Bad Gateway". 2373 5.9.3.4. 5.03 Service Unavailable 2374 Like HTTP 503 "Service Unavailable", but using the Max-Age Option in 2375 place of the "Retry-After" header field to indicate the number of 2376 seconds after which to retry. 2378 5.9.3.5. 5.04 Gateway Timeout 2380 Like HTTP 504 "Gateway Timeout". 2382 5.9.3.6. 5.05 Proxying Not Supported 2384 The server is unable or unwilling to act as a forward-proxy for the 2385 URI specified in the Proxy-Uri Option or using Proxy-Scheme (see 2386 Section 5.10.2). 2388 5.10. Option Definitions 2390 The individual CoAP options are summarized in Table 4 and explained 2391 in the subsections of this section. 2393 In this table, the C, U, and N columns indicate the properties, 2394 Critical, UnSafe, and NoCacheKey, respectively. Since NoCacheKey 2395 only has a meaning for options that are Safe-to-Forward (not marked 2396 Unsafe), the column is filled with a dash for UnSafe options. (The 2397 present specification does not define any NoCacheKey options, but the 2398 format of the table is intended to be useful for additional 2399 specifications.) 2401 +-----+----+---+---+---+----------------+--------+--------+---------+ 2402 | No. | C | U | N | R | Name | Format | Length | Default | 2403 +-----+----+---+---+---+----------------+--------+--------+---------+ 2404 | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | 2405 | 3 | x | x | - | | Uri-Host | string | 1-255 | (see | 2406 | | | | | | | | | below) | 2407 | 4 | | | | x | ETag | opaque | 1-8 | (none) | 2408 | 5 | x | | | | If-None-Match | empty | 0 | (none) | 2409 | 7 | x | x | - | | Uri-Port | uint | 0-2 | (see | 2410 | | | | | | | | | below) | 2411 | 8 | | | | x | Location-Path | string | 0-255 | (none) | 2412 | 11 | x | x | - | x | Uri-Path | string | 0-255 | (none) | 2413 | 12 | | | | | Content-Format | uint | 0-2 | (none) | 2414 | 14 | | x | - | | Max-Age | uint | 0-4 | 60 | 2415 | 15 | x | x | - | x | Uri-Query | string | 0-255 | (none) | 2416 | 17 | x | | | | Accept | uint | 0-2 | (none) | 2417 | 20 | | | | x | Location-Query | string | 0-255 | (none) | 2418 | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | (none) | 2419 | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | (none) | 2420 | 60 | | | x | | Size1 | uint | 0-4 | (none) | 2421 +-----+----+---+---+---+----------------+--------+--------+---------+ 2422 C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable 2424 Table 4: Options 2426 5.10.1. Uri-Host, Uri-Port, Uri-Path and Uri-Query 2428 The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to 2429 specify the target resource of a request to a CoAP origin server. 2430 The options encode the different components of the request URI in a 2431 way that no percent-encoding is visible in the option values and that 2432 the full URI can be reconstructed at any involved endpoint. The 2433 syntax of CoAP URIs is defined in Section 6. 2435 The steps for parsing URIs into options is defined in Section 6.4. 2436 These steps result in zero or more Uri-Host, Uri-Port, Uri-Path and 2437 Uri-Query Options being included in a request, where each option 2438 holds the following values: 2440 o the Uri-Host Option specifies the Internet host of the resource 2441 being requested, 2443 o the Uri-Port Option specifies the transport layer port number of 2444 the resource, 2446 o each Uri-Path Option specifies one segment of the absolute path to 2447 the resource, and 2449 o each Uri-Query Option specifies one argument parameterizing the 2450 resource. 2452 Note: Fragments ([RFC3986], Section 3.5) are not part of the request 2453 URI and thus will not be transmitted in a CoAP request. 2455 The default value of the Uri-Host Option is the IP literal 2456 representing the destination IP address of the request message. 2457 Likewise, the default value of the Uri-Port Option is the destination 2458 UDP port. The default values for the Uri-Host and Uri-Port Options 2459 are sufficient for requests to most servers. Explicit Uri-Host and 2460 Uri-Port Options are typically used when an endpoint hosts multiple 2461 virtual servers. 2463 The Uri-Path and Uri-Query Option can contain any character sequence. 2464 No percent-encoding is performed. The value of a Uri-Path Option 2465 MUST NOT be "." or ".." (as the request URI must be resolved before 2466 parsing it into options). 2468 The steps for constructing the request URI from the options are 2469 defined in Section 6.5. Note that an implementation does not 2470 necessarily have to construct the URI; it can simply look up the 2471 target resource by looking at the individual options. 2473 Examples can be found in Appendix B. 2475 5.10.2. Proxy-Uri and Proxy-Scheme 2477 The Proxy-Uri Option is used to make a request to a forward-proxy 2478 (see Section 5.7). The forward-proxy is requested to forward the 2479 request or service it from a valid cache, and return the response. 2481 The option value is an absolute-URI ([RFC3986], Section 4.3). 2483 Note that the forward-proxy MAY forward the request on to another 2484 proxy or directly to the server specified by the absolute-URI. In 2485 order to avoid request loops, a proxy MUST be able to recognize all 2486 of its server names, including any aliases, local variations, and the 2487 numeric IP addresses. 2489 An endpoint receiving a request with a Proxy-Uri Option that is 2490 unable or unwilling to act as a forward-proxy for the request MUST 2491 cause the return of a 5.05 (Proxying Not Supported) response. 2493 The Proxy-Uri Option MUST take precedence over any of the Uri-Host, 2494 Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included 2495 at the same time in a request containing the Proxy-Uri Option). 2497 As a special case to simplify many proxy clients, the absolute-URI 2498 can be constructed from the Uri-* options. When a Proxy-Scheme 2499 Option is present, the absolute-URI is constructed as follows: A CoAP 2500 URI is constructed from the Uri-* options as defined in Section 6.5. 2501 In the resulting URI, the initial scheme up to, but not including the 2502 following colon is then replaced by the content of the Proxy-Scheme 2503 Option. Note that this case is only applicable if the components of 2504 the desired URI other than the scheme component actually can be 2505 expressed using Uri-* options; e.g., to represent a URI with a 2506 userinfo component in the authority, only Proxy-Uri can be used. 2508 5.10.3. Content-Format 2510 The Content-Format Option indicates the representation format of the 2511 message payload. The representation format is given as a numeric 2512 content format identifier that is defined in the CoAP Content Format 2513 Registry (Section 12.3). In the absence of the option, no default 2514 value is assumed, i.e. the representation format of any 2515 representation message payload is indeterminate (Section 5.5). 2517 5.10.4. Accept 2519 The CoAP Accept option can be used to indicate which Content-Format 2520 is acceptable to the client. The representation format is given as a 2521 numeric Content-Format identifier that is defined in the CoAP 2522 Content-Format Registry (Section 12.3). If no Accept option is 2523 given, the client does not express a preference (thus no default 2524 value is assumed). The client prefers the representation returned by 2525 the server to be in the Content-Format indicated. The server returns 2526 the preferred Content-Format if available. If the preferred Content- 2527 Format cannot be returned, then a 4.06 "Not Acceptable" MUST be sent 2528 as a response, unless another error code takes precedence for this 2529 response. 2531 5.10.5. Max-Age 2533 The Max-Age Option indicates the maximum time a response may be 2534 cached before it is considered not fresh (see Section 5.6.1). 2536 The option value is an integer number of seconds between 0 and 2537 2**32-1 inclusive (about 136.1 years). A default value of 60 seconds 2538 is assumed in the absence of the option in a response. 2540 The value is intended to be current at the time of transmission. 2541 Servers that provide resources with strict tolerances on the value of 2542 Max-Age SHOULD update the value before each retransmission. (See 2543 also Section 5.7.1.) 2545 5.10.6. ETag 2547 An entity-tag is intended for use as a resource-local identifier for 2548 differentiating between representations of the same resource that 2549 vary over time. It is generated by the server providing the 2550 resource, which may generate it in any number of ways including a 2551 version, checksum, hash or time. An endpoint receiving an entity-tag 2552 MUST treat it as opaque and make no assumptions about its content or 2553 structure. (Endpoints that generate an entity-tag are encouraged to 2554 use the most compact representation possible, in particular in 2555 regards to clients and intermediaries that may want to store multiple 2556 ETag values.) 2558 5.10.6.1. ETag as a Response Option 2560 The ETag Option in a response provides the current value (i.e., after 2561 the request was processed) of the entity-tag for the "tagged 2562 representation". If no Location-* options are present, the tagged 2563 representation is the selected representation (Section 5.5.3) of the 2564 target resource. If one or more Location-* options are present and 2565 thus a location URI is indicated (Section 5.10.7), the tagged 2566 representation is the representation that would be retrieved by a GET 2567 request to the location URI. 2569 An ETag response option can be included with any response for which 2570 there is a tagged representation (e.g., it would not be meaningful in 2571 a 4.04 or 4.00 response). The ETag Option MUST NOT occur more than 2572 once in a response. 2574 There is no default value for the ETag Option; if it is not present 2575 in a response, the server makes no statement about the entity-tag for 2576 the tagged representation. 2578 5.10.6.2. ETag as a Request Option 2580 In a GET request, an endpoint that has one or more representations 2581 previously obtained from the resource, and has obtained ETag response 2582 options with these, can specify an instance of the ETag Option for 2583 one or more of these stored responses. 2585 A server can issue a 2.03 Valid response (Section 5.9.1.3) in place 2586 of a 2.05 Content response if one of the ETags given is the entity- 2587 tag for the current representation, i.e. is valid; the 2.03 Valid 2588 response then echoes this specific ETag in a response option. 2590 In effect, a client can determine if any of the stored 2591 representations is current (see Section 5.6.2) without needing to 2592 transfer them again. 2594 The ETag Option MAY occur zero, one or more times in a request. 2596 5.10.7. Location-Path and Location-Query 2598 The Location-Path and Location-Query Options together indicate a 2599 relative URI that consists either of an absolute path, a query string 2600 or both. A combination of these options is included in a 2.01 2601 (Created) response to indicate the location of the resource created 2602 as the result of a POST request (see Section 5.8.2). The location is 2603 resolved relative to the request URI. 2605 If a response with one or more Location-Path and/or Location-Query 2606 Options passes through a cache that interprets these options and the 2607 implied URI identifies one or more currently stored responses, those 2608 entries MUST be marked as not fresh. 2610 Each Location-Path Option specifies one segment of the absolute path 2611 to the resource, and each Location-Query Option specifies one 2612 argument parameterizing the resource. The Location-Path and 2613 Location-Query Option can contain any character sequence. No 2614 percent-encoding is performed. The value of a Location-Path Option 2615 MUST NOT be "." or "..". 2617 The steps for constructing the location URI from the options are 2618 analogous to Section 6.5, except that the first five steps are 2619 skipped and the result is a relative URI-reference, which is then 2620 interpreted relative to the request URI. Note that the relative URI- 2621 reference constructed this way always includes an absolute-path 2622 (e.g., leaving out Location-Path but supplying Location-Query means 2623 the path component in the URI is "/"). 2625 The options that are used to compute the relative URI-reference are 2626 collectively called Location-* options. Beyond Location-Path and 2627 Location-Query, more Location-* options may be defined in the future, 2628 and have been reserved option numbers 128, 132, 136, and 140. If any 2629 of these reserved option numbers occurs in addition to Location-Path 2630 and/or Location-Query and are not supported, then a 4.02 (Bad Option) 2631 error MUST be returned. 2633 5.10.8. Conditional Request Options 2635 Conditional request options enable a client to ask the server to 2636 perform the request only if certain conditions specified by the 2637 option are fulfilled. 2639 For each of these options, if the condition given is not fulfilled, 2640 then the server MUST NOT perform the requested method. Instead, the 2641 server MUST respond with the 4.12 (Precondition Failed) response 2642 code. 2644 If the condition is fulfilled, the server performs the request method 2645 as if the conditional request options were not present. 2647 If the request would, without the conditional request options, result 2648 in anything other than a 2.xx or 4.12 response code, then any 2649 conditional request options MAY be ignored. 2651 5.10.8.1. If-Match 2653 The If-Match Option MAY be used to make a request conditional on the 2654 current existence or value of an ETag for one or more representations 2655 of the target resource. If-Match is generally useful for resource 2656 update requests, such as PUT requests, as a means for protecting 2657 against accidental overwrites when multiple clients are acting in 2658 parallel on the same resource (i.e., the "lost update" problem). 2660 The value of an If-Match option is either an ETag or the empty 2661 string. An If-Match option with an ETag matches a representation 2662 with that exact ETag. An If-Match option with an empty value matches 2663 any existing representation (i.e., it places the precondition on the 2664 existence of any current representation for the target resource). 2666 The If-Match Option can occur multiple times. If any of the options 2667 match, then the condition is fulfilled. 2669 If there is one or more If-Match Option, but none of the options 2670 match, then the condition is not fulfilled. 2672 5.10.8.2. If-None-Match 2674 The If-None-Match Option MAY be used to make a request conditional on 2675 the non-existence of the target resource. If-None-Match is useful 2676 for resource creation requests, such as PUT requests, as a means for 2677 protecting against accidental overwrites when multiple clients are 2678 acting in parallel on the same resource. The If-None-Match Option 2679 carries no value. 2681 If the target resource does exist, then the condition is not 2682 fulfilled. 2684 (It is not very useful to combine If-Match and If-None-Match options 2685 in one request, because the condition will then never be fulfilled.) 2687 5.10.9. Size1 Option 2689 The Size1 option provides size information about the resource 2690 representation in a request. The option value is an integer number 2691 of bytes. Its main use is with block-wise transfers 2692 [I-D.ietf-core-block]. In the present specification, it is used in 2693 4.13 responses (Section 5.9.2.9) to indicate the maximum size of 2694 request entity that the server is able and willing to handle. 2696 6. CoAP URIs 2697 CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP 2698 resources and providing a means of locating the resource. Resources 2699 are organized hierarchically and governed by a potential CoAP origin 2700 server listening for CoAP requests ("coap") or DTLS-secured CoAP 2701 requests ("coaps") on a given UDP port. The CoAP server is 2702 identified via the generic syntax's authority component, which 2703 includes a host component and optional UDP port number. The 2704 remainder of the URI is considered to be identifying a resource which 2705 can be operated on by the methods defined by the CoAP protocol. The 2706 "coap" and "coaps" URI schemes can thus be compared to the "http" and 2707 "https" URI schemes respectively. 2709 The syntax of the "coap" and "coaps" URI schemes is specified in this 2710 section in Augmented Backus-Naur Form (ABNF) [RFC5234]. The 2711 definitions of "host", "port", "path-abempty", "query", "segment", 2712 "IP-literal", "IPv4address" and "reg-name" are adopted from 2713 [RFC3986]. 2715 Implementation Note: Unfortunately, over time the URI format has 2716 acquired significant complexity. Implementers are encouraged to 2717 examine [RFC3986] closely. E.g., the ABNF for IPv6 addresses is 2718 more complicated than maybe expected. Also, implementers should 2719 take care to perform the processing of percent decoding/encoding 2720 exactly once on the way from a URI to its decoded components or 2721 back. Percent encoding is crucial for data transparency, but may 2722 lead to unusual results such as a slash in a path component. 2724 6.1. coap URI Scheme 2726 coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] 2728 If the host component is provided as an IP-literal or IPv4address, 2729 then the CoAP server can be reached at that IP address. If host is a 2730 registered name, then that name is considered an indirect identifier 2731 and the endpoint might use a name resolution service, such as DNS, to 2732 find the address of that host. The host MUST NOT be empty; if a URI 2733 is received with a missing authority or an empty host, then it MUST 2734 be considered invalid. The port subcomponent indicates the UDP port 2735 at which the CoAP server is located. If it is empty or not given, 2736 then the default port 5683 is assumed. 2738 The path identifies a resource within the scope of the host and port. 2739 It consists of a sequence of path segments separated by a slash 2740 character (U+002F SOLIDUS "/"). 2742 The query serves to further parameterize the resource. It consists 2743 of a sequence of arguments separated by an ampersand character 2744 (U+0026 AMPERSAND "&"). An argument is often in the form of a 2745 "key=value" pair. 2747 The "coap" URI scheme supports the path prefix "/.well-known/" 2748 defined by [RFC5785] for "well-known locations" in the name-space of 2749 a host. This enables discovery of policy or other information about 2750 a host ("site-wide metadata"), such as hosted resources (see 2751 Section 7). 2753 Application designers are encouraged to make use of short, but 2754 descriptive URIs. As the environments that CoAP is used in are 2755 usually constrained for bandwidth and energy, the trade-off between 2756 these two qualities should lean towards the shortness, without 2757 ignoring descriptiveness. 2759 6.2. coaps URI Scheme 2761 coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty 2762 [ "?" query ] 2764 All of the requirements listed above for the "coap" scheme are also 2765 requirements for the "coaps" scheme, except that a default UDP port 2766 of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or 2767 not given, and the UDP datagrams MUST be secured through the use of 2768 DTLS as described in Section 9.1. 2770 Considerations for caching of responses to "coaps" identified 2771 requests are discussed in Section 11.2. 2773 Resources made available via the "coaps" scheme have no shared 2774 identity with the "coap" scheme even if their resource identifiers 2775 indicate the same authority (the same host listening to the same UDP 2776 port). They are distinct name spaces and are considered to be 2777 distinct origin servers. 2779 6.3. Normalization and Comparison Rules 2781 Since the "coap" and "coaps" schemes conform to the URI generic 2782 syntax, such URIs are normalized and compared according to the 2783 algorithm defined in [RFC3986], Section 6, using the defaults 2784 described above for each scheme. 2786 If the port is equal to the default port for a scheme, the normal 2787 form is to elide the port subcomponent. Likewise, an empty path 2788 component is equivalent to an absolute path of "/", so the normal 2789 form is to provide a path of "/" instead. The scheme and host are 2790 case-insensitive and normally provided in lowercase; IP-literals are 2791 in recommended form [RFC5952]; all other components are compared in a 2792 case-sensitive manner. Characters other than those in the "reserved" 2793 set are equivalent to their percent-encoded bytes (see [RFC3986], 2794 Section 2.1): the normal form is to not encode them. 2796 For example, the following three URIs are equivalent, and cause the 2797 same options and option values to appear in the CoAP messages: 2799 coap://example.com:5683/~sensors/temp.xml 2800 coap://EXAMPLE.com/%7Esensors/temp.xml 2801 coap://EXAMPLE.com:/%7esensors/temp.xml 2803 6.4. Decomposing URIs into Options 2805 The steps to parse a request's options from a string |url| are as 2806 follows. These steps either result in zero or more of the Uri-Host, 2807 Uri-Port, Uri-Path and Uri-Query Options being included in the 2808 request, or they fail. 2810 1. If the |url| string is not an absolute URI ([RFC3986]), then fail 2811 this algorithm. 2813 2. Resolve the |url| string using the process of reference 2814 resolution defined by [RFC3986]. At this stage the URL is in 2815 ASCII encoding [RFC0020], even though the decoded components will 2816 be interpreted in UTF-8 [RFC3629] after step 5, 8 and 9. 2818 NOTE: It doesn't matter what it is resolved relative to, since we 2819 already know it is an absolute URL at this point. 2821 3. If |url| does not have a component whose value, when 2822 converted to ASCII lowercase, is "coap" or "coaps", then fail 2823 this algorithm. 2825 4. If |url| has a component, then fail this algorithm. 2827 5. If the component of |url| does not represent the request's 2828 destination IP address as an IP-literal or IPv4address, include a 2829 Uri-Host Option and let that option's value be the value of the 2830 component of |url|, converted to ASCII lowercase, and then 2831 converting all percent-encodings ("%" followed by two hexadecimal 2832 digits) to the corresponding characters. 2834 NOTE: In the usual case where the request's destination IP 2835 address is derived from the host part, this ensures that a Uri- 2836 Host Option is only used for a component of the form reg- 2837 name. 2839 6. If |url| has a component, then let |port| be that 2840 component's value interpreted as a decimal integer; otherwise, 2841 let |port| be the default port for the scheme. 2843 7. If |port| does not equal the request's destination UDP port, 2844 include a Uri-Port Option and let that option's value be |port|. 2846 8. If the value of the component of |url| is empty or 2847 consists of a single slash character (U+002F SOLIDUS "/"), then 2848 move to the next step. 2850 Otherwise, for each segment in the component, include a 2851 Uri-Path Option and let that option's value be the segment (not 2852 including the delimiting slash characters) after converting each 2853 percent-encoding ("%" followed by two hexadecimal digits) to the 2854 corresponding byte. 2856 9. If |url| has a component, then, for each argument in the 2857 component, include a Uri-Query Option and let that 2858 option's value be the argument (not including the question mark 2859 and the delimiting ampersand characters) after converting each 2860 percent-encoding to the corresponding byte. 2862 Note that these rules completely resolve any percent-encoding. 2864 6.5. Composing URIs from Options 2866 The steps to construct a URI from a request's options are as follows. 2867 These steps either result in a URI, or they fail. In these steps, 2868 percent-encoding a character means replacing each of its (UTF-8 2869 encoded) bytes by a "%" character followed by two hexadecimal digits 2870 representing the byte, where the digits A-F are in upper case (as 2871 defined in [RFC3986] Section 2.1; to reduce variability, the 2872 hexadecimal notation for percent-encoding in CoAP URIs MUST use 2873 uppercase letters). The definitions of "unreserved" and "sub-delims" 2874 are adopted from [RFC3986]. 2876 1. If the request is secured using DTLS, let |url| be the string 2877 "coaps://". Otherwise, let |url| be the string "coap://". 2879 2. If the request includes a Uri-Host Option, let |host| be that 2880 option's value, where any non-ASCII characters are replaced by 2881 their corresponding percent-encoding. If |host| is not a valid 2882 reg-name or IP-literal or IPv4address, fail the algorithm. If 2883 the request does not include a Uri-Host Option, let |host| be 2884 the IP-literal (making use of the conventions of [RFC5952]) or 2885 IPv4address representing the request's destination IP address. 2887 3. Append |host| to |url|. 2889 4. If the request includes a Uri-Port Option, let |port| be that 2890 option's value. Otherwise, let |port| be the request's 2891 destination UDP port. 2893 5. If |port| is not the default port for the scheme, then append a 2894 single U+003A COLON character (:) followed by the decimal 2895 representation of |port| to |url|. 2897 6. Let |resource name| be the empty string. For each Uri-Path 2898 Option in the request, append a single character U+002F SOLIDUS 2899 (/) followed by the option's value to |resource name|, after 2900 converting any character that is not either in the "unreserved" 2901 set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL 2902 AT (@) character, to its percent-encoded form. 2904 7. If |resource name| is the empty string, set it to a single 2905 character U+002F SOLIDUS (/). 2907 8. For each Uri-Query Option in the request, append a single 2908 character U+003F QUESTION MARK (?) (first option) or U+0026 2909 AMPERSAND (&) (subsequent options) followed by the option's 2910 value to |resource name|, after converting any character that is 2911 not either in the "unreserved" set, "sub-delims" set (except 2912 U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT 2913 (@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, 2914 to its percent-encoded form. 2916 9. Append |resource name| to |url|. 2918 10. Return |url|. 2920 Note that these steps have been designed to lead to a URI in normal 2921 form (see Section 6.3). 2923 7. Discovery 2925 7.1. Service Discovery 2927 As a part of discovering the services offered by a CoAP server, a 2928 client has to learn about the endpoint used by a server. 2930 A server is discovered by a client by the client (knowing or) 2931 learning a URI that references a resource in the namespace of the 2932 server. Alternatively, clients can use Multicast CoAP (see 2933 Section 8) and the "All CoAP Nodes" multicast address to find CoAP 2934 servers. 2936 Unless the port subcomponent in a "coap" or "coaps" URI indicates the 2937 UDP port at which the CoAP server is located, the server is assumed 2938 to be reachable at the default port. 2940 The CoAP default port number 5683 MUST be supported by a server that 2941 offers resources for resource discovery (see Section 7.2 below) and 2942 SHOULD be supported for providing access to other resources. The 2943 default port number [IANA_TBD_PORT] for DTLS-secured CoAP MAY be 2944 supported by a server for resource discovery and for providing access 2945 to other resources. In addition other endpoints may be hosted at 2946 other ports, e.g. in the dynamic port space. 2948 Implementation Note: When a CoAP server is hosted by a 6LoWPAN node, 2949 header compression efficiency is improved when it also supports a 2950 port number in the 61616-61631 compressed UDP port space defined 2951 in [RFC4944] (note that, as its UDP port differs from the default 2952 port, it is a different endpoint from the server at the default 2953 port). 2955 7.2. Resource Discovery 2957 The discovery of resources offered by a CoAP endpoint is extremely 2958 important in machine-to-machine applications where there are no 2959 humans in the loop and static interfaces result in fragility. To 2960 maximize interoperability in a CoRE environment, a CoAP endpoint 2961 SHOULD support the CoRE Link Format of discoverable resources as 2962 described in [RFC6690], except where fully manual configuration is 2963 desired. It is up to the server which resources are made 2964 discoverable (if any). 2966 7.2.1. 'ct' Attribute 2968 This section defines a new Web Linking [RFC5988] attribute for use 2969 with [RFC6690]. The Content-Format code "ct" attribute provides a 2970 hint about the Content-Formats this resource returns. Note that this 2971 is only a hint, and does not override the Content-Format Option of a 2972 CoAP response obtained by actually requesting the representation of 2973 the resource. The value is in the CoAP identifier code format as a 2974 decimal ASCII integer and MUST be in the range of 0-65535 (16-bit 2975 unsigned integer). For example application/xml would be indicated as 2976 "ct=41". If no Content-Format code attribute is present then nothing 2977 about the type can be assumed. The Content-Format code attribute MAY 2978 include a space-separated sequence of Content-Format codes, 2979 indicating that multiple content-formats are available. The syntax 2980 of the attribute value is summarized in the production ct-value in 2981 Figure 12, where cardinal, SP and DQUOTE are defined as in [RFC6690]. 2983 ct-value = cardinal 2984 / DQUOTE cardinal *( 1*SP cardinal ) DQUOTE 2986 Figure 12 2988 8. Multicast CoAP 2990 CoAP supports making requests to a IP multicast group. This is 2991 defined by a series of deltas to Unicast CoAP. A more general 2992 discussion of group communication with CoAP is in 2993 [I-D.ietf-core-groupcomm]. 2995 CoAP endpoints that offer services that they want other endpoints to 2996 be able to find using multicast service discovery, join one or more 2997 of the appropriate all-CoAP-nodes multicast addresses (Section 12.8) 2998 and listen on the default CoAP port. Note that an endpoint might 2999 receive multicast requests on other multicast addresses, including 3000 the all-nodes IPv6 address (or via broadcast on IPv4); an endpoint 3001 MUST therefore be prepared to receive such messages but MAY ignore 3002 them if multicast service discovery is not desired. 3004 8.1. Messaging Layer 3006 A multicast request is characterized by being transported in a CoAP 3007 message that is addressed to an IP multicast address instead of a 3008 CoAP endpoint. Such multicast requests MUST be Non-confirmable. 3010 A server SHOULD be aware that a request arrived via multicast, e.g. 3011 by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 3012 available. 3014 To avoid an implosion of error responses, when a server is aware that 3015 a request arrived via multicast, it MUST NOT return a RST in reply to 3016 NON. If it is not aware, it MAY return a RST in reply to NON as 3017 usual. Because such a Reset message will look identical to an RST 3018 for a unicast message from the sender, the sender MUST avoid using a 3019 Message ID that is also still active from this endpoint with any 3020 unicast endpoint that might receive the multicast message. 3022 At the time of writing, multicast messages can only be carried in 3023 UDP, not in DTLS. This means that the security modes defined for 3024 CoAP in this document are not applicable to multicast. 3026 8.2. Request/Response Layer 3028 When a server is aware that a request arrived via multicast, the 3029 server MAY always ignore the request, in particular if it doesn't 3030 have anything useful to respond (e.g., if it only has an empty 3031 payload or an error response). The decision for this may depend on 3032 the application. (For example, in [RFC6690] query filtering, a 3033 server should not respond to a multicast request if the filter does 3034 not match. More examples are in [I-D.ietf-core-groupcomm].) 3036 If a server does decide to respond to a multicast request, it should 3037 not respond immediately. Instead, it should pick a duration for the 3038 period of time during which it intends to respond. For purposes of 3039 this exposition, we call the length of this period the Leisure. The 3040 specific value of this Leisure may depend on the application, or MAY 3041 be derived as described below. The server SHOULD then pick a random 3042 point of time within the chosen Leisure period to send back the 3043 unicast response to the multicast request. If further responses need 3044 to be sent based on the same multicast address membership, a new 3045 leisure period starts at the earliest after the previous one 3046 finishes. 3048 To compute a value for Leisure, the server should have a group size 3049 estimate G, a target data transfer rate R (which both should be 3050 chosen conservatively) and an estimated response size S; a rough 3051 lower bound for Leisure can then be computed as 3053 lb_Leisure = S * G / R 3055 E.g., for a multicast request with link-local scope on an 2.4 GHz 3056 IEEE 802.15.4 (6LoWPAN) network, G could be (relatively 3057 conservatively) set to 100, S to 100 bytes, and the target rate to 8 3058 kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10 3059 seconds. 3061 If a CoAP endpoint does not have suitable data to compute a value for 3062 Leisure, it MAY resort to DEFAULT_LEISURE. 3064 When matching a response to a multicast request, only the token MUST 3065 match; the source endpoint of the response does not need to (and will 3066 not) be the same as the destination endpoint of the original request. 3068 For the purposes of interpreting the Location-* options and any links 3069 embedded in the representation and, the request URI (base URI) 3070 relative to which the response is interpreted, is formed by replacing 3071 the multicast address in the Host component of the original request 3072 URI by the literal IP address of the endpoint actually responding. 3074 8.2.1. Caching 3076 When a client makes a multicast request, it always makes a new 3077 request to the multicast group (since there may be new group members 3078 that joined meanwhile or ones that did not get the previous request). 3079 It MAY update a cache with the received responses. Then it uses both 3080 cached-still-fresh and 'new' responses as the result of the request. 3082 A response received in reply to a GET request to a multicast group 3083 MAY be used to satisfy a subsequent request on the related unicast 3084 request URI. The unicast request URI is obtained by replacing the 3085 authority part of the request URI with the transport layer source 3086 address of the response message. 3088 A cache MAY revalidate a response by making a GET request on the 3089 related unicast request URI. 3091 A GET request to a multicast group MUST NOT contain an ETag option. 3092 A mechanism to suppress responses the client already has is left for 3093 further study. 3095 8.2.2. Proxying 3097 When a forward-proxy receives a request with a Proxy-Uri or URI 3098 constructed from Proxy-Scheme that indicates a multicast address, the 3099 proxy obtains a set of responses as described above and sends all 3100 responses (both cached-still-fresh and new) back to the original 3101 client. 3103 This specification does not provide a way to indicate the unicast- 3104 modified request URI (base URI) in responses thus forwarded. 3105 Proxying multicast requests is discussed in more detail in 3106 [I-D.ietf-core-groupcomm]; one proposal to address the base URI issue 3107 can be found in section 3 of [I-D.bormann-coap-misc]. 3109 9. Securing CoAP 3111 This section defines the DTLS binding for CoAP. 3113 During the provisioning phase, a CoAP device is provided with the 3114 security information that it needs, including keying materials and 3115 access control lists. This specification defines provisioning for 3116 the RawPublicKey mode in Section 9.1.3.2.1. At the end of the 3117 provisioning phase, the device will be in one of four security modes 3118 with the following information for the given mode. The NoSec and 3119 RawPublicKey modes are mandatory to implement for this specification. 3121 NoSec: There is no protocol level security (DTLS is disabled). 3122 Alternative techniques to provide lower layer security SHOULD be 3123 used when appropriate. The use of IPsec is discussed in 3124 [I-D.bormann-core-ipsec-for-coap]. Certain link layers in use 3125 with constrained nodes also provide link layer security, which may 3126 be appropriate with proper key management. 3128 PreSharedKey: DTLS is enabled and there is a list of pre-shared keys 3129 [RFC4279] and each key includes a list of which nodes it can be 3130 used to communicate with as described in Section 9.1.3.1. At the 3131 extreme there may be one key for each node this CoAP node needs to 3132 communicate with (1:1 node/key ratio). Conversely, if more than 3133 two entities share a specific pre-shared key, this key only 3134 enables the entities to authenticate as a member of that group and 3135 not as a specific peer. 3137 RawPublicKey: DTLS is enabled and the device has an asymmetric key 3138 pair without a certificate (a raw public key) that is validated 3139 using an out-of-band mechanism [I-D.ietf-tls-oob-pubkey] as 3140 described in Section 9.1.3.2. The device also has an identity 3141 calculated from the public key and a list of identities of the 3142 nodes it can communicate with. 3144 Certificate: DTLS is enabled and the device has an asymmetric key 3145 pair with an X.509 certificate [RFC5280] that binds it to its 3146 Authority Name and is signed by some common trust root as 3147 described in Section 9.1.3.3. The device also has a list of root 3148 trust anchors that can be used for validating a certificate. 3150 In the "NoSec" mode, the system simply sends the packets over normal 3151 UDP over IP and is indicated by the "coap" scheme and the CoAP 3152 default port. The system is secured only by keeping attackers from 3153 being able to send or receive packets from the network with the CoAP 3154 nodes; see Section 11.5 for an additional complication with this 3155 approach. 3157 The other three security modes are achieved using DTLS and are 3158 indicated by the "coaps" scheme and DTLS-secured CoAP default port. 3159 The result is a security association that can be used to authenticate 3160 (within the limits of the security model) and, based on this 3161 authentication, authorize the communication partner. CoAP itself 3162 does not provide protocol primitives for authentication or 3163 authorization; where this is required, it can either be provided by 3164 communication security (i.e., IPsec or DTLS) or by object security 3165 (within the payload). Devices that require authorization for certain 3166 operations are expected to require one of these two forms of 3167 security. Necessarily, where an intermediary is involved, 3168 communication security only works when that intermediary is part of 3169 the trust relationships; CoAP does not provide a way to forward 3170 different levels of authorization that clients may have with an 3171 intermediary to further intermediaries or origin servers -- it 3172 therefore may be required to perform all authorization at the first 3173 intermediary. 3175 9.1. DTLS-secured CoAP 3177 Just as HTTP is secured using Transport Layer Security (TLS) over 3178 TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP 3179 (see Figure 13). This section defines the CoAP binding to DTLS, 3180 along with the minimal mandatory-to-implement configurations 3181 appropriate for constrained environments. The binding is defined by 3182 a series of deltas to Unicast CoAP. DTLS is in practice TLS with 3183 added features to deal with the unreliable nature of the UDP 3184 transport. 3186 +----------------------+ 3187 | Application | 3188 +----------------------+ 3189 +----------------------+ 3190 | Requests/Responses | 3191 |----------------------| CoAP 3192 | Messages | 3193 +----------------------+ 3194 +----------------------+ 3195 | DTLS | 3196 +----------------------+ 3197 +----------------------+ 3198 | UDP | 3199 +----------------------+ 3201 Figure 13: Abstract layering of DTLS-secured CoAP 3203 In some constrained nodes (limited flash and/or RAM) and networks 3204 (limited bandwidth or high scalability requirements), and depending 3205 on the specific cipher suites in use, all modes of DTLS may not be 3206 applicable. Some DTLS cipher suites can add significant 3207 implementation complexity as well as some initial handshake overhead 3208 needed when setting up the security association. Once the initial 3209 handshake is completed, DTLS adds a limited per-datagram overhead of 3210 approximately 13 bytes, not including any initialization vectors/ 3211 nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]), 3212 integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 3213 [RFC6655]) and padding required by the cipher suite. Whether and 3214 which mode of using DTLS is applicable for a CoAP-based application 3215 should be carefully weighed considering the specific cipher suites 3216 that may be applicable, and whether the session maintenance makes it 3217 compatible with application flows and sufficient resources are 3218 available on the constrained nodes and for the added network 3219 overhead. (For some modes of using DTLS, this specification 3220 identifies a mandatory to implement cipher suite. This is an 3221 implementation requirement to maximize interoperability in those 3222 cases where these cipher suites are indeed appropriate. The specific 3223 security policies of an application may determine the actual (set of) 3224 cipher suites that can be used.) DTLS is not applicable to group 3225 keying (multicast communication); however, it may be a component in a 3226 future group key management protocol. 3228 9.1.1. Messaging Layer 3230 The endpoint acting as the CoAP client should also act as the DTLS 3231 client. It should initiate a session to the server on the 3232 appropriate port. When the DTLS handshake has finished, the client 3233 may initiate the first CoAP request. All CoAP messages MUST be sent 3234 as DTLS "application data". 3236 The following rules are added for matching an ACK or RST to a CON 3237 message or a RST to a NON message: The DTLS session MUST be the same 3238 and the epoch MUST be the same. 3240 A message is the same when it is sent within the same DTLS session 3241 and same epoch and has the same Message ID. 3243 Note: When a Confirmable message is retransmitted, a new DTLS 3244 sequence_number is used for each attempt, even though the CoAP 3245 Message ID stays the same. So a recipient still has to perform 3246 deduplication as described in Section 4.5. Retransmissions MUST NOT 3247 be performed across epochs. 3249 DTLS connections in RawPublicKey and Certificate mode are set up 3250 using mutual authentication so they can remain up and be reused for 3251 future message exchanges in either direction. Devices can close a 3252 DTLS connection when they need to recover resources but in general 3253 they should keep the connection up for as long as possible. Closing 3254 the DTLS connection after every CoAP message exchange is very 3255 inefficient. 3257 9.1.2. Request/Response Layer 3259 The following rules are added for matching a response to a request: 3260 The DTLS session MUST be the same and the epoch MUST be the same. 3262 This means the response to a DTLS secured request MUST always be DTLS 3263 secured using the same security session and epoch. Any attempt to 3264 supply a NoSec response to a DTLS request simply does not match the 3265 request and (unless it does match an unrelated NoSec request) 3266 therefore MUST be rejected. 3268 9.1.3. Endpoint Identity 3270 Devices SHOULD support the Server Name Indication (SNI) to indicate 3271 their Authority Name in the SNI HostName field as defined in 3272 Section 3 of [RFC6066]. This is needed so that when a host that acts 3273 as a virtual server for multiple Authorities receives a new DTLS 3274 connection, it knows which keys to use for the DTLS session. 3276 9.1.3.1. Pre-Shared Keys 3278 When forming a connection to a new node, the system selects an 3279 appropriate key based on which nodes it is trying to reach and then 3280 forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. 3281 Implementations in these modes MUST support the mandatory to 3282 implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in 3283 [RFC6655]. 3285 Depending on the commissioning model, applications may need to define 3286 an application profile for identity hints as required and detailed in 3287 [RFC4279] (Section 5.2) to enable the use of PSK identity hints. 3289 The security considerations of [RFC4279] (Section 7) apply. In 3290 particular, applications should carefully weigh whether they need 3291 Perfect Forward Secrecy (PFS) or not and select an appropriate cipher 3292 suite (7.1). The entropy of the PSK must be sufficient to mitigate 3293 against brute-force and (where the PSK is not chosen randomly but by 3294 a human) dictionary attacks (7.2). The cleartext communication of 3295 client identities may leak data or compromise privacy (7.3). 3297 9.1.3.2. Raw Public Key Certificates 3299 In this mode the device has an asymmetric key pair but without an 3300 X.509 certificate (called a raw public key); e.g., the asymmetric key 3301 pair is generated by the manufacturer and installed on the device 3302 (see also Section 11.6). A device MAY be configured with multiple 3303 raw public keys. The type and length of the raw public key depends 3304 on the cipher suite used. Implementations in RawPublicKey mode MUST 3305 support the mandatory to implement cipher suite 3306 TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in 3307 [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. The key used 3308 MUST be ECDSA-capable. The curve secp256r1 MUST be supported 3309 [RFC4492]; this curve is equivalent to the NIST P-256 curve. The 3310 hash algorithm is SHA-256. Implementations MUST use the Supported 3311 Elliptic Curves Extension and Supported Point Format extensions 3312 [RFC4492]; the uncompressed point format MUST be supported; [RFC6090] 3313 can be used as an implementation method. Some guidance relevant to 3314 the implementation of this cipher suite can be found in [W3CXMLSEC]. 3315 The mechanism for using raw public keys with TLS is specified in 3316 [I-D.ietf-tls-oob-pubkey]. 3318 Implementation Note: Specifically, this means the extensions listed 3319 in Figure 14 with at least the values listed will be present in 3320 the DTLS handshake. 3322 Extension: elliptic_curves 3323 Type: elliptic_curves (0x000a) 3324 Length: 4 3325 Elliptic Curves Length: 2 3326 Elliptic curves (1 curve) 3327 Elliptic curve: secp256r1 (0x0017) 3329 Extension: ec_point_formats 3330 Type: ec_point_formats (0x000b) 3331 Length: 2 3332 EC point formats Length: 1 3333 Elliptic curves point formats (1) 3334 EC point format: uncompressed (0) 3336 Extension: signature_algorithms 3337 Type: signature_algorithms (0x000d) 3338 Length: 4 3339 Data (4 bytes): 00 02 04 03 3340 HashAlgorithm: sha256 (4) 3341 SignatureAlgorithm: ecdsa (3) 3343 Figure 14: DTLS extensions present for 3344 TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 3346 9.1.3.2.1. Provisioning 3348 The RawPublicKey mode was designed to be easily provisioned in M2M 3349 deployments. It is assumed that each device has an appropriate 3350 asymmetric public key pair installed. An identifier is calculated by 3351 the endpoint from the public key as described in Section 2 of 3352 [RFC6920]. All implementations that support checking RawPublicKey 3353 identities MUST support at least the sha-256-120 mode (SHA-256 3354 truncated to 120 bits). Implementations SHOULD support also longer 3355 length identifiers and MAY support shorter lengths. Note that the 3356 shorter lengths provide less security against attacks and their use 3357 is NOT RECOMMENDED. 3359 Depending on how identifiers are given to the system that verifies 3360 them, support for URI, binary, and/or human-speakable format 3362 [RFC6920] needs to be implemented. All implementations SHOULD 3363 support the binary mode and implementations that have a user 3364 interface SHOULD also support the human-speakable format. 3366 During provisioning, the identifier of each node is collected, for 3367 example by reading a barcode on the outside of the device or by 3368 obtaining a pre-compiled list of the identifiers. These identifiers 3369 are then installed in the corresponding endpoint, for example an M2M 3370 data collection server. The identifier is used for two purposes, to 3371 associate the endpoint with further device information and to perform 3372 access control. During (initial and ongoing) provisioning, an access 3373 control list of identifiers the device may start DTLS sessions with 3374 SHOULD also be installed and maintained. 3376 9.1.3.3. X.509 Certificates 3378 Implementations in Certificate Mode MUST support the mandatory to 3379 implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as 3380 specified in [I-D.mcgrew-tls-aes-ccm-ecc], [RFC5246], [RFC4492]. 3381 Namely, the certificate includes a SubjectPublicKeyInfo that 3382 indicates an algorithm of id-ecPublicKey with namedCurves secp256r1 3383 [RFC5480]; the public key format is uncompressed [RFC5480]; the hash 3384 algorithm is SHA-256; if included the key usage extension indicates 3385 digitalSignature. Certificates MUST be signed with ECDSA using 3386 secp256r1, and the signature MUST use SHA-256. The key used MUST be 3387 ECDSA-capable. The curve secp256r1 MUST be supported [RFC4492]; this 3388 curve is equivalent to the NIST P-256 curve. The hash algorithm is 3389 SHA-256. Implementations MUST use the Supported Elliptic Curves 3390 Extension and Supported Point Format extensions [RFC4492]; the 3391 uncompressed point format MUST be supported; [RFC6090] can be used as 3392 an implementation method. 3394 The Authority Name in the certificate would be built out of a long 3395 term unique identifier for the device such as the EUI-64 [EUI64]. 3396 The Authority Name could also be based on the FQDN that was used as 3397 the Host part of the CoAP URI. However, the device's IP address 3398 should not typically be used as the Authority name as it would change 3399 over time. The discovery process used in the system would build up 3400 the mapping between IP addresses of the given devices and the 3401 Authority Name for each device. Some devices could have more than 3402 one Authority and would need more than a single certificate. 3404 When a new connection is formed, the certificate from the remote 3405 device needs to be verified. If the CoAP node has a source of 3406 absolute time, then the node SHOULD check that the validity dates of 3407 the certificate are within range. The certificate MUST be validated 3408 as appropriate for the security requirements, using functionality 3409 equivalent to the algorithm specified in [RFC5280] section 6. If the 3410 certificate contains a SubjectAltName, then the Authority Name MUST 3411 match at least one of the authority names of any CoAP URI found in a 3412 field of URI type in the SubjectAltName set. If there is no 3413 SubjectAltName in the certificate, then the Authoritative Name MUST 3414 match the CN found in the certificate using the matching rules 3415 defined in [RFC2818] with the exception that certificates with 3416 wildcards are not allowed. 3418 CoRE support for certificate status checking requires further study. 3419 As a mapping of OCSP [RFC2560] onto CoAP is not currently defined and 3420 OCSP may also not be easily applicable in all environments, an 3421 alternative approach may be using the TLS Certificate Status Request 3422 extension ([RFC6066] section 8, also known as "OCSP stapling") or 3423 preferably the Multiple Certificate Status Extension 3424 ([I-D.ietf-tls-multiple-cert-status-extension]), if available. 3426 If the system has a shared key in addition to the certificate, then a 3427 cipher suite that includes the shared key such as 3428 TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA [RFC5489] SHOULD be used. 3430 10. Cross-Protocol Proxying between CoAP and HTTP 3432 CoAP supports a limited subset of HTTP functionality, and thus cross- 3433 protocol proxying to HTTP is straightforward. There might be several 3434 reasons for proxying between CoAP and HTTP, for example when 3435 designing a web interface for use over either protocol or when 3436 realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied 3437 to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the 3438 definition of these mechanisms is out of scope of this specification. 3440 There are two possible directions to access a resource via a forward- 3441 proxy: 3443 CoAP-HTTP Proxying: Enables CoAP clients to access resources on HTTP 3444 servers through an intermediary. This is initiated by including 3445 the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI 3446 in a CoAP request to a CoAP-HTTP proxy. 3448 HTTP-CoAP Proxying: Enables HTTP clients to access resources on CoAP 3449 servers through an intermediary. This is initiated by specifying 3450 a "coap" or "coaps" URI in the Request-Line of an HTTP request to 3451 an HTTP-CoAP proxy. 3453 Either way, only the Request/Response model of CoAP is mapped to 3454 HTTP. The underlying model of Confirmable or Non-confirmable 3455 messages, etc., is invisible and MUST have no effect on a proxy 3456 function. The following sections describe the handling of requests 3457 to a forward-proxy. Reverse proxies are not specified as the proxy 3458 function is transparent to the client with the proxy acting as if it 3459 was the origin server. However, similar considerations apply to 3460 reverse-proxies as to forward-proxies, and there generally will be an 3461 expectation that reverse-proxies operate in a similar way forward- 3462 proxies would. As an implementation note, HTTP client libraries may 3463 make it hard to operate an HTTP-CoAP forward proxy by not providing a 3464 way to put a CoAP URI on the HTTP Request-Line; reverse-proxying may 3465 therefore lead to wider applicability of a proxy. A separate 3466 specification may define a convention for URIs operating such a HTTP- 3467 CoAP reverse proxy [I-D.castellani-core-http-mapping]. 3469 10.1. CoAP-HTTP Proxying 3471 If a request contains a Proxy-Uri or Proxy-Scheme Option with an 3472 'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint 3473 (called "the proxy" henceforth) is requested to perform the operation 3474 specified by the request method on the indicated HTTP resource and 3475 return the result to the client. (See also Section 5.7 for how the 3476 request to the proxy is formulated, including security requirements.) 3478 This section specifies for any CoAP request the CoAP response that 3479 the proxy should return to the client. How the proxy actually 3480 satisfies the request is an implementation detail, although the 3481 typical case is expected to be the proxy translating and forwarding 3482 the request to an HTTP origin server. 3484 Since HTTP and CoAP share the basic set of request methods, 3485 performing a CoAP request on an HTTP resource is not so different 3486 from performing it on a CoAP resource. The meanings of the 3487 individual CoAP methods when performed on HTTP resources are 3488 explained in the subsections of this section. 3490 If the proxy is unable or unwilling to service a request with an HTTP 3491 URI, a 5.05 (Proxying Not Supported) response is returned to the 3492 client. If the proxy services the request by interacting with a 3493 third party (such as the HTTP origin server) and is unable to obtain 3494 a result within a reasonable time frame, a 5.04 (Gateway Timeout) 3495 response is returned; if a result can be obtained but is not 3496 understood, a 5.02 (Bad Gateway) response is returned. 3498 10.1.1. GET 3500 The GET method requests the proxy to return a representation of the 3501 HTTP resource identified by the request URI. 3503 Upon success, a 2.05 (Content) response code SHOULD be returned. The 3504 payload of the response MUST be a representation of the target HTTP 3505 resource, and the Content-Format Option be set accordingly. The 3506 response MUST indicate a Max-Age value that is no greater than the 3507 remaining time the representation can be considered fresh. If the 3508 HTTP entity has an entity tag, the proxy SHOULD include an ETag 3509 Option in the response and process ETag Options in requests as 3510 described below. 3512 A client can influence the processing of a GET request by including 3513 the following option: 3515 Accept: The request MAY include an Accept Option, identifying the 3516 preferred response content-format. 3518 ETag: The request MAY include one or more ETag Options, identifying 3519 responses that the client has stored. This requests the proxy to 3520 send a 2.03 (Valid) response whenever it would send a 2.05 3521 (Content) response with an entity tag in the requested set 3522 otherwise. Note that CoAP ETags are always strong ETags in the 3523 HTTP sense; CoAP does not have the equivalent of HTTP weak ETags, 3524 and there is no good way to make use of these in a cross-proxy. 3526 10.1.2. PUT 3528 The PUT method requests the proxy to update or create the HTTP 3529 resource identified by the request URI with the enclosed 3530 representation. 3532 If a new resource is created at the request URI, a 2.01 (Created) 3533 response MUST be returned to the client. If an existing resource is 3534 modified, a 2.04 (Changed) response MUST be returned to indicate 3535 successful completion of the request. 3537 10.1.3. DELETE 3539 The DELETE method requests the proxy to delete the HTTP resource 3540 identified by the request URI at the HTTP origin server. 3542 A 2.02 (Deleted) response MUST be returned to client upon success or 3543 if the resource does not exist at the time of the request. 3545 10.1.4. POST 3547 The POST method requests the proxy to have the representation 3548 enclosed in the request be processed by the HTTP origin server. The 3549 actual function performed by the POST method is determined by the 3550 origin server and dependent on the resource identified by the request 3551 URI. 3553 If the action performed by the POST method does not result in a 3554 resource that can be identified by a URI, a 2.04 (Changed) response 3555 MUST be returned to the client. If a resource has been created on 3556 the origin server, a 2.01 (Created) response MUST be returned. 3558 10.2. HTTP-CoAP Proxying 3560 If an HTTP request contains a Request-URI with a 'coap' or 'coaps' 3561 URI, then the receiving HTTP endpoint (called "the proxy" henceforth) 3562 is requested to perform the operation specified by the request method 3563 on the indicated CoAP resource and return the result to the client. 3565 This section specifies for any HTTP request the HTTP response that 3566 the proxy should return to the client. Unless otherwise specified 3567 all the statements made are RECOMMENDED behavior; some highly 3568 constrained implementations may need to resort to shortcuts. How the 3569 proxy actually satisfies the request is an implementation detail, 3570 although the typical case is expected to be the proxy translating and 3571 forwarding the request to a CoAP origin server. The meanings of the 3572 individual HTTP methods when performed on CoAP resources are 3573 explained in the subsections of this section. 3575 If the proxy is unable or unwilling to service a request with a CoAP 3576 URI, a 501 (Not Implemented) response is returned to the client. If 3577 the proxy services the request by interacting with a third party 3578 (such as the CoAP origin server) and is unable to obtain a result 3579 within a reasonable time frame, a 504 (Gateway Timeout) response is 3580 returned; if a result can be obtained but is not understood, a 502 3581 (Bad Gateway) response is returned. 3583 10.2.1. OPTIONS and TRACE 3585 As the OPTIONS and TRACE methods are not supported in CoAP a 501 (Not 3586 Implemented) error MUST be returned to the client. 3588 10.2.2. GET 3590 The GET method requests the proxy to return a representation of the 3591 CoAP resource identified by the Request-URI. 3593 Upon success, a 200 (OK) response is returned. The payload of the 3594 response MUST be a representation of the target CoAP resource, and 3595 the Content-Type and Content-Encoding header fields be set 3596 accordingly. The response MUST indicate a max-age directive that 3597 indicates a value no greater than the remaining time the 3598 representation can be considered fresh. If the CoAP response has an 3599 ETag option, the proxy should include an ETag header field in the 3600 response. 3602 A client can influence the processing of a GET request by including 3603 the following options: 3605 Accept: The most preferred Media-type of the HTTP Accept header 3606 field in a request is mapped to a CoAP Accept option. HTTP Accept 3607 Media-type ranges, parameters and extensions are not supported by 3608 the CoAP Accept option. If the proxy cannot send a response which 3609 is acceptable according to the combined Accept field value, then 3610 the proxy sends a 406 (not acceptable) response. The proxy MAY 3611 then retry the request with further Media-types from the HTTP 3612 Accept header field. 3614 Conditional GETs: Conditional HTTP GET requests that include an "If- 3615 Match" or "If-None-Match" request-header field can be mapped to a 3616 corresponding CoAP request. The "If-Modified-Since" and "If- 3617 Unmodified-Since" request-header fields are not directly supported 3618 by CoAP, but are implemented locally by a caching proxy. 3620 10.2.3. HEAD 3622 The HEAD method is identical to GET except that the server MUST NOT 3623 return a message-body in the response. 3625 Although there is no direct equivalent of HTTP's HEAD method in CoAP, 3626 an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and 3627 the HTTP headers are returned without a message-body. 3629 Implementation Note: An HTTP-CoAP proxy may want to try using a 3630 block-wise transfer [I-D.ietf-core-block] option to minimize the 3631 amount of data actually transferred, but needs to be prepared for 3632 the case that the origin server does not support block-wise 3633 transfers. 3635 10.2.4. POST 3637 The POST method requests the proxy to have the representation 3638 enclosed in the request be processed by the CoAP origin server. The 3639 actual function performed by the POST method is determined by the 3640 origin server and dependent on the resource identified by the request 3641 URI. 3643 If the action performed by the POST method does not result in a 3644 resource that can be identified by a URI, a 200 (OK) or 204 (No 3645 Content) response MUST be returned to the client. If a resource has 3646 been created on the origin server, a 201 (Created) response MUST be 3647 returned. 3649 If any of the Location-* Options are present in the CoAP response, a 3650 Location header field constructed from the values of these options is 3651 returned. 3653 10.2.5. PUT 3655 The PUT method requests the proxy to update or create the CoAP 3656 resource identified by the Request-URI with the enclosed 3657 representation. 3659 If a new resource is created at the Request-URI, a 201 (Created) 3660 response is returned to the client. If an existing resource is 3661 modified, either the 200 (OK) or 204 (No Content) response codes is 3662 sent to indicate successful completion of the request. 3664 10.2.6. DELETE 3666 The DELETE method requests the proxy to delete the CoAP resource 3667 identified by the Request-URI at the CoAP origin server. 3669 A successful response is 200 (OK) if the response includes an entity 3670 describing the status or 204 (No Content) if the action has been 3671 enacted but the response does not include an entity. 3673 10.2.7. CONNECT 3675 This method can not currently be satisfied by an HTTP-CoAP proxy 3676 function as TLS to DTLS tunneling has not yet been specified. For 3677 now, a 501 (Not Implemented) error is returned to the client. 3679 11. Security Considerations 3681 This section analyzes the possible threats to the protocol. It is 3682 meant to inform protocol and application developers about the 3683 security limitations of CoAP as described in this document. As CoAP 3684 realizes a subset of the features in HTTP/1.1, the security 3685 considerations in Section 15 of [RFC2616] are also pertinent to CoAP. 3686 This section concentrates on describing limitations specific to CoAP. 3688 11.1. Protocol Parsing, Processing URIs 3690 A network-facing application can exhibit vulnerabilities in its 3691 processing logic for incoming packets. Complex parsers are well- 3692 known as a likely source of such vulnerabilities, such as the ability 3693 to remotely crash a node, or even remotely execute arbitrary code on 3694 it. CoAP attempts to narrow the opportunities for introducing such 3695 vulnerabilities by reducing parser complexity, by giving the entire 3696 range of encodable values a meaning where possible, and by 3697 aggressively reducing complexity that is often caused by unnecessary 3698 choice between multiple representations that mean the same thing. 3699 Much of the URI processing has been moved to the clients, further 3700 reducing the opportunities for introducing vulnerabilities into the 3701 servers. Even so, the URI processing code in CoAP implementations is 3702 likely to be a large source of remaining vulnerabilities and should 3703 be implemented with special care. CoAP access control 3704 implementations need to ensure they don't introduce vulnerabilities 3705 through discrepancies between the code deriving access control 3706 decisions from a URI and the code finally serving up the resource 3707 addressed by the URI. The most complex parser remaining could be the 3708 one for the CoRE Link Format, although this also has been designed 3709 with a goal of reduced implementation complexity [RFC6690]. (See 3710 also section 15.2 of [RFC2616].) 3712 11.2. Proxying and Caching 3714 As mentioned in 15.7 of [RFC2616], proxies are by their very nature 3715 men-in-the-middle, breaking any IPsec or DTLS protection that a 3716 direct CoAP message exchange might have. They are therefore 3717 interesting targets for breaking confidentiality or integrity of CoAP 3718 message exchanges. As noted in [RFC2616], they are also interesting 3719 targets for breaking availability. 3721 The threat to confidentiality and integrity of request/response data 3722 is amplified where proxies also cache. Note that CoAP does not 3723 define any of the cache-suppressing Cache-Control options that HTTP/ 3724 1.1 provides to better protect sensitive data. 3726 For a caching implementation, any access control considerations that 3727 would apply to making the request that generated the cache entry also 3728 need to be applied to the value in the cache. This is relevant for 3729 clients that implement multiple security domains, as well as for 3730 proxies that may serve multiple clients. Also, a caching proxy MUST 3731 NOT make cached values available to requests that have lesser 3732 transport security properties than to which it would make available 3733 the process of forwarding the request in the first place. 3735 Unlike the "coap" scheme, responses to "coaps" identified requests 3736 are never "public" and thus MUST NOT be reused for shared caching 3737 unless the cache is able to make equivalent access control decisions 3738 to the ones that led to the cached entry. They can, however, be 3739 reused in a private cache if the message is cacheable by default in 3740 CoAP. 3742 Finally, a proxy that fans out Separate Responses (as opposed to 3743 Piggy-backed Responses) to multiple original requesters may provide 3744 additional amplification (see Section 11.3). 3746 11.3. Risk of amplification 3748 CoAP servers generally reply to a request packet with a response 3749 packet. This response packet may be significantly larger than the 3750 request packet. An attacker might use CoAP nodes to turn a small 3751 attack packet into a larger attack packet, an approach known as 3752 amplification. There is therefore a danger that CoAP nodes could 3753 become implicated in denial of service (DoS) attacks by using the 3754 amplifying properties of the protocol: An attacker that is attempting 3755 to overload a victim but is limited in the amount of traffic it can 3756 generate, can use amplification to generate a larger amount of 3757 traffic. 3759 This is particularly a problem in nodes that enable NoSec access, 3760 that are accessible from an attacker and can access potential victims 3761 (e.g. on the general Internet), as the UDP protocol provides no way 3762 to verify the source address given in the request packet. An 3763 attacker need only place the IP address of the victim in the source 3764 address of a suitable request packet to generate a larger packet 3765 directed at the victim. 3767 As a mitigating factor, many constrained networks will only be able 3768 to generate a small amount of traffic, which may make CoAP nodes less 3769 attractive for this attack. However, the limited capacity of the 3770 constrained network makes the network itself a likely victim of an 3771 amplification attack. 3773 Therefore, large amplification factors SHOULD NOT be provided in the 3774 response if the request is not authenticated. A CoAP server can 3775 reduce the amount of amplification it provides to an attacker by 3776 using slicing/blocking modes of CoAP [I-D.ietf-core-block] and 3777 offering large resource representations only in relatively small 3778 slices. E.g., for a 1000 byte resource, a 10-byte request might 3779 result in an 80-byte response (with a 64-byte block) instead of a 3780 1016-byte response, considerably reducing the amplification provided. 3782 CoAP also supports the use of multicast IP addresses in requests, an 3783 important requirement for M2M. Multicast CoAP requests may be the 3784 source of accidental or deliberate denial of service attacks, 3785 especially over constrained networks. This specification attempts to 3786 reduce the amplification effects of multicast requests by limiting 3787 when a response is returned. To limit the possibility of malicious 3788 use, CoAP servers SHOULD NOT accept multicast requests that can not 3789 be authenticated in some way, cryptographically or by some multicast 3790 boundary limiting the potential sources. If possible a CoAP server 3791 SHOULD limit the support for multicast requests to the specific 3792 resources where the feature is required. 3794 On some general purpose operating systems providing a Posix-style 3795 API, it is not straightforward to find out whether a packet received 3796 was addressed to a multicast address. While many implementations 3797 will know whether they have joined a multicast group, this creates a 3798 problem for packets addressed to multicast addresses of the form 3799 FF0x::1, which are received by every IPv6 node. Implementations 3800 SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 3801 available, to make this determination. 3803 11.4. IP Address Spoofing Attacks 3805 Due to the lack of a handshake in UDP, a rogue endpoint which is free 3806 to read and write messages carried by the constrained network (i.e. 3807 NoSec or PreSharedKey deployments with nodes/key ratio > 1:1), may 3808 easily attack a single endpoint, a group of endpoints, as well as the 3809 whole network e.g. by: 3811 1. spoofing RST in response to a CON or NON message, thus making an 3812 endpoint "deaf"; or 3814 2. spoofing an ACK in response to a CON message, thus potentially 3815 preventing the sender of the CON message from retransmitting, and 3816 drowning out the actual response; or 3818 3. spoofing the entire response with forged payload/options (this 3819 has different levels of impact: from single response disruption, 3820 to much bolder attacks on the supporting infrastructure, e.g. 3821 poisoning proxy caches, or tricking validation / lookup 3822 interfaces in resource directories and, more generally, any 3823 component that stores global network state and uses CoAP as the 3824 messaging facility to handle state set/update's is a potential 3825 target.); or 3827 4. spoofing a multicast request for a target node which may result 3828 in both network congestion/collapse and victim DoS'ing / forced 3829 wakeup from sleeping; or 3831 5. spoofing observe messages, etc. 3833 Response spoofing by off-path attackers can be detected and mitigated 3834 even without transport layer security by choosing a non-trivial, 3835 randomized token in the request (Section 5.3.1). [RFC4086] discusses 3836 randomness requirements for security. 3838 In principle, other kinds of spoofing can be detected by CoAP only in 3839 case CON semantics is used, because of unexpected ACK/RSTs coming 3840 from the deceived endpoint. But this imposes keeping track of the 3841 used Message IDs which is not always possible, and moreover detection 3842 becomes available usually after the damage is already done. This 3843 kind of attack can be prevented using security modes other than 3844 NoSec. 3846 With or without source address spoofing, a client can attempt to 3847 overload a server by sending requests, preferably complex ones, to a 3848 server; address spoofing makes tracing back, and blocking, this 3849 attack harder. Given that the cost of a CON request is small, this 3850 attack can easily be executed. Under this attack, a constrained node 3851 with limited total energy available may exhaust that energy much more 3852 quickly than planned (battery depletion attack). Also, if the client 3853 uses a Confirmable message and the server responds with a Confirmable 3854 separate response to a (possibly spoofed) address that does not 3855 respond, the server will have to allocate buffer and retransmission 3856 logic for each response up to the exhaustion of MAX_TRANSMIT_SPAN, 3857 making it more likely that it runs out of resources for processing 3858 legitimate traffic. The latter problem can be mitigated somewhat by 3859 limiting the rate of responses as discussed in Section 4.7. An 3860 attacker could also spoof the address of a legitimate client, which, 3861 if the server uses separate responses, might block legitimate 3862 responses to that client because of NSTART=1. All these attacks can 3863 be prevented using a security mode other than NoSec, leaving only 3864 attacks on the security protocol. 3866 11.5. Cross-Protocol Attacks 3868 The ability to incite a CoAP endpoint to send packets to a fake 3869 source address can be used not only for amplification, but also for 3870 cross-protocol attacks against a victim listening to UDP packets at a 3871 given address (IP address and port): 3873 o the attacker sends a message to a CoAP endpoint with the given 3874 address as the fake source address, 3876 o the CoAP endpoint replies with a message to the given source 3877 address, 3879 o the victim at the given address receives a UDP packet that it 3880 interprets according to the rules of a different protocol. 3882 This may be used to circumvent firewall rules that prevent direct 3883 communication from the attacker to the victim, but happen to allow 3884 communication from the CoAP endpoint (which may also host a valid 3885 role in the other protocol) to the victim. 3887 Also, CoAP endpoints may be the victim of a cross-protocol attack 3888 generated through an endpoint of another UDP-based protocol such as 3889 DNS. In both cases, attacks are possible if the security properties 3890 of the endpoints rely on checking IP addresses (and firewalling off 3891 direct attacks sent from outside using fake IP addresses). In 3892 general, because of their lack of context, UDP-based protocols are 3893 relatively easy targets for cross-protocol attacks. 3895 Finally, CoAP URIs transported by other means could be used to incite 3896 clients to send messages to endpoints of other protocols. 3898 One mitigation against cross-protocol attacks is strict checking of 3899 the syntax of packets received, combined with sufficient difference 3900 in syntax. As an example, it might help if it were difficult to 3901 incite a DNS server to send a DNS response that would pass the checks 3902 of a CoAP endpoint. Unfortunately, the first two bytes of a DNS 3903 reply are an ID that can be chosen by the attacker, which map into 3904 the interesting part of the CoAP header, and the next two bytes are 3905 then interpreted as CoAP's Message ID (i.e., any value is 3906 acceptable). The DNS count words may be interpreted as multiple 3907 instances of a (non-existent, but elective) CoAP option 0, or 3908 possibly as a Token. The echoed query finally may be manufactured by 3909 the attacker to achieve a desired effect on the CoAP endpoint; the 3910 response added by the server (if any) might then just be interpreted 3911 as added payload. 3913 1 1 1 1 1 1 3914 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 3915 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3916 | ID | T, TKL, code 3917 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3918 |QR| Opcode |AA|TC|RD|RA| Z | RCODE | Message ID 3919 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3920 | QDCOUNT | (options 0) 3921 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3922 | ANCOUNT | (options 0) 3923 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3924 | NSCOUNT | (options 0) 3925 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3926 | ARCOUNT | (options 0) 3927 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 3929 Figure 15: DNS Header vs. CoAP Message 3931 In general, for any pair of protocols, one of the protocols can very 3932 well have been designed in a way that enables an attacker to cause 3933 the generation of replies that look like messages of the other 3934 protocol. It is often much harder to ensure or prove the absence of 3935 viable attacks than to generate examples that may not yet completely 3936 enable an attack but might be further developed by more creative 3937 minds. Cross-protocol attacks can therefore only be completely 3938 mitigated if endpoints don't authorize actions desired by an attacker 3939 just based on trusting the source IP address of a packet. 3940 Conversely, a NoSec environment that completely relies on a firewall 3941 for CoAP security not only needs to firewall off the CoAP endpoints 3942 but also all other endpoints that might be incited to send UDP 3943 messages to CoAP endpoints using some other UDP-based protocol. 3945 In addition to the considerations above, the security considerations 3946 for DTLS with respect to cross-protocol attacks apply. E.g., if the 3947 same DTLS security association ("connection") is used to carry data 3948 of multiple protocols, DTLS no longer provides protection against 3949 cross-protocol attacks between these protocols. 3951 11.6. Constrained node considerations 3953 Implementers on constrained nodes often find themselves without a 3954 good source of entropy [RFC4086]. If that is the case, the node MUST 3955 NOT be used for processes that require good entropy, such as key 3956 generation. Instead, keys should be generated externally and added 3957 to the device during manufacturing or commissioning. 3959 Due to their low processing power, constrained nodes are particularly 3960 susceptible to timing attacks. Special care must be taken in 3961 implementation of cryptographic primitives. 3963 Large numbers of constrained nodes will be installed in exposed 3964 environments and will have little resistance to tampering, including 3965 recovery of keying materials. This needs to be considered when 3966 defining the scope of credentials assigned to them. In particular, 3967 assigning a shared key to a group of nodes may make any single 3968 constrained node a target for subverting the entire group. 3970 12. IANA Considerations 3972 12.1. CoAP Code Registries 3974 This document defines two sub-registries for the values of the Code 3975 field in the CoAP header within the Constrained RESTful Environments 3976 (CoRE) Parameters ("CoRE Parameters") registry. 3978 Values in the two sub-registries are eight-bit values notated as 3979 three decimal digits c.dd separated by a period between the first and 3980 the second digit; the first digit c is between 0 and 7 and denotes 3981 the code class; the second and third digit dd denote a decimal number 3982 between 00 and 31 for the detail. 3984 All Code values are assigned by sub-registries according to the 3985 following ranges: 3987 0.00 Indicates an Empty message (see Section 4.1). 3989 0.01-0.31 Indicates a request. Values in this range are assigned by 3990 the "CoAP Method Codes" sub-registry (see Section 12.1.1). 3992 1.00-1.31 Reserved 3994 2.00-5.31 Indicates a response. Values in this range are assigned by 3995 the "CoAP Response Codes" sub-registry (see 3996 Section 12.1.2). 3998 6.00-7.31 Reserved 4000 12.1.1. Method Codes 4002 The name of the sub-registry is "CoAP Method Codes". 4004 Each entry in the sub-registry must include the Method Code in the 4005 range 0.01-0.31, the name of the method, and a reference to the 4006 method's documentation. 4008 Initial entries in this sub-registry are as follows: 4010 +------+--------+-----------+ 4011 | Code | Name | Reference | 4012 +------+--------+-----------+ 4013 | 0.01 | GET | [RFCXXXX] | 4014 | 0.02 | POST | [RFCXXXX] | 4015 | 0.03 | PUT | [RFCXXXX] | 4016 | 0.04 | DELETE | [RFCXXXX] | 4017 +------+--------+-----------+ 4019 Table 5: CoAP Method Codes 4021 All other Method Codes are Unassigned. 4023 The IANA policy for future additions to this sub-registry is "IETF 4024 Review or IESG approval" as described in [RFC5226]. 4026 The documentation of a method code should specify the semantics of a 4027 request with that code, including the following properties: 4029 o The response codes the method returns in the success case. 4031 o Whether the method is idempotent, safe, or both. 4033 12.1.2. Response Codes 4034 The name of the sub-registry is "CoAP Response Codes". 4036 Each entry in the sub-registry must include the Response Code in the 4037 range 2.00-5.31, a description of the Response Code, and a reference 4038 to the Response Code's documentation. 4040 Initial entries in this sub-registry are as follows: 4042 +------+------------------------------+-----------+ 4043 | Code | Description | Reference | 4044 +------+------------------------------+-----------+ 4045 | 2.01 | Created | [RFCXXXX] | 4046 | 2.02 | Deleted | [RFCXXXX] | 4047 | 2.03 | Valid | [RFCXXXX] | 4048 | 2.04 | Changed | [RFCXXXX] | 4049 | 2.05 | Content | [RFCXXXX] | 4050 | 4.00 | Bad Request | [RFCXXXX] | 4051 | 4.01 | Unauthorized | [RFCXXXX] | 4052 | 4.02 | Bad Option | [RFCXXXX] | 4053 | 4.03 | Forbidden | [RFCXXXX] | 4054 | 4.04 | Not Found | [RFCXXXX] | 4055 | 4.05 | Method Not Allowed | [RFCXXXX] | 4056 | 4.06 | Not Acceptable | [RFCXXXX] | 4057 | 4.12 | Precondition Failed | [RFCXXXX] | 4058 | 4.13 | Request Entity Too Large | [RFCXXXX] | 4059 | 4.15 | Unsupported Content-Format | [RFCXXXX] | 4060 | 5.00 | Internal Server Error | [RFCXXXX] | 4061 | 5.01 | Not Implemented | [RFCXXXX] | 4062 | 5.02 | Bad Gateway | [RFCXXXX] | 4063 | 5.03 | Service Unavailable | [RFCXXXX] | 4064 | 5.04 | Gateway Timeout | [RFCXXXX] | 4065 | 5.05 | Proxying Not Supported | [RFCXXXX] | 4066 +------+------------------------------+-----------+ 4068 Table 6: CoAP Response Codes 4070 The Response Codes 3.00-3.31 are Reserved for future use. All other 4071 Response Codes are Unassigned. 4073 The IANA policy for future additions to this sub-registry is "IETF 4074 Review or IESG approval" as described in [RFC5226]. 4076 The documentation of a response code should specify the semantics of 4077 a response with that code, including the following properties: 4079 o The methods the response code applies to. 4081 o Whether payload is required, optional or not allowed. 4083 o The semantics of the payload. For example, the payload of a 2.05 4084 (Content) response is a representation of the target resource; the 4085 payload in an error response is a human-readable diagnostic 4086 payload. 4088 o The format of the payload. For example, the format in a 2.05 4089 (Content) response is indicated by the Content-Format Option; the 4090 format of the payload in an error response is always Net-Unicode 4091 text. 4093 o Whether the response is cacheable according to the freshness 4094 model. 4096 o Whether the response is validatable according to the validation 4097 model. 4099 o Whether the response causes a cache to mark responses stored for 4100 the request URI as not fresh. 4102 12.2. Option Number Registry 4104 This document defines a sub-registry for the Option Numbers used in 4105 CoAP options within the "CoRE Parameters" registry. The name of the 4106 sub-registry is "CoAP Option Numbers". 4108 Each entry in the sub-registry must include the Option Number, the 4109 name of the option and a reference to the option's documentation. 4111 Initial entries in this sub-registry are as follows: 4113 +--------+------------------+-----------+ 4114 | Number | Name | Reference | 4115 +--------+------------------+-----------+ 4116 | 0 | (Reserved) | [RFCXXXX] | 4117 | 1 | If-Match | [RFCXXXX] | 4118 | 3 | Uri-Host | [RFCXXXX] | 4119 | 4 | ETag | [RFCXXXX] | 4120 | 5 | If-None-Match | [RFCXXXX] | 4121 | 7 | Uri-Port | [RFCXXXX] | 4122 | 8 | Location-Path | [RFCXXXX] | 4123 | 11 | Uri-Path | [RFCXXXX] | 4124 | 12 | Content-Format | [RFCXXXX] | 4125 | 14 | Max-Age | [RFCXXXX] | 4126 | 15 | Uri-Query | [RFCXXXX] | 4127 | 17 | Accept | [RFCXXXX] | 4128 | 20 | Location-Query | [RFCXXXX] | 4129 | 35 | Proxy-Uri | [RFCXXXX] | 4130 | 39 | Proxy-Scheme | [RFCXXXX] | 4131 | 60 | Size1 | [RFCXXXX] | 4132 | 128 | (Reserved) | [RFCXXXX] | 4133 | 132 | (Reserved) | [RFCXXXX] | 4134 | 136 | (Reserved) | [RFCXXXX] | 4135 | 140 | (Reserved) | [RFCXXXX] | 4136 +--------+------------------+-----------+ 4138 Table 7: CoAP Option Numbers 4140 The IANA policy for future additions to this sub-registry is split 4141 into three tiers as follows. The range of 0..255 is reserved for 4142 options defined by the IETF (IETF Review or IESG approval). The 4143 range of 256..2047 is reserved for commonly used options with public 4144 specifications (Specification Required). The range of 2048..64999 is 4145 for all other options including private or vendor specific ones, 4146 which undergo a Designated Expert review to help ensure that the 4147 option semantics are defined correctly. The option numbers between 4148 65000 and 65535 inclusive are reserved for experiments. They are not 4149 meant for vendor specific use of any kind and MUST NOT be used in 4150 operational deployments. 4152 +---------------+------------------------------+ 4153 | Option Number | Policy [RFC5226] | 4154 +---------------+------------------------------+ 4155 | 0..255 | IETF Review or IESG approval | 4156 | 256..2047 | Specification Required | 4157 | 2048..64999 | Designated Expert | 4158 | 65000..65535 | Reserved for experiments | 4159 +---------------+------------------------------+ 4161 Table 8: CoAP Option Number Registry Policy 4163 The documentation of an Option Number should specify the semantics of 4164 an option with that number, including the following properties: 4166 o The meaning of the option in a request. 4168 o The meaning of the option in a response. 4170 o Whether the option is critical or elective, as determined by the 4171 Option Number. 4173 o Whether the option is Safe-to-Forward, and, if yes, whether it is 4174 part of the Cache-Key, as determined by the Option Number (see 4175 Section 5.4.2). 4177 o The format and length of the option's value. 4179 o Whether the option must occur at most once or whether it can occur 4180 multiple times. 4182 o The default value, if any. For a critical option with a default 4183 value, a discussion on how the default value enables processing by 4184 implementations not implementing the critical option 4185 (Section 5.4.4). 4187 12.3. Content-Format Registry 4189 Internet media types are identified by a string, such as "application 4190 /xml" [RFC2046]. In order to minimize the overhead of using these 4191 media types to indicate the format of payloads, this document defines 4192 a sub-registry for a subset of Internet media types to be used in 4193 CoAP and assigns each, in combination with a content-coding, a 4194 numeric identifier. The name of the sub-registry is "CoAP Content- 4195 Formats", within the "CoRE Parameters" registry. 4197 Each entry in the sub-registry must include the media type registered 4198 with IANA, the numeric identifier in the range 0-65535 to be used for 4199 that media type in CoAP, the content-coding associated with this 4200 identifier, and a reference to a document describing what a payload 4201 with that media type means semantically. 4203 CoAP does not include a separate way to convey content-encoding 4204 information with a request or response, and for that reason the 4205 content-encoding is also specified for each identifier (if any). If 4206 multiple content-encodings will be used with a media type, then a 4207 separate Content-Format identifier for each is to be registered. 4208 Similarly, other parameters related to an Internet media type, such 4209 as level, can be defined for a CoAP Content-Format entry. 4211 Initial entries in this sub-registry are as follows: 4213 +------------------+----------+-------+-----------------------------+ 4214 | Media type | Encoding | Id. | Reference | 4215 +------------------+----------+-------+-----------------------------+ 4216 | text/plain; | - | 0 | [RFC2046][RFC3676][RFC5147] | 4217 | charset=utf-8 | | | | 4218 | application/ | - | 40 | [RFC6690] | 4219 | link-format | | | | 4220 | application/xml | - | 41 | [RFC3023] | 4221 | application/ | - | 42 | [RFC2045][RFC2046] | 4222 | octet-stream | | | | 4223 | application/exi | - | 47 | [EXIMIME] | 4224 | application/json | - | 50 | [RFC4627] | 4225 +------------------+----------+-------+-----------------------------+ 4227 Table 9: CoAP Content-Formats 4229 The identifiers between 65000 and 65535 inclusive are reserved for 4230 experiments. They are not meant for vendor specific use of any kind 4231 and MUST NOT be used in operational deployments. The identifiers 4232 between 256 and 9999 are reserved for future use in IETF 4233 specifications (IETF review or IESG approval). All other identifiers 4234 are Unassigned. 4236 Because the name space of single-byte identifiers is so small, the 4237 IANA policy for future additions in the range 0-255 inclusive to the 4238 sub-registry is "Expert Review" as described in [RFC5226]. The IANA 4239 policy for additions in the range 10000-64999 inclusive is "First 4240 Come First Served" as described in [RFC5226]. 4242 In machine to machine applications, it is not expected that generic 4243 Internet media types such as text/plain, application/xml or 4244 application/octet-stream are useful for real applications in the long 4245 term. It is recommended that M2M applications making use of CoAP 4246 will request new Internet media types from IANA indicating semantic 4247 information about how to create or parse a payload. For example, a 4248 Smart Energy application payload carried as XML might request a more 4249 specific type like application/se+xml or application/se-exi. 4251 12.4. URI Scheme Registration 4253 This document requests the registration of the Uniform Resource 4254 Identifier (URI) scheme "coap". The registration request complies 4255 with [RFC4395]. 4257 URI scheme name. 4258 coap 4260 Status. 4262 Permanent. 4264 URI scheme syntax. 4265 Defined in Section 6.1 of [RFCXXXX]. 4267 URI scheme semantics. 4268 The "coap" URI scheme provides a way to identify resources that 4269 are potentially accessible over the Constrained Application 4270 Protocol (CoAP). The resources can be located by contacting the 4271 governing CoAP server and operated on by sending CoAP requests to 4272 the server. This scheme can thus be compared to the "http" URI 4273 scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of 4274 operation. 4276 Encoding considerations. 4277 The scheme encoding conforms to the encoding rules established for 4278 URIs in [RFC3986], i.e. internationalized and reserved characters 4279 are expressed using UTF-8-based percent-encoding. 4281 Applications/protocols that use this URI scheme name. 4282 The scheme is used by CoAP endpoints to access CoAP resources. 4284 Interoperability considerations. 4285 None. 4287 Security considerations. 4288 See Section 11.1 of [RFCXXXX]. 4290 Contact. 4291 IETF Chair 4293 Author/Change controller. 4294 IESG 4296 References. 4297 [RFCXXXX] 4299 12.5. Secure URI Scheme Registration 4301 This document requests the registration of the Uniform Resource 4302 Identifier (URI) scheme "coaps". The registration request complies 4303 with [RFC4395]. 4305 URI scheme name. 4306 coaps 4308 Status. 4309 Permanent. 4311 URI scheme syntax. 4312 Defined in Section 6.2 of [RFCXXXX]. 4314 URI scheme semantics. 4315 The "coaps" URI scheme provides a way to identify resources that 4316 are potentially accessible over the Constrained Application 4317 Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for 4318 transport security. The resources can be located by contacting 4319 the governing CoAP server and operated on by sending CoAP requests 4320 to the server. This scheme can thus be compared to the "https" 4321 URI scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details 4322 of operation. 4324 Encoding considerations. 4325 The scheme encoding conforms to the encoding rules established for 4326 URIs in [RFC3986], i.e. internationalized and reserved characters 4327 are expressed using UTF-8-based percent-encoding. 4329 Applications/protocols that use this URI scheme name. 4330 The scheme is used by CoAP endpoints to access CoAP resources 4331 using DTLS. 4333 Interoperability considerations. 4334 None. 4336 Security considerations. 4337 See Section 11.1 of [RFCXXXX]. 4339 Contact. 4340 IETF Chair 4342 Author/Change controller. 4343 IESG 4345 References. 4346 [RFCXXXX] 4348 12.6. Service Name and Port Number Registration 4350 One of the functions of CoAP is resource discovery: a CoAP client can 4351 ask a CoAP server about the resources offered by it (see Section 7). 4352 To enable resource discovery just based on the knowledge of an IP 4353 address, the CoAP port for resource discovery needs to be 4354 standardized. 4356 IANA has assigned the port number 5683 and the service name "coap", 4357 in accordance with [RFC6335]. 4359 Besides unicast, CoAP can be used with both multicast and anycast. 4361 Service Name. 4362 coap 4364 Transport Protocol. 4365 UDP 4367 Assignee. 4368 IESG 4370 Contact. 4371 IETF Chair 4373 Description. 4374 Constrained Application Protocol (CoAP) 4376 Reference. 4377 [RFCXXXX] 4379 Port Number. 4380 5683 4382 12.7. Secure Service Name and Port Number Registration 4384 CoAP resource discovery may also be provided using the DTLS-secured 4385 CoAP "coaps" scheme. Thus the CoAP port for secure resource 4386 discovery needs to be standardized. 4388 This document requests the assignment of the port number 4389 [IANA_TBD_PORT] and the service name "coaps", in accordance with 4390 [RFC6335]. 4392 Besides unicast, DTLS-secured CoAP can be used with anycast. 4394 Service Name. 4395 coaps 4397 Transport Protocol. 4398 UDP 4400 Assignee. 4401 IESG 4403 Contact. 4404 IETF Chair 4406 Description. 4408 DTLS-secured CoAP 4410 Reference. 4411 [RFCXXXX] 4413 Port Number. 4414 [IANA_TBD_PORT] 4416 12.8. Multicast Address Registration 4418 Section 8, "Multicast CoAP", defines the use of multicast. This 4419 document requests the assignment of the following multicast addresses 4420 for use by CoAP nodes: 4422 IPv4 -- "All CoAP Nodes" address [TBD1], from the IPv4 Multicast 4423 Address Space Registry. As the address is used for discovery that 4424 may span beyond a single network, it should come from the 4425 Internetwork Control Block (224.0.1.x, RFC 5771). 4427 IPv6 -- "All CoAP Nodes" address [TBD2], from the IPv6 Multicast 4428 Address Space Registry, in the Variable Scope Multicast Addresses 4429 space (RFC3307). Note that there is a distinct multicast address 4430 for each scope that interested CoAP nodes should listen to; CoAP 4431 needs the Link-Local and Site-Local scopes only. The address 4432 should be of the form FF0x::nn, where nn is a single byte, to 4433 ensure good compression of the local-scope address with [RFC6282]. 4435 [The explanatory text to be removed upon allocation of the addresses, 4436 except for the note about the distinct multicast addresses.] 4438 13. Acknowledgements 4440 Brian Frank was a contributor to and co-author of previous drafts of 4441 this specification. 4443 Special thanks to Peter Bigot, Esko Dijk and Cullen Jennings for 4444 substantial contributions to the ideas and text in the document, 4445 along with countless detailed reviews and discussions. 4447 Thanks to Ed Beroset, Angelo P. Castellani, Gilbert Clark, Robert 4448 Cragie, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas Fossati, Tom 4449 Herbst, Richard Kelsey, Ari Keranen, Matthias Kovatsch, Salvatore 4450 Loreto, Kerry Lynn, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin 4451 O'Flynn, Charles Palmer, Adriano Pezzuto, Robert Quattlebaum, Akbar 4452 Rahman, Eric Rescorla, Dan Romascanu, David Ryan, Szymon Sasin, 4453 Michael Scharf, Dale Seed, Robby Simpson, Peter van der Stok, Michael 4454 Stuber, Linyi Tian, Gilman Tolle, Matthieu Vial and Alper Yegin for 4455 helpful comments and discussions that have shaped the document. 4457 Special thanks also to the IESG reviewers, Adrian Farrel, Martin 4458 Stiemerling, Pete Resnick, Richard Barnes, Sean Turner, Spencer 4459 Dawkins, Stephen Farrell, and Ted Lemon, who contributed in-depth 4460 reviews. 4462 Some of the text has been borrowed from the working documents of the 4463 IETF httpbis working group. 4465 14. References 4467 14.1. Normative References 4469 [I-D.ietf-tls-oob-pubkey] 4470 Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and 4471 T. Kivinen, "Out-of-Band Public Key Validation for 4472 Transport Layer Security (TLS)", draft-ietf-tls-oob- 4473 pubkey-07 (work in progress), February 2013. 4475 [I-D.mcgrew-tls-aes-ccm-ecc] 4476 McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES- 4477 CCM ECC Cipher Suites for TLS", draft-mcgrew-tls-aes-ccm- 4478 ecc-06 (work in progress), February 2013. 4480 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 4481 August 1980. 4483 [RFC2045] Freed, N. and N.S. Borenstein, "Multipurpose Internet Mail 4484 Extensions (MIME) Part One: Format of Internet Message 4485 Bodies", RFC 2045, November 1996. 4487 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4488 Extensions (MIME) Part Two: Media Types", RFC 2046, 4489 November 1996. 4491 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4492 Requirement Levels", BCP 14, RFC 2119, March 1997. 4494 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 4495 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 4496 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 4498 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 4499 Types", RFC 3023, January 2001. 4501 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 4502 10646", STD 63, RFC 3629, November 2003. 4504 [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", 4505 RFC 3676, February 2004. 4507 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4508 Resource Identifier (URI): Generic Syntax", STD 66, RFC 4509 3986, January 2005. 4511 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 4512 for Transport Layer Security (TLS)", RFC 4279, December 4513 2005. 4515 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 4516 Registration Procedures for New URI Schemes", BCP 35, RFC 4517 4395, February 2006. 4519 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 4520 text/plain Media Type", RFC 5147, April 2008. 4522 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 4523 Interchange", RFC 5198, March 2008. 4525 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 4526 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 4527 May 2008. 4529 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 4530 Specifications: ABNF", STD 68, RFC 5234, January 2008. 4532 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4533 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 4535 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4536 Housley, R., and W. Polk, "Internet X.509 Public Key 4537 Infrastructure Certificate and Certificate Revocation List 4538 (CRL) Profile", RFC 5280, May 2008. 4540 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 4541 "Elliptic Curve Cryptography Subject Public Key 4542 Information", RFC 5480, March 2009. 4544 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4545 Uniform Resource Identifiers (URIs)", RFC 5785, April 4546 2010. 4548 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 4549 Address Text Representation", RFC 5952, August 2010. 4551 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 4553 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 4554 Extension Definitions", RFC 6066, January 2011. 4556 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4557 Security Version 1.2", RFC 6347, January 2012. 4559 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 4560 Format", RFC 6690, August 2012. 4562 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 4563 Keranen, A., and P. Hallam-Baker, "Naming Things with 4564 Hashes", RFC 6920, April 2013. 4566 14.2. Informative References 4568 [EUI64] , "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) 4569 REGISTRATION AUTHORITY", April 2010, . 4572 [EXIMIME] , "Efficient XML Interchange (EXI) Format 1.0", December 4573 2009, . 4576 [HHGTTG] Adams, D., "The Hitchhiker's Guide to the Galaxy", October 4577 1979. 4579 [I-D.allman-tcpm-rto-consider] 4580 Allman, M., "Retransmission Timeout Considerations", 4581 draft-allman-tcpm-rto-consider-01 (work in progress), May 4582 2012. 4584 [I-D.bormann-coap-misc] 4585 Bormann, C. and K. Hartke, "Miscellaneous additions to 4586 CoAP", draft-bormann-coap-misc-22 (work in progress), 4587 December 2012. 4589 [I-D.bormann-core-ipsec-for-coap] 4590 Bormann, C., "Using CoAP with IPsec", draft-bormann-core- 4591 ipsec-for-coap-00 (work in progress), December 2012. 4593 [I-D.castellani-core-http-mapping] 4594 Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 4595 E. Dijk, "Best Practices for HTTP-CoAP Mapping 4596 Implementation", draft-castellani-core-http-mapping-07 4597 (work in progress), February 2013. 4599 [I-D.ietf-core-block] 4600 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 4601 draft-ietf-core-block-10 (work in progress), October 2012. 4603 [I-D.ietf-core-groupcomm] 4604 Rahman, A. and E. Dijk, "Group Communication for CoAP", 4605 draft-ietf-core-groupcomm-06 (work in progress), April 4606 2013. 4608 [I-D.ietf-core-observe] 4609 Hartke, K., "Observing Resources in CoAP", draft-ietf- 4610 core-observe-08 (work in progress), February 2013. 4612 [I-D.ietf-lwig-terminology] 4613 Bormann, C., Ersue, M., and A. Keraenen, "Terminology for 4614 Constrained Node Networks", draft-ietf-lwig-terminology-04 4615 (work in progress), April 2013. 4617 [I-D.ietf-tls-multiple-cert-status-extension] 4618 Pettersen, Y., "The TLS Multiple Certificate Status 4619 Request Extension", draft-ietf-tls-multiple-cert-status- 4620 extension-08 (work in progress), April 2013. 4622 [REST] Fielding, R., "Architectural Styles and the Design of 4623 Network-based Software Architectures", Ph.D. Dissertation, 4624 University of California, Irvine, 2000, . 4628 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 4629 October 1969. 4631 [RFC0792] Postel, J., "Internet Control Message Protocol", STD 5, 4632 RFC 792, September 1981. 4634 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 4635 793, September 1981. 4637 [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. 4638 Adams, "X.509 Internet Public Key Infrastructure Online 4639 Certificate Status Protocol - OCSP", RFC 2560, June 1999. 4641 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 4643 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 4644 with Session Description Protocol (SDP)", RFC 3264, June 4645 2002. 4647 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 4648 "Advanced Sockets Application Program Interface (API) for 4649 IPv6", RFC 3542, May 2003. 4651 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and 4652 G. Fairhurst, "The Lightweight User Datagram Protocol 4653 (UDP-Lite)", RFC 3828, July 2004. 4655 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 4656 Requirements for Security", BCP 106, RFC 4086, June 2005. 4658 [RFC4443] Conta, A., Deering, S., and M. Gupta, "Internet Control 4659 Message Protocol (ICMPv6) for the Internet Protocol 4660 Version 6 (IPv6) Specification", RFC 4443, March 2006. 4662 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 4663 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 4664 for Transport Layer Security (TLS)", RFC 4492, May 2006. 4666 [RFC4627] Crockford, D., "The application/json Media Type for 4667 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 4669 [RFC4821] Mathis, M. and J. Heffner, "Packetization Layer Path MTU 4670 Discovery", RFC 4821, March 2007. 4672 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 4673 "Transmission of IPv6 Packets over IEEE 802.15.4 4674 Networks", RFC 4944, September 2007. 4676 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 4677 for Application Designers", BCP 145, RFC 5405, November 4678 2008. 4680 [RFC5489] Badra, M. and I. Hajjeh, "ECDHE_PSK Cipher Suites for 4681 Transport Layer Security (TLS)", RFC 5489, March 2009. 4683 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 4684 Curve Cryptography Algorithms", RFC 6090, February 2011. 4686 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 4687 Protocol (XMPP): Core", RFC 6120, March 2011. 4689 [RFC6282] Hui, J. and P. Thubert, "Compression Format for IPv6 4690 Datagrams over IEEE 802.15.4-Based Networks", RFC 6282, 4691 September 2011. 4693 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 4694 Cheshire, "Internet Assigned Numbers Authority (IANA) 4695 Procedures for the Management of the Service Name and 4696 Transport Protocol Port Number Registry", BCP 165, RFC 4697 6335, August 2011. 4699 [RFC6655] McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for 4700 Transport Layer Security (TLS)", RFC 6655, July 2012. 4702 [RFC6936] Fairhurst, G. and M. Westerlund, "Applicability Statement 4703 for the Use of IPv6 UDP Datagrams with Zero Checksums", 4704 RFC 6936, April 2013. 4706 [W3CXMLSEC] 4707 Wenning, R., "Report of the XML Security PAG", October 4708 2012, . 4710 Appendix A. Examples 4712 This section gives a number of short examples with message flows for 4713 GET requests. These examples demonstrate the basic operation, the 4714 operation in the presence of retransmissions, and multicast. 4716 Figure 16 shows a basic GET request causing a piggy-backed response: 4717 The client sends a Confirmable GET request for the resource coap:// 4718 server/temperature to the server with a Message ID of 0x7d34. The 4719 request includes one Uri-Path Option (Delta 0 + 11 = 11, Length 11, 4720 Value "temperature"); the Token is left empty. This request is a 4721 total of 16 bytes long. A 2.05 (Content) response is returned in the 4722 Acknowledgement message that acknowledges the Confirmable request, 4723 echoing both the Message ID 0x7d34 and the empty Token value. The 4724 response includes a Payload of "22.3 C" and is 11 bytes long. 4726 Client Server 4727 | | 4728 | | 4729 +----->| Header: GET (T=CON, Code=0.01, MID=0x7d34) 4730 | GET | Uri-Path: "temperature" 4731 | | 4732 | | 4733 |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34) 4734 | 2.05 | Payload: "22.3 C" 4735 | | 4737 0 1 2 3 4738 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 4739 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4740 | 1 | 0 | 0 | GET=1 | MID=0x7d34 | 4741 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4742 | 11 | 11 | "temperature" (11 B) ... 4743 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4745 0 1 2 3 4746 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 4747 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4748 | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | 4749 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4750 |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... 4751 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4753 Figure 16: Confirmable request; piggy-backed response 4755 Figure 17 shows a similar example, but with the inclusion of an non- 4756 empty Token (Value 0x20) in the request and the response, increasing 4757 the sizes to 17 and 12 bytes, respectively. 4759 Client Server 4760 | | 4761 | | 4762 +----->| Header: GET (T=CON, Code=0.01, MID=0x7d35) 4763 | GET | Token: 0x20 4764 | | Uri-Path: "temperature" 4765 | | 4766 | | 4767 |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d35) 4768 | 2.05 | Token: 0x20 4769 | | Payload: "22.3 C" 4770 | | 4772 0 1 2 3 4773 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 4774 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4775 | 1 | 0 | 1 | GET=1 | MID=0x7d35 | 4776 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4777 | 0x20 | 4778 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4779 | 11 | 11 | "temperature" (11 B) ... 4780 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4782 0 1 2 3 4783 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 4784 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4785 | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | 4786 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4787 | 0x20 | 4788 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4789 |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ... 4790 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 4792 Figure 17: Confirmable request; piggy-backed response 4794 In Figure 18, the Confirmable GET request is lost. After ACK_TIMEOUT 4795 seconds, the client retransmits the request, resulting in a piggy- 4796 backed response as in the previous example. 4798 Client Server 4799 | | 4800 | | 4801 +----X | Header: GET (T=CON, Code=0.01, MID=0x7d36) 4802 | GET | Token: 0x31 4803 | | Uri-Path: "temperature" 4804 TIMEOUT | 4805 | | 4806 +----->| Header: GET (T=CON, Code=0.01, MID=0x7d36) 4807 | GET | Token: 0x31 4808 | | Uri-Path: "temperature" 4809 | | 4810 | | 4811 |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d36) 4812 | 2.05 | Token: 0x31 4813 | | Payload: "22.3 C" 4814 | | 4816 Figure 18: Confirmable request (retransmitted); piggy-backed response 4818 In Figure 19, the first Acknowledgement message from the server to 4819 the client is lost. After ACK_TIMEOUT seconds, the client 4820 retransmits the request. 4822 Client Server 4823 | | 4824 | | 4825 +----->| Header: GET (T=CON, Code=0.01, MID=0x7d37) 4826 | GET | Token: 0x42 4827 | | Uri-Path: "temperature" 4828 | | 4829 | | 4830 | X----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37) 4831 | 2.05 | Token: 0x42 4832 | | Payload: "22.3 C" 4833 TIMEOUT | 4834 | | 4835 +----->| Header: GET (T=CON, Code=0.01, MID=0x7d37) 4836 | GET | Token: 0x42 4837 | | Uri-Path: "temperature" 4838 | | 4839 | | 4840 |<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37) 4841 | 2.05 | Token: 0x42 4842 | | Payload: "22.3 C" 4843 | | 4845 Figure 19: Confirmable request; piggy-backed response (retransmitted) 4847 In Figure 20, the server acknowledges the Confirmable request and 4848 sends a 2.05 (Content) response separately in a Confirmable message. 4849 Note that the Acknowledgement message and the Confirmable response do 4850 not necessarily arrive in the same order as they were sent. The 4851 client acknowledges the Confirmable response. 4853 Client Server 4854 | | 4855 | | 4856 +----->| Header: GET (T=CON, Code=0.01, MID=0x7d38) 4857 | GET | Token: 0x53 4858 | | Uri-Path: "temperature" 4859 | | 4860 | | 4861 |<- - -+ Header: (T=ACK, Code=0.00, MID=0x7d38) 4862 | | 4863 | | 4864 |<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7b) 4865 | 2.05 | Token: 0x53 4866 | | Payload: "22.3 C" 4867 | | 4868 | | 4869 +- - ->| Header: (T=ACK, Code=0.00, MID=0xad7b) 4870 | | 4872 Figure 20: Confirmable request; separate response 4874 Figure 21 shows an example where the client loses its state (e.g., 4875 crashes and is rebooted) right after sending a Confirmable request, 4876 so the separate response arriving some time later comes unexpected. 4877 In this case, the client rejects the Confirmable response with a 4878 Reset message. Note that the unexpected ACK is silently ignored. 4880 Client Server 4881 | | 4882 | | 4883 +----->| Header: GET (T=CON, Code=0.01, MID=0x7d39) 4884 | GET | Token: 0x64 4885 | | Uri-Path: "temperature" 4886 CRASH | 4887 | | 4888 |<- - -+ Header: (T=ACK, Code=0.00, MID=0x7d39) 4889 | | 4890 | | 4891 |<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7c) 4892 | 2.05 | Token: 0x64 4893 | | Payload: "22.3 C" 4894 | | 4895 | | 4896 +- - ->| Header: (T=RST, Code=0.00, MID=0xad7c) 4897 | | 4899 Figure 21: Confirmable request; separate response (unexpected) 4901 Figure 22 shows a basic GET request where the request and the 4902 response are Non-confirmable, so both may be lost without notice. 4904 Client Server 4905 | | 4906 | | 4907 +----->| Header: GET (T=NON, Code=0.01, MID=0x7d40) 4908 | GET | Token: 0x75 4909 | | Uri-Path: "temperature" 4910 | | 4911 | | 4912 |<-----+ Header: 2.05 Content (T=NON, Code=2.05, MID=0xad7d) 4913 | 2.05 | Token: 0x75 4914 | | Payload: "22.3 C" 4915 | | 4917 Figure 22: Non-confirmable request; Non-confirmable response 4919 In Figure 23, the client sends a Non-confirmable GET request to a 4920 multicast address: all nodes in link-local scope. There are 3 4921 servers on the link: A, B and C. Servers A and B have a matching 4922 resource, therefore they send back a Non-confirmable 2.05 (Content) 4923 response. The response sent by B is lost. C does not have matching 4924 response, therefore it sends a Non-confirmable 4.04 (Not Found) 4925 response. 4927 Client ff02::1 A B C 4928 | | | | | 4929 | | | | | 4930 +------>| | | | Header: GET (T=NON, Code=0.01, MID=0x7d41) 4931 | GET | | | | Token: 0x86 4932 | | | | Uri-Path: "temperature" 4933 | | | | 4934 | | | | 4935 |<------------+ | | Header: 2.05 (T=NON, Code=2.05, MID=0x60b1) 4936 | 2.05 | | | Token: 0x86 4937 | | | | Payload: "22.3 C" 4938 | | | | 4939 | | | | 4940 | X------------+ | Header: 2.05 (T=NON, Code=2.05, MID=0x01a0) 4941 | 2.05 | | | Token: 0x86 4942 | | | | Payload: "20.9 C" 4943 | | | | 4944 | | | | 4945 |<------------------+ Header: 4.04 (T=NON, Code=4.04, MID=0x952a) 4946 | 4.04 | | | Token: 0x86 4947 | | | | 4949 Figure 23: Non-confirmable request (multicast); Non-confirmable 4950 response 4952 Appendix B. URI Examples 4954 The following examples demonstrate different sets of Uri options, and 4955 the result after constructing an URI from them. In addition to the 4956 options, Section 6.5 refers to the destination IP address and port, 4957 but not all paths of the algorithm cause the destination IP address 4958 and port to be included in the URI. 4960 o Input: 4962 Destination IP Address = [2001:db8::2:1] 4963 Destination UDP Port = 5683 4965 Output: 4967 coap://[2001:db8::2:1]/ 4969 o Input: 4971 Destination IP Address = [2001:db8::2:1] 4972 Destination UDP Port = 5683 4973 Uri-Host = "example.net" 4975 Output: 4977 coap://example.net/ 4979 o Input: 4981 Destination IP Address = [2001:db8::2:1] 4982 Destination UDP Port = 5683 4983 Uri-Host = "example.net" 4984 Uri-Path = ".well-known" 4985 Uri-Path = "core" 4987 Output: 4989 coap://example.net/.well-known/core 4991 o Input: 4993 Destination IP Address = [2001:db8::2:1] 4994 Destination UDP Port = 5683 4995 Uri-Host = "xn--18j4d.example" 4996 Uri-Path = the string composed of the Unicode characters U+3053 4997 U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as 4998 E38193E38293E381ABE381A1E381AF hexadecimal 5000 Output: 5002 coap://xn--18j4d.example/ 5003 %E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF 5005 (The line break has been inserted for readability; it is not 5006 part of the URI.) 5008 o Input: 5010 Destination IP Address = 198.51.100.1 5011 Destination UDP Port = 61616 5012 Uri-Path = "" 5013 Uri-Path = "/" 5014 Uri-Path = "" 5015 Uri-Path = "" 5016 Uri-Query = "//" 5017 Uri-Query = "?&" 5019 Output: 5021 coap://198.51.100.1:61616//%2F//?%2F%2F&?%26 5023 Appendix C. Changelog 5025 (To be removed by RFC editor before publication.) 5027 Changes from ietf-17 to ietf-18: Address comments from the IESG 5028 reviews. 5030 o Accept is now critical. 5032 o Add Size1 option for 4.13 responses. 5034 Changes from ietf-15 to ietf-16: Address comments from the IESG 5035 reviews. These should not impact interoperability. 5037 o Clarify that once there has been an empty ACK, all further ACKs to 5038 the same message also must be empty (#301). 5040 o Define Cache-key properly (#302). 5042 o Clarify that ACKs don't get retransmitted, the CONs do (#303). 5044 o Clarify: NON is like separate for CON (#304). 5046 o Don't use decimal response codes, keep the 3+5 structure 5047 throughout (#305). 5049 o RFC 2119 usage in 4.5 (#306) and 8.2 (#307). 5051 o Ensure all protocol reactions to reserved or prohibited values are 5052 defined (#308). 5054 o URI matching rules may be scheme specific (#309). 5056 o Don't dally beyond MAX_TRANSMIT_SPAN during retransmission (#310). 5058 o More about selecting a token length for anti-spoofing (#311). 5060 o Discuss spoofing ACKs (#312). 5062 o Qualify partial discard strategy implementation note as UDP only 5063 (#313). 5065 o Explicitly point out that UDP and DTLS don't mix (#314). 5067 o Point out security consideration re URIs and access control 5068 (#315). 5070 o Point to RFC5280 section 6 (#316). 5072 o Add a paragraph about cert status checking (#317). 5074 o RSA is out, ECDHE is in for cert-with-PSK, too (#318). 5076 o Point out that requests and responses don't always come in pairs 5077 (#319). 5079 o Clarify when there is a need for Unicode normalization (#320). 5081 o Point out that Uri-Host doesn't handle user-part (#321). 5083 o Clarify the use of non-FQDN Authority Names in certificates. 5085 o Numerous editorial improvements and clarifications. 5087 Changes from ietf-14 to ietf-15: Address comments from IETF last- 5088 call, mostly implementation notes and editorial improvements. These 5089 should not impact interoperability. 5091 o Clarify bytes/characters and UTF-8/ASCII in "Decomposing URIs into 5092 Options" (#282). 5094 o Make reference to ECC/CCM DTLS ciphersuite normative (#286). 5096 o Add a quick warning that bytewise scanning for a payload marker is 5097 not a good idea (#287). 5099 o Make reference to PROBING_RATE explicit for saturation discussion 5100 (#288). 5102 o Mention PROCESSING_DELAY when discussion piggy-backing (#290). 5104 o Various editorial nits: Clarify use of noun "service" (#283), 5105 Reference terminology from lwig-terminology (#284), make reference 5106 to HTTP terms more explicit (#285), add a forward reference to 5107 5.9.2.9 (#289), 8 kbit/s is not "conservative" (#291). 5109 o Add description of resource depletion attack (#292). 5111 o Add description of DoS attack on congestion control (#293). 5113 o Add discussion of using non-trivial token for protecting against 5114 hijacking (#294). 5116 o Clarify implementation note about per-destination Message ID 5117 generation. 5119 Changed from ietf-13 to ietf-14: 5121 o Made Accept option non-repeatable. 5123 o Clarified that Safe options in a 2.03 Valid response update the 5124 cache. 5126 o Clarified that payload sniffing is acceptable only if no Content- 5127 Format was supplied. 5129 o Clarified URI examples (Appendix B). 5131 o Numerous editorial improvements and clarifications. 5133 Changed from ietf-12 to ietf-13: 5135 o Simplified message format. 5137 * Removed the OC (Option Count) field in the CoAP Header. 5139 * Changed the End-of-Options Marker into the Payload Marker. 5141 * Changed the format of Options: use 4 bits for option length and 5142 delta; insert one or two additional bytes after the option 5143 header if necessary. 5145 * Promoted the Token Option to a field following the CoAP Header. 5147 o Clarified when a payload is a diagnostic payload (#264). 5149 o Moved IPsec discussion to separate draft (#262). 5151 o Added a reference to a separate draft on reverse-proxy URI 5152 embedding (#259). 5154 o Clarified the use of ETags and of 2.03 responses (#265, #254, 5155 #256). 5157 o Added reserved Location-* numbers and clarified Location-*. 5159 o Added Proxy-Scheme proposal. 5161 o Clarified terms such as content negotiation, selected 5162 representation, representation-format, message format error. 5164 o Numerous clarifications and a few bugfixes. 5166 Changed from ietf-11 to ietf-12: 5168 o Extended options to support lengths of up to 1034 bytes (#202). 5170 o Added new Jump mechanism for options and removed Fenceposting 5171 (#214). 5173 o Added new IANA option number registration policy (#214). 5175 o Added Proxy Unsafe/Safe and Cache-Key masking to option numbers 5176 (#241). 5178 o Re-numbered option numbers to use Unsafe/Safe and Cache-Key 5179 compliant numbers (#241). 5181 o Defined NSTART and restricted the value to 1 with a MUST (#215). 5183 o Defined PROBING_RATE and set it to 1 Byte/second (#215). 5185 o Defined DEFAULT_LEISURE (#246). 5187 o Renamed Content-Type into Content-Format, and Media Type registry 5188 into Content-Format registry. 5190 o A large number of small editorial changes, clarifications and 5191 improvements have been made. 5193 Changed from ietf-10 to ietf-11: 5195 o Expanded section 4.8 on Transmission Parameters, and used the 5196 derived values defined there (#201). Changed parameter names to 5197 be shorter and more to the point. 5199 o Several more small editorial changes, clarifications and 5200 improvements have been made. 5202 Changed from ietf-09 to ietf-10: 5204 o Option deltas are restricted to 0 to 14; the option delta 15 is 5205 used exclusively for the end-of-options marker (#239). 5207 o Option numbers that are a multiple of 14 are not reserved, but are 5208 required to have an empty default value (#212). 5210 o Fixed misleading language that was introduced in 5.10.2 in coap-07 5211 re Uri-Host and Uri-Port (#208). 5213 o Segments and arguments can have a length of zero characters 5214 (#213). 5216 o The Location-* options describe together describe one location. 5217 The location is a relative URI, not an "absolute path URI" (#218). 5219 o The value of the Location-Path Option must not be '.' or '..' 5220 (#218). 5222 o Added a sentence on constructing URIs from Location-* options 5223 (#231). 5225 o Reserved option numbers for future Location-* options (#230). 5227 o Fixed response codes with payload inconsistency (#233). 5229 o Added advice on default values for critical options (#207). 5231 o Clarified use of identifiers in RawPublicKey Mode Provisioning 5232 (#222). 5234 o Moved "Securing CoAP" out of the "Security Considerations" (#229). 5236 o Added "All CoAP Nodes" multicast addresses to "IANA 5237 Considerations" (#216). 5239 o Over 100 small editorial changes, clarifications and improvements 5240 have been made. 5242 Changed from ietf-08 to ietf-09: 5244 o Improved consistency of statements about RST on NON: RST is a 5245 valid response to a NON message (#183). 5247 o Clarified that the protocol constants can be configured for 5248 specific application environments. 5250 o Added implementation note recommending piggy-backing whenever 5251 possible (#182). 5253 o Added a content-encoding column to the media type registry (#181). 5255 o Minor improvements to Appendix D. 5257 o Added text about multicast response suppression (#177). 5259 o Included the new End-of-options Marker (#176). 5261 o Added a reference to draft-ietf-tls-oob-pubkey and updated the RPK 5262 text accordingly. 5264 Changed from ietf-07 to ietf-08: 5266 o Clarified matching rules for messages (#175) 5267 o Fixed a bug in Section 8.2.2 on Etags (#168) 5269 o Added an IP address spoofing threat analysis contribution (#167) 5271 o Re-focused the security section on raw public keys (#166) 5273 o Added an 4.06 error to Accept (#165) 5275 Changed from ietf-06 to ietf-07: 5277 o application/link-format added to Media types registration (#160) 5279 o Moved content-type attribute to the document from link-format. 5281 o Added coaps scheme and DTLS-secured CoAP default port (#154) 5283 o Allowed 0-length Content-type options (#150) 5285 o Added congestion control recommendations (#153) 5287 o Improved text on PUT/POST response payloads (#149) 5289 o Added an Accept option for content-negotiation (#163) 5291 o Added If-Match and If-None-Match options (#155) 5293 o Improved Token Option explanation (#147) 5295 o Clarified mandatory to implement security (#156) 5297 o Added first come first server policy for 2-byte Media type codes 5298 (#161) 5300 o Clarify matching rules for messages and tokens (#151) 5302 o Changed OPTIONS and TRACE to always return 501 in HTTP-CoAP 5303 mapping (#164) 5305 Changed from ietf-05 to ietf-06: 5307 o HTTP mapping section improved with the minimal protocol standard 5308 text for CoAP-HTTP and HTTP-CoAP forward proxying (#137). 5310 o Eradicated percent-encoding by including one Uri-Query Option per 5311 &-delimited argument in a query. 5313 o Allowed RST message in reply to a NON message with unexpected 5314 token (#135). 5316 o Cache Invalidation only happens upon successful responses (#134). 5318 o 50% jitter added to the initial retransmit timer (#142). 5320 o DTLS cipher suites aligned with ZigBee IP, DTLS clarified as 5321 default CoAP security mechanism (#138, #139) 5323 o Added a minimal reference to draft-kivinen-ipsecme-ikev2-minimal 5324 (#140). 5326 o Clarified the comparison of UTF-8s (#136). 5328 o Minimized the initial media type registry (#101). 5330 Changed from ietf-04 to ietf-05: 5332 o Renamed Immediate into Piggy-backed and Deferred into Separate -- 5333 should finally end the confusion on what this is about. 5335 o GET requests now return a 2.05 (Content) response instead of 2.00 5336 (OK) response (#104). 5338 o Added text to allow 2.02 (Deleted) responses in reply to POST 5339 requests (#105). 5341 o Improved message deduplication rules (#106). 5343 o Section added on message size implementation considerations 5344 (#103). 5346 o Clarification made on human readable error payloads (#109). 5348 o Definition of CoAP methods improved (#108). 5350 o Max-Age removed from requests (#107). 5352 o Clarified uniqueness of tokens (#112). 5354 o Location-Query Option added (#113). 5356 o ETag length set to 1-8 bytes (#123). 5358 o Clarified relation between elective/critical and option numbers 5359 (#110). 5361 o Defined when to update Version header field (#111). 5363 o URI scheme registration improved (#102). 5365 o Added review guidelines for new CoAP codes and numbers. 5367 Changes from ietf-03 to ietf-04: 5369 o Major document reorganization (#51, #63, #71, #81). 5371 o Max-age length set to 0-4 bytes (#30). 5373 o Added variable unsigned integer definition (#31). 5375 o Clarification made on human readable error payloads (#50). 5377 o Definition of POST improved (#52). 5379 o Token length changed to 0-8 bytes (#53). 5381 o Section added on multiplexing CoAP, DTLS and STUN (#56). 5383 o Added cross-protocol attack considerations (#61). 5385 o Used new Immediate/Deferred response definitions (#73). 5387 o Improved request/response matching rules (#74). 5389 o Removed unnecessary media types and added recommendations for 5390 their use in M2M (#76). 5392 o Response codes changed to base 32 coding, new Y.XX naming (#77). 5394 o References updated as per AD review (#79). 5396 o IANA section completed (#80). 5398 o Proxy-Uri Option added to disambiguate between proxy and non-proxy 5399 requests (#82). 5401 o Added text on critical options in cached states (#83). 5403 o HTTP mapping sections improved (#88). 5405 o Added text on reverse proxies (#72). 5407 o Some security text on multicast added (#54). 5409 o Trust model text added to introduction (#58, #60). 5411 o AES-CCM vs. AES-CCB text added (#55). 5413 o Text added about device capabilities (#59). 5415 o DTLS section improvements (#87). 5417 o Caching semantics aligned with RFC2616 (#78). 5419 o Uri-Path Option split into multiple path segments. 5421 o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. 5423 Changes from ietf-02 to ietf-03: 5425 o Token Option and related use in asynchronous requests added (#25). 5427 o CoAP specific error codes added (#26). 5429 o Erroring out on unknown critical options changed to a MUST (#27). 5431 o Uri-Query Option added. 5433 o Terminology and definitions of URIs improved. 5435 o Security section completed (#22). 5437 Changes from ietf-01 to ietf-02: 5439 o Sending an error on a critical option clarified (#18). 5441 o Clarification on behavior of PUT and idempotent operations (#19). 5443 o Use of Uri-Authority clarified along with server processing rules; 5444 Uri-Scheme Option removed (#20, #23). 5446 o Resource discovery section removed to a separate CoRE Link Format 5447 draft (#21). 5449 o Initial security section outline added. 5451 Changes from ietf-00 to ietf-01: 5453 o New cleaner transaction message model and header (#5). 5455 o Removed subscription while being designed (#1). 5457 o Section 2 re-written (#3). 5459 o Text added about use of short URIs (#4). 5461 o Improved header option scheme (#5, #14). 5463 o Date option removed whiled being designed (#6). 5465 o New text for CoAP default port (#7). 5467 o Completed proxying section (#8). 5469 o Completed resource discovery section (#9). 5471 o Completed HTTP mapping section (#10). 5473 o Several new examples added (#11). 5475 o URI split into 3 options (#12). 5477 o MIME type defined for link-format (#13, #16). 5479 o New text on maximum message size (#15). 5481 o Location Option added. 5483 Changes from shelby-01 to ietf-00: 5485 o Removed the TCP binding section, left open for the future. 5487 o Fixed a bug in the example. 5489 o Marked current Sub/Notify as (Experimental) while under WG 5490 discussion. 5492 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 5493 CoAP-CoAP proxying to work). 5495 o Temporarily removed the Magic Byte header as TCP is no longer 5496 included as a binding. 5498 o Removed the Uri-code Option as different URI encoding schemes are 5499 being discussed. 5501 o Changed the rel= field to desc= for resource discovery. 5503 o Changed the maximum message size to 1024 bytes to allow for IP/UDP 5504 headers. 5506 o Made the URI slash optimization and method idempotence MUSTs 5508 o Minor editing and bug fixing. 5510 Changes from shelby-00 to shelby-01: 5512 o Unified the message header and added a notify message type. 5514 o Renamed methods with HTTP names and removed the NOTIFY method. 5516 o Added a number of options field to the header. 5518 o Combines the Option Type and Length into an 8-bit field. 5520 o Added the magic byte header. 5522 o Added new ETag Option. 5524 o Added new Date Option. 5526 o Added new Subscription Option. 5528 o Completed the HTTP Code - CoAP Code mapping table appendix. 5530 o Completed the Content-type Identifier appendix and tables. 5532 o Added more simplifications for URI support. 5534 o Initial subscription and discovery sections. 5536 o A Flag requirements simplified. 5538 Authors' Addresses 5540 Zach Shelby 5541 Sensinode 5542 Kidekuja 2 5543 Vuokatti 88600 5544 Finland 5546 Phone: +358407796297 5547 Email: zach@sensinode.com 5549 Klaus Hartke 5550 Universitaet Bremen TZI 5551 Postfach 330440 5552 Bremen D-28359 5553 Germany 5555 Phone: +49-421-218-63905 5556 Email: hartke@tzi.org 5557 Carsten Bormann 5558 Universitaet Bremen TZI 5559 Postfach 330440 5560 Bremen D-28359 5561 Germany 5563 Phone: +49-421-218-63921 5564 Email: cabo@tzi.org