idnits 2.17.1 draft-ietf-core-coap-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 3657 has weird spacing: '... Client ff02:...' -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: This option is "critical". It MAY NOT occur more than once. -- The document date (November 1, 2011) is 4532 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '0x7d34' is mentioned on line 395, but not defined == Missing Reference: '0x01a0' is mentioned on line 408, but not defined == Missing Reference: '0xbc90' is mentioned on line 448, but not defined == Missing Reference: '0xbc91' is mentioned on line 448, but not defined == Missing Reference: '0x7a10' is mentioned on line 473, but not defined == Missing Reference: '0x23bb' is mentioned on line 484, but not defined == Missing Reference: '0x7a11' is mentioned on line 497, but not defined == Missing Reference: '0x23bc' is mentioned on line 502, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 3227, but not defined == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-07 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4347 (Obsoleted by RFC 6347) ** Obsolete normative reference: RFC 4395 (Obsoleted by RFC 7595) ** Obsolete normative reference: RFC 4492 (Obsoleted by RFC 8422) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 4835 (Obsoleted by RFC 7321) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 5996 (Obsoleted by RFC 7296) == Outdated reference: A later version (-21) exists of draft-ietf-core-block-04 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-17 == Outdated reference: A later version (-01) exists of draft-kivinen-ipsecme-ikev2-minimal-00 == Outdated reference: A later version (-04) exists of draft-mcgrew-tls-aes-ccm-01 Summary: 13 errors (**), 0 flaws (~~), 17 warnings (==), 2 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: May 4, 2012 C. Bormann 6 Universitaet Bremen TZI 7 B. Frank 8 SkyFoundry 9 November 1, 2011 11 Constrained Application Protocol (CoAP) 12 draft-ietf-core-coap-08 14 Abstract 16 This document specifies the Constrained Application Protocol (CoAP), 17 a specialized web transfer protocol for use with constrained networks 18 and nodes for machine-to-machine applications such as smart energy 19 and building automation. These constrained nodes often have 8-bit 20 microcontrollers with small amounts of ROM and RAM, while networks 21 such as 6LoWPAN often have high packet error rates and a typical 22 throughput of 10s of kbit/s. CoAP provides a method/response 23 interaction model between application end-points, supports built-in 24 resource discovery, and includes key web concepts such as URIs and 25 content-types. CoAP easily translates to HTTP for integration with 26 the web while meeting specialized requirements such as multicast 27 support, very low overhead and simplicity for constrained 28 environments. 30 Status of this Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on May 4, 2012. 47 Copyright Notice 48 Copyright (c) 2011 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 66 2. Constrained Application Protocol . . . . . . . . . . . . . . . 8 67 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 8 68 2.2. Request/Response Model . . . . . . . . . . . . . . . . . . 10 69 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . . 12 70 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . . 12 71 3. Message Syntax . . . . . . . . . . . . . . . . . . . . . . . . 12 72 3.1. Message Format . . . . . . . . . . . . . . . . . . . . . . 13 73 3.1.1. Message Size Implementation Considerations . . . . . 14 74 3.2. Option Format . . . . . . . . . . . . . . . . . . . . . . 15 75 4. Message Semantics . . . . . . . . . . . . . . . . . . . . . . 16 76 4.1. Reliable Messages . . . . . . . . . . . . . . . . . . . . 17 77 4.2. Unreliable Messages . . . . . . . . . . . . . . . . . . . 18 78 4.3. Message Matching Rules . . . . . . . . . . . . . . . . . . 19 79 4.4. Message Types . . . . . . . . . . . . . . . . . . . . . . 19 80 4.4.1. Confirmable (CON) . . . . . . . . . . . . . . . . . . 19 81 4.4.2. Non-Confirmable (NON) . . . . . . . . . . . . . . . . 20 82 4.4.3. Acknowledgement (ACK) . . . . . . . . . . . . . . . . 20 83 4.4.4. Reset (RST) . . . . . . . . . . . . . . . . . . . . . 20 84 4.5. Multicast . . . . . . . . . . . . . . . . . . . . . . . . 20 85 4.6. Congestion Control . . . . . . . . . . . . . . . . . . . . 20 86 5. Request/Response Semantics . . . . . . . . . . . . . . . . . . 21 87 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . . 21 88 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 22 89 5.2.1. Piggy-backed . . . . . . . . . . . . . . . . . . . . 23 90 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 23 91 5.2.3. Non-Confirmable . . . . . . . . . . . . . . . . . . . 24 92 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 24 93 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 25 94 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 26 95 5.4.2. Length . . . . . . . . . . . . . . . . . . . . . . . 26 96 5.4.3. Default Values . . . . . . . . . . . . . . . . . . . 27 97 5.4.4. Repeating Options . . . . . . . . . . . . . . . . . . 27 98 5.4.5. Option Numbers . . . . . . . . . . . . . . . . . . . 27 99 5.5. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 27 100 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 28 101 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 29 102 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 29 103 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 29 104 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . . 31 105 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 31 106 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 31 107 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 31 108 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 32 109 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 32 110 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 32 111 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 33 112 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 35 113 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . . 36 114 5.10.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 36 115 5.10.2. Uri-Host, Uri-Port, Uri-Path and Uri-Query . . . . . 37 116 5.10.3. Proxy-Uri . . . . . . . . . . . . . . . . . . . . . . 38 117 5.10.4. Content-Type . . . . . . . . . . . . . . . . . . . . 38 118 5.10.5. Accept . . . . . . . . . . . . . . . . . . . . . . . 38 119 5.10.6. Max-Age . . . . . . . . . . . . . . . . . . . . . . . 39 120 5.10.7. ETag . . . . . . . . . . . . . . . . . . . . . . . . 39 121 5.10.8. Location-Path and Location-Query . . . . . . . . . . 40 122 5.10.9. If-Match . . . . . . . . . . . . . . . . . . . . . . 40 123 5.10.10. If-None-Match . . . . . . . . . . . . . . . . . . . . 41 124 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 41 125 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 41 126 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . . 42 127 6.3. Normalization and Comparison Rules . . . . . . . . . . . . 42 128 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 43 129 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 44 130 7. Finding and Addressing CoAP End-Points . . . . . . . . . . . . 45 131 7.1. Resource Discovery . . . . . . . . . . . . . . . . . . . . 45 132 7.1.1. Content-type code 'ct' attribute . . . . . . . . . . 46 133 7.2. Default Ports . . . . . . . . . . . . . . . . . . . . . . 46 134 8. HTTP Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 46 135 8.1. CoAP-HTTP Mapping . . . . . . . . . . . . . . . . . . . . 47 136 8.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 48 137 8.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 48 138 8.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 48 139 8.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 49 140 8.2. HTTP-CoAP Mapping . . . . . . . . . . . . . . . . . . . . 49 141 8.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . . 49 142 8.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . . 49 143 8.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 50 144 8.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 50 145 8.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 51 146 8.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 51 147 8.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 51 148 9. Protocol Constants . . . . . . . . . . . . . . . . . . . . . . 51 149 10. Security Considerations . . . . . . . . . . . . . . . . . . . 52 150 10.1. Securing CoAP with DTLS . . . . . . . . . . . . . . . . . 53 151 10.1.1. PreSharedKey Mode . . . . . . . . . . . . . . . . . . 54 152 10.1.2. RawPublicKey Mode . . . . . . . . . . . . . . . . . . 54 153 10.1.3. Certificate Mode . . . . . . . . . . . . . . . . . . 54 154 10.2. Using CoAP with IPsec . . . . . . . . . . . . . . . . . . 55 155 10.3. Threat analysis and protocol limitations . . . . . . . . . 56 156 10.3.1. Protocol Parsing, Processing URIs . . . . . . . . . . 56 157 10.3.2. Proxying and Caching . . . . . . . . . . . . . . . . 57 158 10.3.3. Risk of amplification . . . . . . . . . . . . . . . . 57 159 10.3.4. IP Address Spoofing Attacks . . . . . . . . . . . . . 58 160 10.3.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . 59 161 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 162 11.1. CoAP Code Registry . . . . . . . . . . . . . . . . . . . . 61 163 11.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 61 164 11.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 62 165 11.2. Option Number Registry . . . . . . . . . . . . . . . . . . 63 166 11.3. Media Type Registry . . . . . . . . . . . . . . . . . . . 65 167 11.4. URI Scheme Registration . . . . . . . . . . . . . . . . . 66 168 11.5. Secure URI Scheme Registration . . . . . . . . . . . . . . 67 169 11.6. Service Name and Port Number Registration . . . . . . . . 68 170 11.7. Secure Service Name and Port Number Registration . . . . . 68 171 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 69 172 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 69 173 13.1. Normative References . . . . . . . . . . . . . . . . . . . 69 174 13.2. Informative References . . . . . . . . . . . . . . . . . . 72 175 Appendix A. Integer Option Value Format . . . . . . . . . . . . . 73 176 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 73 177 Appendix C. URI Examples . . . . . . . . . . . . . . . . . . . . 79 178 Appendix D. Security Provisioning and Access Control . . . . . . 80 179 D.1. RawPublicKey Identity . . . . . . . . . . . . . . . . . . 81 180 D.2. Provisioning . . . . . . . . . . . . . . . . . . . . . . . 81 181 D.3. Access Control . . . . . . . . . . . . . . . . . . . . . . 81 182 D.3.1. PreSharedKey Mode . . . . . . . . . . . . . . . . . . 81 183 D.3.2. RawPublicKey Mode . . . . . . . . . . . . . . . . . . 81 184 D.3.3. Certificate Mode . . . . . . . . . . . . . . . . . . 82 185 Appendix E. Changelog . . . . . . . . . . . . . . . . . . . . . . 82 186 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 88 188 1. Introduction 190 The use of web services on the Internet has become ubiquitous in most 191 applications, and depends on the fundamental Representational State 192 Transfer (REST) architecture of the web. 194 The Constrained RESTful Environments (CoRE) working group aims at 195 realizing the REST architecture in a suitable form for the most 196 constrained nodes (e.g. 8-bit microcontrollers with limited RAM and 197 ROM) and networks (e.g. 6LoWPAN). Constrained networks like 6LoWPAN 198 support the expensive fragmentation of IPv6 packets into small link- 199 layer frames. One design goal of CoAP has been to keep message 200 overhead small, thus limiting the use of fragmentation. 202 One of the main goals of CoAP is to design a generic web protocol for 203 the special requirements of this constrained environment, especially 204 considering energy, building automation and other M2M applications. 205 The goal of CoAP is not to blindly compress HTTP [RFC2616], but 206 rather to realize a subset of REST common with HTTP but optimized for 207 M2M applications. Although CoAP could be used for compressing simple 208 HTTP interfaces, it more importantly also offers features for M2M 209 such as built-in discovery, multicast support and asynchronous 210 message exchanges. 212 This document specifies the Constrained Application Protocol (CoAP), 213 which easily translates to HTTP for integration with the existing web 214 while meeting specialized requirements such as multicast support, 215 very low overhead and simplicity for constrained environments and M2M 216 applications. 218 1.1. Features 220 CoAP has the following main features: 222 o Constrained web protocol fulfilling M2M requirements. 224 o UDP binding with optional reliability supporting unicast and 225 multicast requests. 227 o Asynchronous message exchanges. 229 o Low header overhead and parsing complexity. 231 o URI and Content-type support. 233 o Simple proxy and caching capabilities. 235 o A stateless HTTP mapping, allowing proxies to be built providing 236 access to CoAP resources via HTTP in a uniform way or for HTTP 237 simple interfaces to be realized alternatively over CoAP. 239 o Security binding to Datagram Transport Layer Security (DTLS). 241 1.2. Terminology 243 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 244 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 245 document are to be interpreted as described in [RFC2119]. 247 This specification requires readers to be familiar with all the terms 248 and concepts that are discussed in [RFC2616]. In addition, this 249 specification defines the following terminology: 251 Piggy-backed Response 252 A Piggy-backed Response is included right in a CoAP 253 Acknowledgement (ACK) message that is sent to acknowledge receipt 254 of the Request for this Response (Section 5.2.1). 256 Separate Response 257 When a Confirmable message carrying a Request is acknowledged with 258 an empty message (e.g., because the server doesn't have the answer 259 right away), a Separate Response is sent in a separate message 260 exchange (Section 5.2.2). 262 Critical Option 263 An option that would need to be understood by the end-point 264 receiving the message in order to properly process the message 265 (Section 5.4.1). Note that the implementation of critical options 266 is, as the name "Option" implies, generally optional: unsupported 267 critical options lead to rejection of the message. 269 Elective Option 270 An option that is intended be ignored by an end-point that does 271 not understand it, which nonetheless still can correctly process 272 the message (Section 5.4.1). 274 Resource Discovery 275 The process where a CoAP client queries a server for its list of 276 hosted resources (i.e., links, Section 7.1). 278 End-Point 279 An entity participating in the CoAP protocol. Colloquially, a 280 synonym is "Node", although "Host" would be more consistent with 281 Internet standards usage. 283 Sender 284 The originating end-point of a message. 286 Recipient 287 The destination end-point of a message. 289 Client 290 The originating end-point of a request; the destination end-point 291 of a response. 293 Server 294 The destination end-point of a request; the originating end-point 295 of a response. 297 Origin Server 298 The server on which a given resource resides or is to be created. 300 Intermediary 301 A CoAP end-point that acts both as a server and as a client 302 towards (possibly via further intermediaries) an origin server. 303 There are two common forms of intermediary: proxy and reverse 304 proxy. In some cases, a single end-point might act as an origin 305 server, proxy, or reverse proxy, switching behavior based on the 306 nature of each request. 308 Proxy 309 A "proxy" is an end-point selected by a client, usually via local 310 configuration rules, to perform requests on behalf of the client, 311 doing any necessary translations. Some translations are minimal, 312 such as for proxy requests for "coap" URIs, whereas other requests 313 might require translation to and from entirely different 314 application-layer protocols. 316 Reverse Proxy 317 A "reverse proxy" is an end-point that acts as a layer above some 318 other server(s) and satisfies requests on behalf of these, doing 319 any necessary translations. Unlike a proxy, a reverse proxy 320 receives requests as if it was the origin server for the target 321 resource; the requesting client will not be aware that it is 322 communicating with a reverse proxy. 324 In this specification, the term "byte" is used in its now customary 325 sense as a synonym for "octet". 327 In this specification, the operator "^" stands for exponentiation. 329 2. Constrained Application Protocol 331 The interaction model of CoAP is similar to the client/server model 332 of HTTP. However, machine-to-machine interactions typically result 333 in a CoAP implementation acting in both client and server roles 334 (called an end-point). A CoAP request is equivalent to that of HTTP, 335 and is sent by a client to request an action (using a method code) on 336 a resource (identified by a URI) on a server. The server then sends 337 a response with a response code; this response may include a resource 338 representation. 340 Unlike HTTP, CoAP deals with these interchanges asynchronously over a 341 datagram-oriented transport such as UDP. This is done logically 342 using a layer of messages that supports optional reliability (with 343 exponential back-off). CoAP defines four types of messages: 344 Confirmable, Non-Confirmable, Acknowledgement, Reset; method codes 345 and response codes included in some of these messages make them carry 346 requests or responses. The basic exchanges of the four types of 347 messages are transparent to the request/response interactions. 349 One could think of CoAP logically as using a two-layer approach, a 350 CoAP messaging layer used to deal with UDP and the asynchronous 351 nature of the interactions, and the request/response interactions 352 using Method and Response codes (see Figure 1). CoAP is however a 353 single protocol, with messaging and request/response just features of 354 the CoAP header. 356 +----------------------+ 357 | Application | 358 +----------------------+ 359 +----------------------+ 360 | Requests/Responses | 361 |----------------------| CoAP 362 | Messages | 363 +----------------------+ 364 +----------------------+ 365 | UDP | 366 +----------------------+ 368 Figure 1: Abstract layering of CoAP 370 2.1. Messaging Model 372 The CoAP messaging model is based on the exchange of messages over 373 UDP between end-points. 375 CoAP uses a short fixed-length binary header (4 bytes) that may be 376 followed by compact binary options and a payload. This message 377 format is shared by requests and responses. The CoAP message format 378 is specified in Section 3. Each message contains a Message ID used 379 to detect duplicates and for optional reliability. 381 Reliability is provided by marking a message as Confirmable (CON). A 382 Confirmable message is retransmitted using a default timeout and 383 exponential back-off between retransmissions, until the recipient 384 sends an Acknowledgement message (ACK) with the same Message ID (for 385 example, 0x7d34) from the corresponding end-point; see Figure 2. 386 When a recipient is not able to process a Confirmable message, it 387 replies with a Reset message (RST) instead of an Acknowledgement 388 (ACK). 390 Client Server 391 | | 392 | CON [0x7d34] | 393 +----------------->| 394 | | 395 | ACK [0x7d34] | 396 |<-----------------+ 397 | | 399 Figure 2: Reliable message delivery 401 A message that does not require reliable delivery, for example each 402 single measurement out of a stream of sensor data, can be sent as a 403 Non-confirmable message (NON). These are not acknowledged, but still 404 have a Message ID for duplicate detection; see Figure 3. 406 Client Server 407 | | 408 | NON [0x01a0] | 409 +----------------->| 410 | | 412 Figure 3: Unreliable message delivery 414 See Section 4 for details of CoAP messages. 416 As CoAP is based on UDP, it also supports the use of multicast IP 417 destination addresses, enabling multicast CoAP requests. Section 4.5 418 discusses the proper use of CoAP messages with multicast addresses 419 and precautions for avoiding response congestion. 421 Several security modes are defined for CoAP in Section 10 ranging 422 from no security to certificate-based security. The use of IPsec 423 along with a binding to DTLS are specified for securing the protocol. 425 2.2. Request/Response Model 427 CoAP request and response semantics are carried in CoAP messages, 428 which include either a method code or response code, respectively. 429 Optional (or default) request and response information, such as the 430 URI and payload content-type are carried as CoAP options. A Token 431 Option is used to match responses to requests independently from the 432 underlying messages (Section 5.3). 434 A request is carried in a Confirmable (CON) or Non-confirmable (NON) 435 message, and if immediately available, the response to a request 436 carried in a Confirmable message is carried in the resulting 437 Acknowledgement (ACK) message. This is called a piggy-backed 438 response, detailed in Section 5.2.1. Two examples for a basic GET 439 request with piggy-backed response are shown in Figure 4. 441 Client Server Client Server 442 | | | | 443 | CON [0xbc90] | | CON [0xbc91] | 444 | GET /temperature | | GET /temperature | 445 | (Token 0x71) | | (Token 0x72) | 446 +----------------->| +----------------->| 447 | | | | 448 | ACK [0xbc90] | | ACK [0xbc91] | 449 | 2.05 Content | | 4.04 Not Found | 450 | (Token 0x71) | | (Token 0x72) | 451 | "22.5 C" | | "Not found" | 452 |<-----------------+ |<-----------------+ 453 | | | | 455 Figure 4: Two GET requests with piggy-backed responses, one 456 successful, one not found 458 If the server is not able to respond immediately to a request carried 459 in a Confirmable message, it simply responds with an empty 460 Acknowledgement message so that the client can stop retransmitting 461 the request. When the response is ready, the server sends it in a 462 new Confirmable message (which then in turn needs to be acknowledged 463 by the client). This is called a separate response, as illustrated 464 in Figure 5 and described in more detail in Section 5.2.2. 466 Client Server 467 | | 468 | CON [0x7a10] | 469 | GET /temperature | 470 | (Token 0x73) | 471 +----------------->| 472 | | 473 | ACK [0x7a10] | 474 |<-----------------+ 475 | | 476 ... Time Passes ... 477 | | 478 | CON [0x23bb] | 479 | 2.05 Content | 480 | (Token 0x73) | 481 | "22.5 C" | 482 |<-----------------+ 483 | | 484 | ACK [0x23bb] | 485 +----------------->| 486 | | 488 Figure 5: A GET request with a separate response 490 Likewise, if a request is sent in a Non-Confirmable message, then the 491 response is usually sent using a new Non-Confirmable message, 492 although the server may send a Confirmable message. This type of 493 exchange is illustrated in Figure 6. 495 Client Server 496 | | 497 | NON [0x7a11] | 498 | GET /temperature | 499 | (Token 0x74) | 500 +----------------->| 501 | | 502 | NON [0x23bc] | 503 | 2.05 Content | 504 | (Token 0x74) | 505 | "22.5 C" | 506 |<-----------------+ 507 | | 509 Figure 6: A NON request and response 511 CoAP makes use of GET, PUT, POST and DELETE methods in a similar 512 manner to HTTP, with the semantics specified in Section 5.8. (Note 513 that the detailed semantics of CoAP methods are "almost, but not 514 entirely unlike" those of HTTP methods: Intuition taken from HTTP 515 experience generally does apply well, but there are enough 516 differences that make it worthwhile to actually read the present 517 specification.) 519 URI support in a server is simplified as the client already parses 520 the URI and splits it into host, port, path and query components, 521 making use of default values for efficiency. Response codes 522 correspond to a small subset of HTTP response codes with a few CoAP 523 specific codes added, as defined in Section 5.9. 525 2.3. Intermediaries and Caching 527 The protocol supports the caching of responses in order to 528 efficiently fulfill requests. Simple caching is enabled using 529 freshness and validity information carried with CoAP responses. A 530 cache could be located in an end-point or an intermediary. Caching 531 functionality is specified in Section 5.6. 533 Proxying is useful in constrained networks for several reasons, 534 including network traffic limiting, to improve performance, to access 535 resources of sleeping devices or for security reasons. The proxying 536 of requests on behalf of another CoAP end-point is supported in the 537 protocol. The URI of the resource to request is included in the 538 request, while the destination IP address is set to the proxy. See 539 Section 5.7 for more information on proxy functionality. 541 As CoAP was designed according to the REST architecture and thus 542 exhibits functionality similar to that of the HTTP protocol, it is 543 quite straightforward to map between HTTP-CoAP or CoAP-HTTP. Such a 544 mapping may be used to realize an HTTP REST interface using CoAP, or 545 for converting between HTTP and CoAP. This conversion can be carried 546 out by a proxy, which converts the method or response code, content- 547 type and options to the corresponding HTTP feature. Section 8 548 provides more detail about HTTP mapping. 550 2.4. Resource Discovery 552 Resource discovery is important for machine-to-machine interactions, 553 and is supported using the CoRE Link Format 554 [I-D.ietf-core-link-format] as discussed in Section 7.1. 556 3. Message Syntax 558 CoAP is based on the exchange of short messages which, by default, 559 are transported over UDP (i.e. each CoAP message occupies the data 560 section of one UDP datagram). CoAP may be used with Datagram 561 Transport Layer Security (DTLS) (see Section 10.1). It could also be 562 used over other transports such as TCP or SCTP, the specification of 563 which is out of this document's scope. 565 3.1. Message Format 567 CoAP messages are encoded in a simple binary format. A message 568 consists of a fixed-sized CoAP Header followed by options in Type- 569 Length-Value (TLV) format and a payload. The number of options is 570 determined by the header. The payload is made up of the bytes after 571 the options, if any; its length is calculated from the datagram 572 length. 574 0 1 2 3 575 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 576 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 577 |Ver| T | OC | Code | Message ID | 578 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 579 | Options (if any) ... 580 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 581 | Payload (if any) ... 582 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 584 Figure 7: Message Format 586 The fields in the header are defined as follows: 588 Version (Ver): 2-bit unsigned integer. Indicates the CoAP version 589 number. Implementations of this specification MUST set this field 590 to 1. Other values are reserved for future versions. 592 Type (T): 2-bit unsigned integer. Indicates if this message is of 593 type Confirmable (0), Non-Confirmable (1), Acknowledgement (2) or 594 Reset (3). See Section 4 for the semantics of these message 595 types. 597 Option Count (OC): 4-bit unsigned integer. Indicates the number of 598 options after the header. If set to 0, there are no options and 599 the payload (if any) immediately follows the header. The format 600 of options is defined below. 602 Code: 8-bit unsigned integer. Indicates if the message carries a 603 request (1-31) or a response (64-191), or is empty (0). (All 604 other code values are reserved.) In case of a request, the Code 605 field indicates the Request Method; in case of a response a 606 Response Code. Possible values are maintained in the CoAP Code 607 Registry (Section 11.1). See Section 5 for the semantics of 608 requests and responses. 610 Message ID: 16-bit unsigned integer. Used for the detection of 611 message duplication, and to match messages of type 612 Acknowledgement/Reset and messages of type Confirmable. See 613 Section 4 for Message ID generation rules and how messages are 614 matched. 616 While specific link layers make it beneficial to keep CoAP messages 617 small enough to fit into their link layer packets (see Section 1), 618 this is a matter of implementation quality. The CoAP specification 619 itself provides only an upper bound to the message size. Messages 620 larger than an IP fragment result in undesired packet fragmentation. 621 A CoAP message, appropriately encapsulated, SHOULD fit within a 622 single IP packet (i.e., avoid IP fragmentation) and MUST fit within a 623 single IP datagram. If the Path MTU is not known for a destination, 624 an IP MTU of 1280 bytes SHOULD be assumed; if nothing is known about 625 the size of the headers, good upper bounds are 1152 bytes for the 626 message size and 1024 bytes for the payload size. 628 3.1.1. Message Size Implementation Considerations 630 Note that CoAP's choice of message size parameters works well with 631 IPv6 and with most of today's IPv4 paths. (However, with IPv4, it is 632 harder to absolutely ensure that there is no IP fragmentation. If 633 IPv4 support on unusual networks is a consideration, implementations 634 may want to limit themselves to more conservative IPv4 datagram sizes 635 such as 576 bytes; worse, the absolute minimum value of the IP MTU 636 for IPv4 is as low as 68 bytes, which would leave only 40 bytes minus 637 security overhead for a UDP payload. Implementations extremely 638 focused on this problem set might also set the IPv4 DF bit and 639 perform some form of path MTU discovery; this should generally be 640 unnecessary in most realistic use cases for CoAP, however.) A more 641 important kind of fragmentation in many constrained networks is that 642 on the adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 643 bytes including various overheads); this may motivate implementations 644 to be frugal in their packet sizes and to move to block-wise 645 transfers [I-D.ietf-core-block] when approaching three-digit message 646 sizes. 648 Note that message sizes are also of considerable importance to 649 implementations on constrained nodes. Many implementations will need 650 to allocate a buffer for incoming messages. If an implementation is 651 too constrained to allow for allocating the above-mentioned upper 652 bound, it could apply the following implementation strategy: 653 Implementations receiving a datagram into a buffer that is too small 654 are usually able to determine if the trailing portion of a datagram 655 was discarded and to retrieve the initial portion. So, if not all of 656 the payload, at least the CoAP header and options are likely to fit 657 within the buffer. A server can thus fully interpret a request and 658 return a 4.13 (Request Entity Too Large) response code if the payload 659 was truncated. A client sending an idempotent request and receiving 660 a response larger than would fit in the buffer can repeat the request 661 with a suitable value for the Block Option [I-D.ietf-core-block]. 663 3.2. Option Format 665 Options MUST appear in order of their Option Number (see 666 Section 5.4.5). A delta encoding is used between options, with the 667 Option Number for each Option calculated as the sum of its Option 668 Delta field and the Option Number of the preceding Option in the 669 message, if any, or zero otherwise. Multiple options with the same 670 Option Number can be included by using an Option Delta of zero. 671 Following the Option Delta, each option has a Length field which 672 specifies the length of the Option Value, in bytes. The Length field 673 can be extended by one byte for options with values longer than 14 674 bytes. The Option Value immediately follows the Length field. 676 0 1 2 3 4 5 6 7 677 +---+---+---+---+---+---+---+---+ 678 | Option Delta | Length | for 0..14 679 +---+---+---+---+---+---+---+---+ 680 | Option Value ... 681 +---+---+---+---+---+---+---+---+ 682 for 15..270: 683 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 684 | Option Delta | 1 1 1 1 | Length - 15 | 685 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 686 | Option Value ... 687 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ 689 Figure 8: Option Format 691 The fields in an option are defined as follows: 693 Option Delta: 4-bit unsigned integer. Indicates the difference 694 between the Option Number of this option and the previous option 695 (or zero for the first option). In other words, the Option Number 696 is calculated by simply summing the Option Delta fields of this 697 and previous options before it. The Option Numbers 14, 28, 42, 698 ... are reserved for no-op options when they are sent with an 699 empty value (they are ignored) and can be used as "fenceposts" if 700 deltas larger than 15 would otherwise be required. 702 Length: Indicates the length of the Option Value, in bytes. 703 Normally Length is a 4-bit unsigned integer allowing value lengths 704 of 0-14 bytes. When the Length field is set to 15, another byte 705 is added as an 8-bit unsigned integer whose value is added to the 706 15, allowing option value lengths of 15-270 bytes. 708 The length and format of the Option Value depends on the respective 709 option, which MAY define variable length values. Options defined in 710 this document make use of the following formats for option values: 712 uint: A non-negative integer which is represented in network byte 713 order using a variable number of bytes (see Appendix A). 715 string: A Unicode string which is encoded using UTF-8 [RFC3629] in 716 Net-Unicode form [RFC5198]. Note that here and in all other 717 places where UTF-8 encoding is used in the CoAP protocol, the 718 intention is that the encoded strings can be directly used and 719 compared as opaque byte strings by CoAP protocol 720 implementations. There is no expectation and no need to 721 perform normalization within a CoAP implementation unless 722 Unicode strings that are not known to be normalized are 723 imported from sources outside the CoAP protocol. Note also 724 that ASCII strings (that do not make use of special control 725 characters) are always valid UTF-8 Net-Unicode strings. 727 opaque: An opaque sequence of bytes. 729 Option Numbers are maintained in the CoAP Option Number Registry 730 (Section 11.2). See Section 5.10 for the semantics of the options 731 defined in this document. 733 4. Message Semantics 735 CoAP messages are exchanged asynchronously between CoAP end-points. 736 They are used to transport CoAP requests and responses, the semantics 737 of which are defined in Section 5. 739 As CoAP is bound to non-reliable transports such as UDP, CoAP 740 messages may arrive out of order, appear duplicated, or go missing 741 without notice. For this reason, CoAP implements a lightweight 742 reliability mechanism, without trying to re-create the full feature 743 set of a transport like TCP. It has the following features: 745 o Simple stop-and-wait retransmission reliability with exponential 746 back-off for "confirmable" messages. 748 o Duplicate detection for both "confirmable" and "non-confirmable" 749 messages. 751 o Multicast support. 753 4.1. Reliable Messages 755 The reliable transmission of a message is initiated by marking the 756 message as "confirmable" in the CoAP header. A recipient MUST 757 acknowledge such a message with an acknowledgement message (or, if it 758 lacks context to process the message properly, MUST reject it with a 759 reset message). The sender retransmits the confirmable message at 760 exponentially increasing intervals, until it receives an 761 acknowledgement (or reset message), or runs out of attempts. 763 Retransmission is controlled by two things that a CoAP end-point MUST 764 keep track of for each confirmable message it sends while waiting for 765 an acknowledgement (or reset): a timeout and a retransmission 766 counter. For a new confirmable message, the initial timeout is set 767 to a random number between RESPONSE_TIMEOUT and (RESPONSE_TIMEOUT * 768 RESPONSE_RANDOM_FACTOR), and the retransmission counter is set to 0. 769 When the timeout is triggered and the retransmission counter is less 770 than MAX_RETRANSMIT, the message is retransmitted, the retransmission 771 counter is incremented, and the timeout is doubled. If the 772 retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the 773 end-point receives a reset message, then the attempt to transmit the 774 message is canceled and the application process informed of failure. 775 On the other hand, if the end-point receives an acknowledgement 776 message in time, transmission is considered successful. 778 An acknowledgement or reset message is related to a confirmable 779 message by means of a Message ID along with additional address 780 information of the corresponding end-point as described in 781 Section 4.3. The Message ID is a 16-bit unsigned integer that is 782 generated by the sender of a confirmable message and included in the 783 CoAP header. The Message ID MUST be echoed in the acknowledgement or 784 reset message by the recipient. 786 Several implementation strategies can be employed for generating 787 Message IDs. In the simplest case a CoAP end-point generates Message 788 IDs by keeping a single Message ID variable, which is changed each 789 time a new confirmable message is sent regardless of the destination 790 address or port. End-points dealing with large numbers of 791 transactions could keep multiple Message ID variables, for example 792 per prefix or destination address. The initial variable value SHOULD 793 be randomized. The same Message ID MUST NOT be re-used (per Message 794 ID variable) within the potential retransmission window, calculated 795 as RESPONSE_TIMEOUT * RESPONSE_RANDOM_FACTOR * (2 ^ MAX_RETRANSMIT - 796 1) plus the expected maximum round trip time. 798 A recipient MUST be prepared to receive the same confirmable message 799 (as indicated by the Message ID and additional address information of 800 the corresponding end-point as described in Section 4.3) multiple 801 times, for example, when its acknowledgement went missing or didn't 802 reach the original sender before the first timeout. The recipient 803 SHOULD acknowledge each duplicate copy of a confirmable message using 804 the same acknowledgement or reset message, but SHOULD process any 805 request or response in the message only once. This rule MAY be 806 relaxed in case the confirmable message transports a request that is 807 idempotent (see Section 5.1). Examples for relaxed message 808 deduplication: 810 o A server MAY relax the requirement to answer all retransmissions 811 of an idempotent request with the same response (Section 4.1), so 812 that it does not have to maintain state for Message IDs. For 813 example, an implementation might want to process duplicate 814 transmissions of a GET, PUT or DELETE request as separate requests 815 if the effort incurred by duplicate processing is less expensive 816 than keeping track of previous responses would be. 818 o (As an implementation consideration, a constrained server MAY even 819 want to relax this requirement for certain non-idempotent requests 820 if the application semantics make this trade-off favorable. For 821 example, if the result of a POST request is just the creation of 822 some short-lived state at the server, it may be less expensive to 823 incur this effort multiple times for a request than keeping track 824 of whether a previous transmission of the same request already was 825 processed.) 827 Implementation notes: Note that a CoAP end-point that sent a 828 confirmable message MAY give up in attempting to obtain an ACK even 829 before the MAX_RETRANSMIT counter value is reached: E.g., the 830 application has canceled the request as it no longer needs a 831 response, or there is some other indication that the CON message did 832 arrive. In particular, a CoAP request message may have elicited a 833 separate response, in which case it is clear to the requester that 834 only the ACK was lost and a retransmission of the request would serve 835 no purpose. However, a responder MUST NOT in turn rely on this 836 cross-layer behavior from a requester, i.e. it SHOULD retain the 837 state to create the ACK for the request, if needed, even if a 838 confirmable response was already acknowledged by the requester. 840 4.2. Unreliable Messages 842 As a more lightweight alternative, a message can be transmitted less 843 reliably by marking the message as "non-confirmable". A non- 844 confirmable message MUST NOT be acknowledged by the recipient. If a 845 recipient lacks context to process the message properly, it MAY 846 reject the message with a reset message or otherwise MUST silently 847 ignore it. 849 There is no way to detect if a non-confirmable message was received 850 or not at the CoAP-level. A sender MAY choose to transmit a non- 851 confirmable message multiple times which, for this purpose, specifies 852 a Message ID as well. The same rules for generating the Message ID 853 apply. 855 A recipient MUST be prepared to receive the same non-confirmable 856 message (as indicated by the Message ID and source address 857 information) multiple times. As a general rule that may be relaxed 858 based on the specific semantics of a message, the recipient SHOULD 859 silently ignore any duplicated non-confirmable message, and SHOULD 860 process any request or response in the message only once. 862 4.3. Message Matching Rules 864 The exact rules for matching an ACK or RST to a CON message or a RST 865 to a NON message are as follows. The Message ID of the response MUST 866 match that of the original message. For unicast messages, the source 867 of the response MUST match the destination of the original message. 868 How this is determined depends on the security mode used (see 869 Section 10): With NoSec, the IP address and port number of the 870 message destination and response source must match. With other 871 security modes, in addition to the IP address and UDP port matching, 872 the request and response MUST have the same security context. 874 4.4. Message Types 876 The different types of messages are summarized below. The type of a 877 message is specified by the T field of the CoAP header. 879 Separate from the message type, a message may carry a request, a 880 response, or be empty. This is signaled by the Code field in the 881 CoAP header and is relevant to the request/response model. Possible 882 values for the Code field are maintained by the CoAP Code Registry 883 (Section 11.1). 885 An empty message has the Code field set to 0. The OC field SHOULD be 886 set to 0 and no bytes SHOULD be present after the Message ID field. 887 The OC field and any bytes trailing the header MUST be ignored by any 888 recipient. 890 4.4.1. Confirmable (CON) 892 Some messages require an acknowledgement. These messages are called 893 "Confirmable". When no packets are lost, each confirmable message 894 elicits exactly one return message of type Acknowledgement or type 895 Reset. 897 A confirmable message always carries either a request or response and 898 MUST NOT be empty. 900 4.4.2. Non-Confirmable (NON) 902 Some other messages do not require an acknowledgement. This is 903 particularly true for messages that are repeated regularly for 904 application requirements, such as repeated readings from a sensor 905 where eventual arrival is sufficient. 907 A non-confirmable message always carries either a request or 908 response, as well, and MUST NOT be empty. 910 4.4.3. Acknowledgement (ACK) 912 An Acknowledgement message acknowledges that a specific confirmable 913 message (identified by its Message ID) arrived. It does not indicate 914 success or failure of any encapsulated request. 916 The acknowledgement message MUST echo the Message ID of the 917 confirmable message, and MUST carry a response or be empty (see 918 Section 5.2.1 and Section 5.2.2). 920 4.4.4. Reset (RST) 922 A Reset message indicates that a specific confirmable message was 923 received, but some context is missing to properly process it. This 924 condition is usually caused when the receiving node has rebooted and 925 has forgotten some state that would be required to interpret the 926 message. 928 A reset message MUST echo the Message ID of the confirmable message, 929 and MUST be empty. 931 4.5. Multicast 933 CoAP supports sending messages to multicast destination addresses. 934 Such multicast messages MUST be Non-Confirmable. Some mechanisms for 935 avoiding congestion from multicast requests have been considered in 936 [I-D.eggert-core-congestion-control]. 938 4.6. Congestion Control 940 Basic congestion control for CoAP is provided by the exponential 941 back-off mechanism in Section 4.1. 943 In order not to cause congestion, Clients (including proxies) SHOULD 944 strictly limit the number of simultaneous outstanding interactions 945 that they maintain to a given server (including proxies). An 946 outstanding interaction is either a CON for which an ACK has not yet 947 been received but is still expected (message layer) or a request for 948 which a response has not yet been received but is still expected 949 (which may both occur at the same time, counting as one outstanding 950 interaction). A good value for this limit is the number 1. (Note 951 that [RFC2616], in trying to achieve a similar objective, did specify 952 a specific number of simultaneous connections as a ceiling. While 953 revising [RFC2616], this was found to be impractical for many 954 applications [I-D.ietf-httpbis-p1-messaging]. For the same 955 considerations, this specification does not mandate a particular 956 maximum number of outstanding interactions, but instead encourages 957 clients to be conservative when initiating interactions.) 959 Further congestion control optimizations and considerations are 960 expected in the future, which may for example provide automatic 961 initialization of the CoAP constants defined in Section 9. 963 5. Request/Response Semantics 965 CoAP operates under a similar request/response model as HTTP: a CoAP 966 end-point in the role of a "client" sends one or more CoAP requests 967 to a "server", which services the requests by sending CoAP responses. 968 Unlike HTTP, requests and responses are not sent over a previously 969 established connection, but exchanged asynchronously over CoAP 970 messages. 972 5.1. Requests 974 A CoAP request consists of the method to be applied to the resource, 975 the identifier of the resource, a payload and Internet media type (if 976 any), and optional meta-data about the request. 978 CoAP supports the basic methods of GET, POST, PUT, DELETE, which are 979 easily mapped to HTTP. They have the same properties of safe (only 980 retrieval) and idempotent (you can invoke it multiple times with the 981 same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method 982 is safe, therefore it MUST NOT take any other action on a resource 983 other than retrieval. The GET, PUT and DELETE methods MUST be 984 performed in such a way that they are idempotent. POST is not 985 idempotent, because its effect is determined by the origin server and 986 dependent on the target resource; it usually results in a new 987 resource being created or the target resource being updated. 989 A request is initiated by setting the Code field in the CoAP header 990 of a confirmable or a non-confirmable message to a Method Code and 991 including request information. 993 The methods used in requests are described in detail in Section 5.8. 995 5.2. Responses 997 After receiving and interpreting a request, a server responds with a 998 CoAP response, which is matched to the request by means of a client- 999 generated token. 1001 A response is identified by the Code field in the CoAP header being 1002 set to a Response Code. Similar to the HTTP Status Code, the CoAP 1003 Response Code indicates the result of the attempt to understand and 1004 satisfy the request. These codes are fully defined in Section 5.9. 1005 The Response Code numbers to be set in the Code field of the CoAP 1006 header are maintained in the CoAP Response Code Registry 1007 (Section 11.1.2). 1009 0 1010 0 1 2 3 4 5 6 7 1011 +-+-+-+-+-+-+-+-+ 1012 |class| detail | 1013 +-+-+-+-+-+-+-+-+ 1015 Figure 9: Structure of a Response Code 1017 The upper three bits of the 8-bit Response Code number define the 1018 class of response. The lower five bits do not have any 1019 categorization role; they give additional detail to the overall class 1020 (Figure 9). There are 3 classes: 1022 2 - Success: The request was successfully received, understood, and 1023 accepted. 1025 4 - Client Error: The request contains bad syntax or cannot be 1026 fulfilled. 1028 5 - Server Error: The server failed to fulfill an apparently valid 1029 request. 1031 The response codes are designed to be extensible: Response Codes in 1032 the Client Error and Server Error class that are unrecognized by an 1033 end-point MUST be treated as being equivalent to the generic Response 1034 Code of that class. However, there is no generic Response Code 1035 indicating success, so a Response Code in the Success class that is 1036 unrecognized by an end-point can only be used to determine that the 1037 request was successful without any further details. 1039 As a human readable notation for specifications and protocol 1040 diagnostics, the numeric value of a response code is indicated by 1041 giving the upper three bits in decimal, followed by a dot and then 1042 the lower five bits in a two-digit decimal. E.g., "Not Found" is 1043 written as 4.04 -- indicating a value of hexadecimal 0x84 or decimal 1044 132. In other words, the dot "." functions as a short-cut for 1045 "*32+". 1047 The possible response codes are described in detail in Section 5.9. 1049 Responses can be sent in multiple ways, which are defined below. 1051 5.2.1. Piggy-backed 1053 In the most basic case, the response is carried directly in the 1054 acknowledgement message that acknowledges the request (which requires 1055 that the request was carried in a confirmable message). This is 1056 called a "Piggy-backed" Response. 1058 The response is returned in the acknowledgement message independent 1059 of whether the response indicates success or failure. In effect, the 1060 response is piggy-backed on the acknowledgement message, so no 1061 separate message is required to both acknowledge that the request was 1062 received and return the response. 1064 5.2.2. Separate 1066 It may not be possible to return a piggy-backed response in all 1067 cases. For example, a server might need longer to obtain the 1068 representation of the resource requested than it can wait sending 1069 back the acknowledgement message, without risking the client to 1070 repeatedly retransmit the request message. Responses to requests 1071 carried in a Non-Confirmable message are always sent separately (as 1072 there is no acknowledgement message). 1074 The server maybe initiates the attempt to obtain the resource 1075 representation and times out an acknowledgement timer, or it 1076 immediately sends an acknowledgement knowing in advance that there 1077 will be no piggy-backed response. The acknowledgement effectively is 1078 a promise that the request will be acted upon. 1080 When the server finally has obtained the resource representation, it 1081 sends the response. To ensure that this message is not lost, it is 1082 again sent as a confirmable message and answered by the client with 1083 an acknowledgement, echoing the new Message ID chosen by the server. 1085 (Implementation notes: Note that, as the underlying datagram 1086 transport may not be sequence-preserving, the confirmable message 1087 carrying the response may actually arrive before or after the 1088 acknowledgement message for the request. Note also that, while the 1089 CoAP protocol itself does not make any specific demands here, there 1090 is an expectation that the response will come within a time frame 1091 that is reasonable from an application point of view; as there is no 1092 underlying transport protocol that could be instructed to run a keep- 1093 alive mechanism, the requester MAY want to set up a timeout that is 1094 unrelated to CoAP's retransmission timers in case the server is 1095 destroyed or otherwise unable to send the response.) 1097 For a separate exchange, both the acknowledgement to the confirmable 1098 request and the acknowledgement to the confirmable response MUST be 1099 an empty message, i.e. one that carries neither a request nor a 1100 response. 1102 5.2.3. Non-Confirmable 1104 If the request message is non-confirmable, then the response SHOULD 1105 be returned in a non-confirmable message as well. However, an end- 1106 point MUST be prepared to receive a non-confirmable response 1107 (preceded or followed an empty acknowledgement message) in reply to a 1108 confirmable request, or a confirmable response in reply to a non- 1109 confirmable request. 1111 5.3. Request/Response Matching 1113 Regardless of how a response is sent, it is matched to the request by 1114 means of a token that is included by the client in the request as one 1115 of the options along with additional address information of the 1116 corresponding end-point. The token MUST be echoed by the server in 1117 any resulting response without modification. 1119 The exact rules for matching a response to a request are as follows: 1121 1. For requests sent in a unicast message, the source of the 1122 response MUST match the destination of the original request. How 1123 this is determined depends on the security mode used (see 1124 Section 10): With NoSec, the IP address and port number of the 1125 request destination and response source must match. With other 1126 security modes, in addition to the IP address and UDP port 1127 matching, the request and response MUST have the same security 1128 context. 1130 2. In a piggy-backed response, both the Message ID of the 1131 confirmable request and the acknowledgement, and the token of the 1132 response and original request MUST match. In a separate 1133 response, just the token of the response and original request 1134 MUST match. 1136 The client SHOULD generate tokens in a way that tokens currently in 1137 use for a given source/destination pair are unique. (Note that a 1138 client can use the same token for any request if it uses a different 1139 source port number each time.) 1141 An end-point receiving a token MUST treat it as opaque and make no 1142 assumptions about its format. (Note that there is a default value 1143 for the Token Option, so every message carries a token, even if it is 1144 not explicitly expressed in a CoAP option.) 1146 In case a confirmable message carrying a response is unexpected (i.e. 1147 the client is not waiting for a response with the specified address 1148 and/or token), the confirmable response SHOULD be rejected with a 1149 reset message and MUST NOT be acknowledged. 1151 5.4. Options 1153 Both requests and responses may include a list of one or more 1154 options. For example, the URI in a request is transported in several 1155 options, and meta-data that would be carried in an HTTP header in 1156 HTTP is supplied as options as well. 1158 CoAP defines a single set of options that are used in both requests 1159 and responses: 1161 o Content-Type 1163 o ETag 1165 o Location-Path 1167 o Location-Query 1169 o Max-Age 1171 o Proxy-Uri 1173 o Token 1175 o Uri-Host 1177 o Uri-Path 1179 o Uri-Port 1181 o Uri-Query 1183 o Accept 1184 o If-Match 1186 o If-None-Match 1188 The semantics of these options along with their properties are 1189 defined in detail in Section 5.10. 1191 Not all options have meaning with all methods and response codes. 1192 The possible options for methods and response codes are defined in 1193 Section 5.8 and Section 5.9 respectively. In case an option has no 1194 meaning, it SHOULD NOT be included by the sender and MUST be ignored 1195 by the recipient. 1197 5.4.1. Critical/Elective 1199 Options fall into one of two classes: "critical" or "elective". The 1200 difference between these is how an option unrecognized by an end- 1201 point is handled: 1203 o Upon reception, unrecognized options of class "elective" MUST be 1204 silently ignored. 1206 o Unrecognized options of class "critical" that occur in a 1207 confirmable request MUST cause the return of a 4.02 (Bad Option) 1208 response. This response SHOULD include a human-readable error 1209 message describing the unrecognized option(s) (see Section 5.5). 1211 o Unrecognized options of class "critical" that occur in a 1212 confirmable response SHOULD cause the response to be rejected with 1213 a reset message. 1215 o Unrecognized options of class "critical" that occur in a non- 1216 confirmable message MUST cause the message to be silently ignored. 1218 Note that, whether critical or elective, an option is never 1219 "mandatory" (it is always optional): These rules are defined in order 1220 to enable implementations to reject options they do not understand or 1221 implement. 1223 5.4.2. Length 1225 Option values are defined to have a specific length, often in the 1226 form of an upper and lower bound. If the length of an option value 1227 in a request is outside the defined range, that option MUST be 1228 treated like an unrecognized option (see Section 5.4.1). 1230 5.4.3. Default Values 1232 Options may be defined to have a default value. If the value of 1233 option is intended to be this default value, the option SHOULD NOT be 1234 included in the message. If the option is not present, the default 1235 value MUST be assumed. 1237 5.4.4. Repeating Options 1239 Each definition of an option specifies whether it is defined to occur 1240 only at most once or whether it can occur multiple times. If a 1241 message includes an option with more instances than the option is 1242 defined for, the additional option instances MUST be treated like an 1243 unrecognized option (see Section 5.4.1). 1245 5.4.5. Option Numbers 1247 Options are identified by an option number. Odd numbers indicate a 1248 critical option, while even numbers indicate an elective option. 1249 (Note that this is not just a convention, it is a feature of the 1250 protocol: Whether an option is elective or critical is entirely 1251 determined by whether its option number is even or odd.) 1253 The numbers 14, 28, 42, ... are reserved for "fenceposting", as 1254 described in Section 3.2. As these option numbers are even, they 1255 stand for elective options, and unless assigned a meaning, these MUST 1256 be silently ignored. 1258 The option numbers for the options defined in this document are 1259 listed in the CoAP Option Number Registry (Section 11.2). 1261 5.5. Payload 1263 Both requests and responses may include payload, depending on the 1264 method or response code respectively. Methods with payload are PUT 1265 and POST, and the response codes with payload are 2.05 (Content) and 1266 the error codes. 1268 The payload of PUT, POST and 2.05 (Content) is typically a resource 1269 representation. Its format is specified by the Internet media type 1270 given by the Content-Type Option. No default value is assumed in the 1271 absence of this option. 1273 2.01 (Created), 2.02 (Deleted), 2.04 (Changed) MAY include payload 1274 that is describing the result of the action. Again, the format of 1275 this payload is specified by the Internet media type given by the 1276 Content-Type Option; no default value is assumed in the absence of 1277 this option. 1279 A response with a code indicating a Client or Server Error SHOULD 1280 include a brief human-readable diagnostic message as payload, 1281 explaining the error situation. This diagnostic message MUST be 1282 encoded using UTF-8 [RFC3629], more specifically using Net-Unicode 1283 form [RFC5198]. The Content-Type Option has no meaning and SHOULD 1284 NOT be included. (Similar to what one would find as a Reason-Phrase 1285 on an HTTP status line, the message is not intended for end-users but 1286 for software engineers that during debugging need to interpret it in 1287 the context of the present, English-language specification; therefore 1288 no language tagging is foreseen.) 1290 If a method or response code is not defined to have a payload, then 1291 the sender SHOULD NOT include one, and the recipient MUST ignore it. 1293 5.6. Caching 1295 CoAP end-points MAY cache responses in order to reduce the response 1296 time and network bandwidth consumption on future, equivalent 1297 requests. 1299 The goal of caching in CoAP is to reuse a prior response message to 1300 satisfy a current request. In some cases, a stored response can be 1301 reused without the need for a network request, reducing latency and 1302 network round-trips; a "freshness" mechanism is used for this purpose 1303 (see Section 5.6.1). Even when a new request is required, it is 1304 often possible to reuse the payload of a prior response to satisfy 1305 the request, thereby reducing network bandwidth usage; a "validation" 1306 mechanism is used for this purpose (see Section 5.6.2). 1308 Unlike HTTP, the cacheability of CoAP responses does not depend on 1309 the request method, but the Response Code. The cacheability of each 1310 Response Code is defined along the Response Code definitions in 1311 Section 5.9. Response Codes that indicate success and are 1312 unrecognized by an end-point MUST NOT be cached. 1314 For a presented request, a CoAP end-point MUST NOT use a stored 1315 response, unless: 1317 o the presented request method and that used to obtain the stored 1318 response match, 1320 o all options match between those in the presented request and those 1321 of the request used to obtain the stored response (which includes 1322 the request URI), except that there is no need for a match of the 1323 Token, Max-Age, or ETag request option(s), and 1325 o the stored response is either fresh or successfully validated as 1326 defined below. 1328 5.6.1. Freshness Model 1330 When a response is "fresh" in the cache, it can be used to satisfy 1331 subsequent requests without contacting the origin server, thereby 1332 improving efficiency. 1334 The mechanism for determining freshness is for an origin server to 1335 provide an explicit expiration time in the future, using the Max-Age 1336 Option (see Section 5.10.6). The Max-Age Option indicates that the 1337 response is to be considered not fresh after its age is greater than 1338 the specified number of seconds. 1340 As the Max-Age Option defaults to a value of 60, if it is not present 1341 in a cacheable response, then the response is considered not fresh 1342 after its age is greater than 60 seconds. If an origin server wishes 1343 to prevent caching, it MUST explicitly include a Max-Age Option with 1344 a value of zero seconds. 1346 5.6.2. Validation Model 1348 When an end-point has one or more stored responses for a GET request, 1349 but cannot use any of them (e.g., because they are not fresh), it can 1350 use the ETag Option in the GET request to give the origin server an 1351 opportunity to both select a stored response to be used, and to 1352 update its freshness. This process is known as "validating" or 1353 "revalidating" the stored response. 1355 When sending such a request, the end-point SHOULD add an ETag Option 1356 specifying the entity-tag of each stored response that is applicable. 1358 A 2.03 (Valid) response indicates the stored response identified by 1359 the entity-tag given in the response's ETag Option can be reused, 1360 after updating its freshness with the value of the Max-Age Option 1361 that is included with the response (see Section 5.9.1.3). 1363 Any other response code indicates that none of the stored responses 1364 nominated in the request is suitable. Instead, the response SHOULD 1365 be used to satisfy the request and MAY replace the stored response. 1367 5.7. Proxying 1369 CoAP distinguishes between requests to an origin server and a request 1370 made through a proxy. A proxy is a CoAP end-point that can be tasked 1371 by CoAP clients to perform requests on their behalf. This may be 1372 useful, for example, when the request could otherwise not be made, or 1373 to service the response from a cache in order to reduce response time 1374 and network bandwidth or energy consumption. 1376 CoAP requests to a proxy are made as normal confirmable or non- 1377 confirmable requests to the proxy end-point, but specify the request 1378 URI in a different way: The request URI in a proxy request is 1379 specified as a string in the Proxy-Uri Option (see Section 5.10.3), 1380 while the request URI in a request to an origin server is split into 1381 the Uri-Host, Uri-Port, Uri-Path and Uri-Query Options (see 1382 Section 5.10.2). 1384 When a proxy request is made to an end-point and the end-point is 1385 unwilling or unable to act as proxy for the request URI, it MUST 1386 return a 5.05 (Proxying Not Supported) response. If the authority 1387 (host and port) is recognized as identifying the proxy end-point, 1388 then the request MUST be treated as a local request. 1390 Unless a proxy is configured to forward the proxy request to another 1391 proxy, it MUST translate the request as follows: The origin server's 1392 IP address and port are determined by the authority component of the 1393 request URI, and the request URI is decoded and split into the Uri- 1394 Host, Uri-Port, Uri-Path and Uri-Query Options. 1396 All options present in a proxy request MUST be processed at the 1397 proxy. Critical options in a request that are not recognized by the 1398 proxy MUST lead to a 4.02 (Bad Option) response being returned by the 1399 proxy. Elective options not recognized by the proxy MUST NOT be 1400 forwarded to the origin server. Similarly, critical options in a 1401 response that are not recognized by the proxy server MUST lead to a 1402 5.02 (Bad Gateway) response. Again, elective options that are not 1403 recognized MUST NOT be forwarded. 1405 If the proxy does not employ a cache, then it simply forwards the 1406 translated request to the determined destination. Otherwise, if it 1407 does employ a cache but does not have a stored response that matches 1408 the translated request and is considered fresh, then it needs to 1409 refresh its cache according to Section 5.6. 1411 If the request to the destination times out, then a 5.04 (Gateway 1412 Timeout) response MUST be returned. If the request to the 1413 destination returns an response that cannot be processed by the 1414 proxy, then a 5.02 (Bad Gateway) response MUST be returned. 1415 Otherwise, the proxy returns the response to the client. 1417 If a response is generated out of a cache, it MUST be generated with 1418 a Max-Age Option that does not extend the max-age originally set by 1419 the server, considering the time the resource representation spent in 1420 the cache. E.g., the Max-Age Option could be adjusted by the proxy 1421 for each response using the formula: proxy-max-age = original-max-age 1422 - cache-age. For example if a request is made to a proxied resource 1423 that was refreshed 20 seconds ago and had an original Max-Age of 60 1424 seconds, then that resource's proxied max-age is now 40 seconds. 1426 5.8. Method Definitions 1428 In this section each method is defined along with its behavior. A 1429 request with an unrecognized or unsupported Method Code MUST generate 1430 a 4.05 (Method Not Allowed) response. 1432 5.8.1. GET 1434 The GET method retrieves a representation for the information that 1435 currently corresponds to the resource identified by the request URI. 1436 If the request inlcudes one or more Accept Options, they indicate the 1437 preferred content-type of a response. If the request includes an 1438 ETag Option, the GET method requests that ETag be validated and that 1439 the representation be transferred only if validation failed. Upon 1440 success a 2.05 (Content) or 2.03 (Valid) response SHOULD be sent. 1442 The GET method is safe and idempotent. 1444 5.8.2. POST 1446 The POST method requests that the representation enclosed in the 1447 request be processed. The actual function performed by the POST 1448 method is determined by the origin server and dependent on the target 1449 resource. It usually results in a new resource being created or the 1450 target resource being updated. 1452 If a resource has been created on the server, a 2.01 (Created) 1453 response that includes the URI of the new resource in a sequence of 1454 one or more Location-Path Options and/or a Location-Query Option 1455 SHOULD be returned. If the POST succeeds but does not result in a 1456 new resource being created on the server, a 2.04 (Changed) response 1457 SHOULD be returned. If the POST succeeds and results in the target 1458 resource being deleted, a 2.02 (Deleted) response SHOULD be returned. 1460 POST is neither safe nor idempotent. 1462 5.8.3. PUT 1464 The PUT method requests that the resource identified by the request 1465 URI be updated or created with the enclosed representation. The 1466 representation format is specified by the media type given in the 1467 Content-Type Option. 1469 If a resource exists at the request URI the enclosed representation 1470 SHOULD be considered a modified version of that resource, and a 2.04 1471 (Changed) response SHOULD be returned. If no resource exists then 1472 the server MAY create a new resource with that URI, resulting in a 1473 2.01 (Created) response. If the resource could not be created or 1474 modified, then an appropriate error response code SHOULD be sent. 1476 Further restrictions to a PUT can be made by including the If-Match 1477 (see Section 5.10.9) or If-None-Match (see Section 5.10.10) options 1478 in the request. 1480 PUT is not safe, but idempotent. 1482 5.8.4. DELETE 1484 The DELETE method requests that the resource identified by the 1485 request URI be deleted. A 2.02 (Deleted) response SHOULD be sent on 1486 success or in case the resource did not exist before the request. 1488 DELETE is not safe, but idempotent. 1490 5.9. Response Code Definitions 1492 Each response code is described below, including any options required 1493 in the response. Where appropriate, some of the codes will be 1494 specified in regards to related response codes in HTTP [RFC2616]; 1495 this does not mean that any such relationship modifies the HTTP 1496 mapping specified in Section 8. 1498 5.9.1. Success 2.xx 1500 This class of status code indicates that the clients request was 1501 successfully received, understood, and accepted. 1503 5.9.1.1. 2.01 Created 1505 Like HTTP 201 "Created", but only used in response to POST and PUT 1506 requests. The payload returned with the response, if any, is a 1507 representation of the action result. The representation format is 1508 specified by the media type given in the Content-Type Option. 1510 If the response includes one or more Location-Path Options and/or a 1511 Location-Query Option, the values of these options specify the 1512 location at which the resource was created. Otherwise, the resource 1513 was created at the request URI. A cache SHOULD mark any stored 1514 response for the created resource as not fresh. 1516 This response is not cacheable. 1518 5.9.1.2. 2.02 Deleted 1520 Like HTTP 204 "No Content", but only used in response to DELETE 1521 requests. The payload returned with the response, if any, is a 1522 representation of the action result. The representation format is 1523 specified by the media type given in the Content-Type Option. 1525 This response is not cacheable. However, a cache SHOULD mark any 1526 stored response for the deleted resource as not fresh. 1528 5.9.1.3. 2.03 Valid 1530 Related to HTTP 304 "Not Modified", but only used to indicate that 1531 the response identified by the entity-tag identified by the included 1532 ETag Option is valid. Accordingly, the response MUST include an ETag 1533 Option. 1535 When a cache receives a 2.03 (Valid) response, it needs to update the 1536 stored response with the value of the Max-Age Option included in the 1537 response (see Section 5.6.2). 1539 5.9.1.4. 2.04 Changed 1541 Like HTTP 204 "No Content", but only used in response to POST and PUT 1542 requests. The payload returned with the response, if any, is a 1543 representation of the action result. The representation format is 1544 specified by the media type given in the Content-Type Option. 1546 This response is not cacheable. However, a cache SHOULD mark any 1547 stored response for the changed resource as not fresh. 1549 5.9.1.5. 2.05 Content 1551 Like HTTP 200 "OK", but only used in response to GET requests. 1553 The payload returned with the response is a representation of the 1554 target resource. The representation format is specified by the media 1555 type given in the Content-Type Option. 1557 This response is cacheable: Caches can use the Max-Age Option to 1558 determine freshness (see Section 5.6.1) and (if present) the ETag 1559 Option for validation (see Section 5.6.2). 1561 5.9.2. Client Error 4.xx 1563 This class of response code is intended for cases in which the client 1564 seems to have erred. These response codes are applicable to any 1565 request method. 1567 The server SHOULD include a brief human-readable message as payload, 1568 as detailed in Section 5.5. 1570 Responses of this class are cacheable: Caches can use the Max-Age 1571 Option to determine freshness (see Section 5.6.1). They cannot be 1572 validated. 1574 5.9.2.1. 4.00 Bad Request 1576 Like HTTP 400 "Bad Request". 1578 5.9.2.2. 4.01 Unauthorized 1580 The client is not authorized to perform the requested action. The 1581 client SHOULD NOT repeat the request without previously improving its 1582 authentication status to the server. Which specific mechanism can be 1583 used for this is outside this document's scope; see also Section 10. 1585 5.9.2.3. 4.02 Bad Option 1587 The request could not be understood by the server due to one or more 1588 unrecognized or malformed critical options. The client SHOULD NOT 1589 repeat the request without modification. 1591 5.9.2.4. 4.03 Forbidden 1593 Like HTTP 403 "Forbidden". 1595 5.9.2.5. 4.04 Not Found 1597 Like HTTP 404 "Not Found". 1599 5.9.2.6. 4.05 Method Not Allowed 1601 Like HTTP 405 "Method Not Allowed", but with no parallel to the 1602 "Allow" header field. 1604 5.9.2.7. 4.06 Not Acceptable 1606 Like HTTP 406 "Not Acceptable", but with no response entity. 1608 5.9.2.8. 4.12 Precondition Failed 1610 Like HTTP 412 "Precondition Failed". 1612 5.9.2.9. 4.13 Request Entity Too Large 1614 Like HTTP 413 "Request Entity Too Large". 1616 5.9.2.10. 4.15 Unsupported Media Type 1618 Like HTTP 415 "Unsupported Media Type". 1620 5.9.3. Server Error 5.xx 1622 This class of response code indicates cases in which the server is 1623 aware that it has erred or is incapable of performing the request. 1624 These response codes are applicable to any request method. 1626 The server SHOULD include a human-readable message as payload, as 1627 detailed in Section 5.5. 1629 Responses of this class are cacheable: Caches can use the Max-Age 1630 Option to determine freshness (see Section 5.6.1). They cannot be 1631 validated. 1633 5.9.3.1. 5.00 Internal Server Error 1635 Like HTTP 500 "Internal Server Error". 1637 5.9.3.2. 5.01 Not Implemented 1639 Like HTTP 501 "Not Implemented". 1641 5.9.3.3. 5.02 Bad Gateway 1643 Like HTTP 502 "Bad Gateway". 1645 5.9.3.4. 5.03 Service Unavailable 1647 Like HTTP 503 "Service Unavailable", but using the Max-Age Option in 1648 place of the "Retry-After" header field. 1650 5.9.3.5. 5.04 Gateway Timeout 1652 Like HTTP 504 "Gateway Timeout". 1654 5.9.3.6. 5.05 Proxying Not Supported 1656 The server is unable or unwilling to act as a proxy for the URI 1657 specified in the Proxy-Uri Option (see Section 5.10.3). 1659 5.10. Option Definitions 1661 The individual CoAP options are summarized in Table 1 and explained 1662 below. 1664 +-----+----------+----------------+--------+---------+-------------+ 1665 | No. | C/E | Name | Format | Length | Default | 1666 +-----+----------+----------------+--------+---------+-------------+ 1667 | 1 | Critical | Content-Type | uint | 0-2 B | (none) | 1668 | 2 | Elective | Max-Age | uint | 0-4 B | 60 | 1669 | 3 | Critical | Proxy-Uri | string | 1-270 B | (none) | 1670 | 4 | Elective | ETag | opaque | 1-8 B | (none) | 1671 | 5 | Critical | Uri-Host | string | 1-270 B | (see below) | 1672 | 6 | Elective | Location-Path | string | 1-270 B | (none) | 1673 | 7 | Critical | Uri-Port | uint | 0-2 B | (see below) | 1674 | 8 | Elective | Location-Query | string | 1-270 B | (none) | 1675 | 9 | Critical | Uri-Path | string | 1-270 B | (none) | 1676 | 11 | Critical | Token | opaque | 1-8 B | (empty) | 1677 | 12 | Elective | Accept | uint | 0-2 B | (none) | 1678 | 13 | Critical | If-Match | opaque | 0-8 B | (none) | 1679 | 15 | Critical | Uri-Query | string | 1-270 B | (none) | 1680 | 21 | Critical | If-None-Match | (none) | 0 B | (none) | 1681 +-----+----------+----------------+--------+---------+-------------+ 1683 Table 1: Options 1685 5.10.1. Token 1687 The Token Option is used to match a response with a request. Every 1688 request has a client-generated token which the server MUST echo in 1689 any response. A default value of a zero-length token is assumed in 1690 the absence of the option. Thus when the token value is empty, the 1691 Token Option SHOULD be elided for efficiency. 1693 A token is intended for use as a client-local identifier for 1694 differentiating between concurrent requests (see Section 5.3). A 1695 client SHOULD generate tokens in a way that tokens currently in use 1696 for a given source/destination pair are unique. An empty token value 1697 is appropriate e.g. when no other tokens are in use to a destination, 1698 or when requests are made serially per destination. There are 1699 however multiple possible implementation strategies to fulfill this. 1700 An end-point receiving a token MUST treat it as opaque and make no 1701 assumptions about its format. 1703 This option is "critical". It MUST NOT occur more than once. 1705 5.10.2. Uri-Host, Uri-Port, Uri-Path and Uri-Query 1707 The Uri-Host, Uri-Port, Uri-Path and Uri-Query Options are used to 1708 specify the target resource of a request to a CoAP origin server. 1709 The options encode the different components of the request URI in a 1710 way that no percent-encoding is visible in the option values and that 1711 the full URI can be reconstructed at any involved end-point. The 1712 syntax of CoAP URIs is defined in Section 6. 1714 The steps for parsing URIs into options is defined in Section 6.4. 1715 These steps result in zero or more Uri-Host, Uri-Port, Uri-Path and 1716 Uri-Query Options being included in a request, where each option 1717 holds the following values: 1719 o the Uri-Host Option specifies the Internet host of the resource 1720 being requested, 1722 o the Uri-Port Option specifies the port number of the resource, 1724 o each Uri-Path Option specifies one segment of the absolute path to 1725 the resource, and 1727 o each Uri-Query Option specifies one argument parameterizing the 1728 resource. 1730 Note: Fragments ([RFC3986], Section 3.5) are not part of the request 1731 URI and thus will not be transmitted in a CoAP request. 1733 The default value of the Uri-Host Option is the IP literal 1734 representing the destination IP address of the request message. 1735 Likewise, the default value of the Uri-Port Option is the destination 1736 UDP port. The default Uri-Host and Uri-Port options are sufficient 1737 for requests to most servers, and are typically used when an end- 1738 point hosts multiple virtual servers. 1740 The Uri-Path and Uri-Query Option can contain any character sequence. 1741 No percent-encoding is performed. The value of a Uri-Path Option 1742 MUST NOT be "." or ".." (as the request URI must be resolved before 1743 parsing it into options). 1745 The steps for constructing the request URI from the options are 1746 defined in Section 6.5. Note that an implementation does not 1747 necessarily have to construct the URI; it can simply look up the 1748 target resource by looking at the individual options. 1750 Examples can be found in Appendix C. 1752 All of the options are "critical". Uri-Host and Uri-Port MUST NOT 1753 occur more than once; Uri-Path and Uri-Query MAY occur one or more 1754 times. 1756 5.10.3. Proxy-Uri 1758 The Proxy-Uri Option is used to make a request to a proxy (see 1759 Section 5.7). The proxy is requested to forward the request or 1760 service it from a valid cache, and return the response. 1762 The option value is an absolute-URI ([RFC3986], Section 4.3). In 1763 case the absolute-URI doesn't fit within a single option, the Proxy- 1764 Uri Option MAY be included multiple times in a request such that the 1765 concatenation of the values results in the single absolute-URI. 1767 All but the last instance of the Proxy-Uri Option MUST have a value 1768 with a length of 270 bytes, and the last instance MUST NOT be empty. 1770 Note that the proxy MAY forward the request on to another proxy or 1771 directly to the server specified by the absolute-URI. In order to 1772 avoid request loops, a proxy MUST be able to recognize all of its 1773 server names, including any aliases, local variations, and the 1774 numeric IP addresses. 1776 An end-point receiving a request with a Proxy-Uri Option that is 1777 unable or unwilling to act as a proxy for the request MUST cause the 1778 return of a 5.05 (Proxying Not Supported) response. 1780 This option is "critical". It MAY occur one or more times and MUST 1781 take precedence over any of the Uri-Host, Uri-Port, Uri-Path or Uri- 1782 Query options (which MUST NOT be included at the same time). 1784 5.10.4. Content-Type 1786 The Content-Type Option indicates the representation format of the 1787 message payload. The representation format is given as a numeric 1788 media type identifier that is defined in the CoAP Media Type registry 1789 (Section 11.3). No default value is assumed in the absence of the 1790 option. 1792 This option is "critical". It MUST NOT occur more than once. 1794 5.10.5. Accept 1796 The CoAP Accept option indicates when included one or more times in a 1797 request, one or more media types, each of which is an acceptable 1798 media type for the client, in the order of preference. The 1799 representation format is given as a numeric media type identifier 1800 that is defined in the CoAP Media Type registry (Section 11.3). If 1801 no Accept options are given, the client does not express a preference 1802 (thus no default value is assumed). The client prefers the 1803 representation returned by the server to be in one of the media types 1804 indicated. The server SHOULD return one of the preferred media types 1805 if available. If none of the preferred media types can be returned, 1806 then a 4.06 "Not Acceptable" SHOULD be sent as a response. 1808 Note that as a server might not support the Accept option (and thus 1809 would ignore it as it is elective), the client needs to be prepared 1810 to receive a representation in a different media type. The client 1811 can simply discard a representation it can not make use of. 1813 This option is "elective". It MAY occur more than once. 1815 5.10.6. Max-Age 1817 The Max-Age Option indicates the maximum time a response may be 1818 cached before it MUST be considered not fresh (see Section 5.6.1). 1820 The option value is an integer number of seconds between 0 and 2^32-1 1821 inclusive (about 136.1 years). A default value of 60 seconds is 1822 assumed in the absence of the option in a response. 1824 This option is "elective". It MUST NOT occur more than once. 1826 5.10.7. ETag 1828 The ETag Option in a response provides the current value of the 1829 entity-tag for the enclosed representation of the target resource. 1831 An entity-tag is intended for use as a resource-local identifier for 1832 differentiating between representations of the same resource that 1833 vary over time. It may be generated in any number of ways including 1834 a version, checksum, hash or time. An end-point receiving an entity- 1835 tag MUST treat it as opaque and make no assumptions about its format. 1836 (End-points generating an entity-tag are encouraged to use the most 1837 compact representation possible, in particular in regards to clients 1838 and intermediaries that may want to store multiple ETag values.) 1840 An end-point that has one or more representations previously obtained 1841 from the resource can specify the ETag Option in a request for each 1842 stored response to determine if any of those representations is 1843 current (see Section 5.6.2). 1845 This option is "elective". It MUST NOT occur more than once in a 1846 response, and MAY occur one or more times in a request. 1848 5.10.8. Location-Path and Location-Query 1850 The Location-Path and Location-Query Options indicates the location 1851 of a resource as an absolute path URI. The Location-Path Option is 1852 similar to the Uri-Path Option, and the Location-Query Option similar 1853 to the Uri-Query Option. 1855 The two options MAY be included in a response to indicate the 1856 location of a new resource created with POST. 1858 If a response with a Location-Path and/or Location-Query Option 1859 passes through a cache and the implied URI identifies one or more 1860 currently stored responses, those entries SHOULD be marked as not 1861 fresh. 1863 Both options are "elective" and MAY occur one or more times. 1865 5.10.9. If-Match 1867 The If-Match Option MAY be used to make a request conditional on the 1868 current existence or value of an ETag for one or more representations 1869 of the target resource. If-Match is generally useful for resource 1870 update requests, such as PUT requests, as a means for protecting 1871 against accidental overwrites when multiple clients are acting in 1872 parallel on the same resource (i.e., the "lost update" problem). 1874 The value of an If-Match option is either an ETag or the empty 1875 string. An empty string places the precondition on the existence of 1876 any current representation for the target resource. 1878 The If-Match Option can occur multiple times. If any of the ETags 1879 given as an option value match the ETag of the selected 1880 representation for the target resource, or if an If-Match Option with 1881 an empty string as option value is given and any current 1882 representation exists for the target resource, then the server MAY 1883 perform the request method as if the If-Match Option was not present. 1885 If none of the ETags match and, if an empty string is given, no 1886 current representation exists at all, the server MUST NOT perform the 1887 requested method. Instead, the server MUST respond with the 4.12 1888 (Precondition Failed) response code. 1890 If the request would, without the If-Match Options, result in 1891 anything other than a 2.xx or 4.12 response code, then any If-Match 1892 Options MUST be ignored. 1894 This option is "critical". It MAY occur more than once. 1896 5.10.10. If-None-Match 1898 The If-None-Match Option MAY be used to make a request conditional on 1899 the non-existance of the target resource. If-None-Match is useful 1900 for resource creation requests, such as PUT requests, as a means for 1901 protecting against accidental overwrites when multiple clients are 1902 acting in parallel on the same resource. The If-None-Match Option 1903 carries no value. 1905 If the target resource does exist, then the server MUST NOT perform 1906 the requested method. Instead, the server MUST respond with the 4.12 1907 (Precondition Failed) response code. 1909 This option is "critical". It MAY NOT occur more than once. 1911 6. CoAP URIs 1913 CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP 1914 resources and providing a means of locating the resource. Resources 1915 are organized hierarchically and governed by a potential CoAP origin 1916 server listening for CoAP requests ("coap") or DTLS-secured CoAP 1917 requests ("coaps") on a given UDP port. The CoAP server is 1918 identified via the generic syntax's authority component, which 1919 includes a host identifier and optional UDP port number. The 1920 remainder of the URI is considered to be identifying a resource which 1921 can be operated on by the methods defined by the CoAP protocol. The 1922 "coap" and "coaps" URI schemes can thus be compared to the "http" and 1923 "https" URI schemes respectively. 1925 The syntax of the "coap" and "coaps" URI schemes is specified below 1926 in Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 1927 "host", "port", "path-abempty", "query", "segment", "IP-literal", 1928 "IPv4address" and "reg-name" are adopted from [RFC3986]. 1930 6.1. coap URI Scheme 1932 coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] 1934 If host is provided as an IP-literal or IPv4address, then the CoAP 1935 server is located at that IP address. If host is a registered name, 1936 then that name is considered an indirect identifier and the end-point 1937 might use a name resolution service, such as DNS, to find the address 1938 of that host. The host MUST NOT be empty. The port subcomponent 1939 indicates the UDP port at which the CoAP server is located. If it is 1940 empty or not given, then the default port 5683 is assumed. 1942 The path identifies a resource within the scope of the host and port. 1944 It consists of a sequence of path segments separated by a slash 1945 character (U+002F SOLIDUS "/"). 1947 The query serves to further parameterize the resource. It consists 1948 of a sequence of arguments separated by an ampersand character 1949 (U+0026 AMPERSAND "&"). An argument is often in the form of a 1950 "key=value" pair. 1952 The "coap" URI scheme supports the path prefix "/.well-known/" 1953 defined by [RFC5785] for "well-known locations" in the name-space of 1954 a host. This enables discovery of policy or other information about 1955 a host ("site-wide metadata"), such as hosted resources (see 1956 Section 7.1). 1958 Application designers are encouraged to make use of short, but 1959 descriptive URIs. As the environments that CoAP is used in are 1960 usually constrained for bandwidth and energy, the trade-off between 1961 these two qualities should lean towards the shortness, without 1962 ignoring descriptiveness. 1964 6.2. coaps URI Scheme 1966 coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty 1967 [ "?" query ] 1969 All of the requirements listed above for the "coap" scheme are also 1970 requirements for the "coaps" scheme, except that a default UDP port 1971 of [IANA_TBD_PORT] is assumed if the port subcomponent is empty or 1972 not given, and the UDP datagrams MUST be secured for privacy through 1973 the use of DTLS as described in Section 10.1. 1975 Unlike the "coap" scheme, responses to "coaps" identified requests 1976 are never "public" and thus MUST NOT be reused for shared caching. 1977 They can, however, be reused in a private cache if the message is 1978 cacheable by default in CoAP. 1980 Resources made available via the "coaps" scheme have no shared 1981 identity with the "coap" scheme even if their resource identifiers 1982 indicate the same authority (the same host listening to the same UDP 1983 port). They are distinct name spaces and are considered to be 1984 distinct origin servers. 1986 6.3. Normalization and Comparison Rules 1988 Since the "coap" and "coaps" schemes conform to the URI generic 1989 syntax, such URIs are normalized and compared according to the 1990 algorithm defined in [RFC3986], Section 6, using the defaults 1991 described above for each scheme. 1993 If the port is equal to the default port for a scheme, the normal 1994 form is to elide the port subcomponent. Likewise, an empty path 1995 component is equivalent to an absolute path of "/", so the normal 1996 form is to provide a path of "/" instead. The scheme and host are 1997 case-insensitive and normally provided in lowercase; IP-literals are 1998 in recommended form [RFC5952]; all other components are compared in a 1999 case-sensitive manner. Characters other than those in the "reserved" 2000 set are equivalent to their percent-encoded octets (see [RFC3986], 2001 Section 2.1): the normal form is to not encode them. 2003 For example, the following three URIs are equivalent, and cause the 2004 same options and option values to appear in the CoAP messages: 2006 coap://example.com:5683/~sensors/temp.xml 2007 coap://EXAMPLE.com/%7Esensors/temp.xml 2008 coap://EXAMPLE.com:/%7esensors/temp.xml 2010 6.4. Decomposing URIs into Options 2012 The steps to parse a request's options from a string /url/ are as 2013 follows. These steps either result in zero or more of the Uri-Host, 2014 Uri-Port, Uri-Path and Uri-Query Options being included in the 2015 request, or they fail. 2017 1. If the /url/ string is not an absolute URI ([RFC3986]), then fail 2018 this algorithm. 2020 2. Resolve the /url/ string using the process of reference 2021 resolution defined by [RFC3986], with the URL character encoding 2022 set to UTF-8 [RFC3629]. 2024 NOTE: It doesn't matter what it is resolved relative to, since we 2025 already know it is an absolute URL at this point. 2027 3. If /url/ does not have a component whose value, when 2028 converted to ASCII lowercase, is "coap" or "coaps", then fail 2029 this algorithm. 2031 4. If /url/ has a component, then fail this algorithm. 2033 5. If the component of /url/ does not represent the request's 2034 destination IP address as an IP-literal or IPv4address, include a 2035 Uri-Host Option and let that option's value be the value of the 2036 component of /url/, converted to ASCII lowercase, and then 2037 converting all percent-encodings ("%" followed by two hexadecimal 2038 digits) to the corresponding characters. 2040 NOTE: In the usual case where the request's destination IP 2041 address is derived from the host part, this ensures that Uri-Host 2042 Options are only used for host parts of the form reg-name. 2044 6. If /url/ has a component, then let /port/ be that 2045 component's value interpreted as a decimal integer; otherwise, 2046 let /port/ be the default port for the scheme. 2048 7. If /port/ does not equal the request's destination UDP port, 2049 include a Uri-Port Option and let that option's value be /port/. 2051 8. If the value of the component of /url/ is empty or 2052 consists of a single slash character (U+002F SOLIDUS "/"), then 2053 move to the next step. 2055 Otherwise, for each segment in the component, include a 2056 Uri-Path Option and let that option's value be the segment (not 2057 including the delimiting slash characters) after converting all 2058 percent-encodings ("%" followed by two hexadecimal digits) to the 2059 corresponding characters. 2061 9. If /url/ has a component, then, for each argument in the 2062 component, include a Uri-Query Option and let that 2063 option's value be the argument (not including the question mark 2064 and the delimiting ampersand characters) after converting all 2065 percent-encodings to the corresponding characters. 2067 Note that these rules completely resolve any percent-encoding. 2069 6.5. Composing URIs from Options 2071 The steps to construct a URI from a request's options are as follows. 2072 These steps either result in a URI, or they fail. In these steps, 2073 percent-encoding a character means replacing each of its (UTF-8 2074 encoded) bytes by a "%" character followed by two hexadecimal digits 2075 representing the byte, where the digits A-F are in upper case (as 2076 defined in [RFC3986] Section 2.1; to reduce variability, the 2077 hexadecimal notation in CoAP URIs MUST use uppercase letters). 2079 1. If the request is secured using DTLS, let /url/ be the string 2080 "coaps://". Otherwise, let /url/ be the string "coap://". 2082 2. If the request includes a Uri-Host Option, let /host/ be that 2083 option's value, where any non-ASCII characters are replaced by 2084 their corresponding percent-encoding. If /host/ is not a valid 2085 reg-name or IP-literal or IPv4address, fail the algorithm. 2086 Otherwise, let /host/ be the IP-literal (making use of the 2087 conventions of [RFC5952]) or IPv4address representing the 2088 request's destination IP address. 2090 3. Append /host/ to /url/. 2092 4. If the request includes a Uri-Port Option, let /port/ be that 2093 option's value. Otherwise, let /port/ be the request's 2094 destination UDP port. 2096 5. If /port/ is not the default port for the scheme, then append a 2097 single U+003A COLON character (:) followed by the decimal 2098 representation of /port/ to /url/. 2100 6. Let /resource name/ be the empty string. For each Uri-Path 2101 Option in the request, append a single character U+002F SOLIDUS 2102 (/) followed by the option's value to /resource name/, after 2103 converting any character that is not either in the "unreserved" 2104 set, "sub-delims" set, a U+003A COLON (:) or U+0040 COMMERCIAL 2105 AT (@) character, to its percent-encoded form. 2107 7. If /resource name/ is the empty string, set it to a single 2108 character U+002F SOLIDUS (/). 2110 8. For each Uri-Query Option in the request, append a single 2111 character U+003F QUESTION MARK (?) (first option) or U+0026 2112 AMPERSAND (&) (subsequent options) followed by the option's 2113 value to /resource name/, after converting any character that is 2114 not either in the "unreserved" set, "sub-delims" set (except 2115 U+0026 AMPERSAND (&)), a U+003A COLON (:), U+0040 COMMERCIAL AT 2116 (@), U+002F SOLIDUS (/) or U+003F QUESTION MARK (?) character, 2117 to its percent-encoded form. 2119 9. Append /resource name/ to /url/. 2121 10. Return /url/. 2123 Note that these steps have been designed to lead to a URI in normal 2124 form (see Section 6.3). 2126 7. Finding and Addressing CoAP End-Points 2128 7.1. Resource Discovery 2130 The discovery of resources offered by a CoAP end-point is extremely 2131 important in machine-to-machine applications where there are no 2132 humans in the loop and static interfaces result in fragility. A CoAP 2133 end-point SHOULD support the CoRE Link Format of discoverable 2134 resources as described in [I-D.ietf-core-link-format]. It is up to 2135 the server which resources are made discoverable (if any). 2137 7.1.1. Content-type code 'ct' attribute 2139 This section defines a new Web Linking [RFC5988] attribute for use 2140 with [I-D.ietf-core-link-format]. The Content-type code "ct" 2141 attribute provides a hint about the Internet media type(s) this 2142 resource returns. Note that this is only a hint, and does not 2143 override the Content-type Option of a CoAP response obtained by 2144 actually following the link. The value is in the CoAP identifier 2145 code format as a decimal ASCII integer and MUST be in the range of 2146 0-65535 (16-bit unsigned integer). For example application/xml would 2147 be indicated as "ct=41". If no Content-type code attribute is 2148 present then nothing about the type can be assumed. The Content-type 2149 code attribute MAY appear more than once in a link, indicating that 2150 multiple content-types are available. 2152 link-extension = 2153 link-extension = ( "ct" "=" cardinal ) ; Range of 0-65535 2154 cardinal = "0" / %x31-39 *DIGIT 2156 7.2. Default Ports 2158 The CoAP default port number 5683 MUST be supported by a server for 2159 resource discovery and SHOULD be supported for providing access to 2160 other resources. The DTLS-secured CoAP default port number 2161 [IANA_TBD_PORT] MAY be supported by a server for resource discovery 2162 and for providing access to other resources. In addition other end- 2163 points may be hosted in the dynamic port space. 2165 When a CoAP server is hosted by a 6LoWPAN node, it SHOULD also 2166 support a port in the 61616-61631 compressed UDP port space defined 2167 in [RFC4944]. 2169 8. HTTP Mapping 2171 CoAP supports a limited subset of HTTP functionality, and thus a 2172 mapping to HTTP is straightforward. There might be several reasons 2173 for mapping between CoAP and HTTP, for example when designing a web 2174 interface for use over either protocol or when realizing a CoAP-HTTP 2175 proxy. Likewise, CoAP could equally be mapped to other protocols 2176 such as XMPP [RFC6120] or SIP [RFC3264]; the definition of these 2177 mappings is out of scope of this specification. 2179 There are two possible mappings via a forward proxy: 2181 CoAP-HTTP Mapping: Enables CoAP clients to access resources on HTTP 2182 servers through an intermediary. This is initiated by including 2183 the Proxy-Uri Option with an "http" or "https" URI in a CoAP 2184 request to a CoAP-HTTP proxy. 2186 HTTP-CoAP Mapping: Enables HTTP clients to access resources on CoAP 2187 servers through an intermediary. This is initiated by specifying 2188 a "coap" or "coaps" URI in the Request-Line of an HTTP request to 2189 an HTTP-CoAP proxy. 2191 Either way, only the Request/Response model of CoAP is mapped to 2192 HTTP. The underlying model of confirmable or non-confirmable 2193 messages, etc., is invisible and MUST have no effect on a proxy 2194 function. The following sections describe the handling of requests 2195 to a forward proxy. Reverse proxies are not specified as the proxy 2196 function is transparent to the client with the proxy acting as if it 2197 was the origin server. 2199 8.1. CoAP-HTTP Mapping 2201 If a request contains a Proxy-URI Option with an 'http' or 'https' 2202 URI [RFC2616], then the receiving CoAP end-point (called "the proxy" 2203 henceforth) is requested to perform the operation specified by the 2204 request method on the indicated HTTP resource and return the result 2205 to the client. 2207 This section specifies for any CoAP request the CoAP response that 2208 the proxy should return to the client. How the proxy actually 2209 satisfies the request is an implementation detail, although the 2210 typical case is expected to be the proxy translating and forwarding 2211 the request to an HTTP origin server. 2213 Since HTTP and CoAP share the basic set of request methods, 2214 performing a CoAP request on an HTTP resource is not so different 2215 from performing it on a CoAP resource. The meanings of the 2216 individual CoAP methods when performed on HTTP resources are 2217 explained below. 2219 If the proxy is unable or unwilling to service a request with an HTTP 2220 URI, a 5.05 (Proxying Not Supported) response SHOULD be returned to 2221 the client. If the proxy services the request by interacting with a 2222 third party (such as the HTTP origin server) and is unable to obtain 2223 a result within a reasonable time frame, a 5.04 (Gateway Timeout) 2224 response SHOULD be returned; if a result can be obtained but is not 2225 understood, a 5.02 (Bad Gateway) response SHOULD be returned. 2227 8.1.1. GET 2229 The GET method requests the proxy to return a representation of the 2230 HTTP resource identified by the request URI. 2232 Upon success, a 2.05 (Content) response SHOULD be returned. The 2233 payload of the response MUST be a representation of the target HTTP 2234 resource, and the Content-Type Option be set accordingly. The 2235 response MUST indicate a Max-Age value that is no greater than the 2236 remaining time the representation can be considered fresh. If the 2237 HTTP entity has an entity tag, the proxy SHOULD include an ETag 2238 Option in the response and process ETag Options in requests as 2239 described below. 2241 A client can influence the processing of a GET request by including 2242 the following option: 2244 Accept: The request MAY include one or more Accept Options, 2245 identifying the preferred response content-type. 2247 ETag: The request MAY include one or more ETag Options, identifying 2248 responses that the client has stored. This requests the proxy to 2249 send a 2.03 (Valid) response whenever it would send a 2.05 2250 (Content) response with an entity tag in the requested set 2251 otherwise. 2253 8.1.2. PUT 2255 The PUT method requests the proxy to update or create the HTTP 2256 resource identified by the request URI with the enclosed 2257 representation. 2259 If a new resource is created at the request URI, a 2.01 (Created) 2260 response MUST be returned to the client. If an existing resource is 2261 modified, a 2.04 (Changed) response MUST be returned to indicate 2262 successful completion of the request. 2264 8.1.3. DELETE 2266 The DELETE method requests the proxy to delete the HTTP resource 2267 identified by the request URI at the HTTP origin server. 2269 A 2.02 (Deleted) response MUST be returned to client upon success or 2270 if the resource does not exist at the time of the request. 2272 8.1.4. POST 2274 The POST method requests the proxy to have the representation 2275 enclosed in the request be processed by the HTTP origin server. The 2276 actual function performed by the POST method is determined by the 2277 origin server and dependent on the resource identified by the request 2278 URI. 2280 If the action performed by the POST method does not result in a 2281 resource that can be identified by a URI, a 2.04 (Changed) response 2282 MUST be returned to the client. If a resource has been created on 2283 the origin server, a 2.01 (Created) response MUST be returned. 2285 8.2. HTTP-CoAP Mapping 2287 If an HTTP request contains a Request-URI with a 'coap' or 'coaps' 2288 URI, then the receiving HTTP end-point (called "the proxy" 2289 henceforth) is requested to perform the operation specified by the 2290 request method on the indicated CoAP resource and return the result 2291 to the client. 2293 This section specifies for any HTTP request the HTTP response that 2294 the proxy should return to the client. How the proxy actually 2295 satisfies the request is an implementation detail, although the 2296 typical case is expected to be the proxy translating and forwarding 2297 the request to a CoAP origin server. The meanings of the individual 2298 HTTP methods when performed on CoAP resources are explained below. 2300 If the proxy is unable or unwilling to service a request with a CoAP 2301 URI, a 501 (Not Implemented) response SHOULD be returned to the 2302 client. If the proxy services the request by interacting with a 2303 third party (such as the CoAP origin server) and is unable to obtain 2304 a result within a reasonable time frame, a 504 (Gateway Timeout) 2305 response SHOULD be returned; if a result can be obtained but is not 2306 understood, a 502 (Bad Gateway) response SHOULD be returned. 2308 8.2.1. OPTIONS and TRACE 2310 As the OPTIONS and TRACE methods are not supported in CoAP a 501 (Not 2311 Implemented) error MUST be returned to the client. 2313 8.2.2. GET 2315 The GET method requests the proxy to return a representation of the 2316 CoAP resource identified by the Request-URI. 2318 Upon success, a 200 (OK) response SHOULD be returned. The payload of 2319 the response MUST be a representation of the target CoAP resource, 2320 and the Content-Type Option be set accordingly. The response MUST 2321 indicate a Max-Age value that is no greater than the remaining time 2322 the representation can be considered fresh. If the CoAP entity has 2323 an entity tag, the proxy SHOULD include an ETag Option in the 2324 response. 2326 A client can influence the processing of a GET request by including 2327 the following option: 2329 Accept: Each individual Media-type of the HTTP Accept header in a 2330 request is mapped to a CoAP Accept option. HTTP Accept Media-type 2331 ranges, parameters and extensions are not supported by the CoAP 2332 Accept option. If the proxy cannot send a response which is 2333 acceptable according to the combined Accept field value, then the 2334 proxy SHOULD send a 406 (not acceptable) response. 2336 Conditional GETs: Conditional HTTP GET requests that include an "If- 2337 Match" or "If-None-Match" request-header field can be mapped to a 2338 corresponding CoAP request. The "If-Modified-Since" and "If- 2339 Unmodified-Since" request-header fields are not directly supported 2340 by CoAP, but SHOULD be implemented locally by a caching proxy. 2342 8.2.3. HEAD 2344 The HEAD method is identical to GET except that the server MUST NOT 2345 return a message-body in the response. 2347 Although there is no direct equivalent of HTTP's HEAD method in CoAP, 2348 an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and 2349 the HTTP headers are returned without a message-body. 2351 8.2.4. POST 2353 The POST method requests the proxy to have the representation 2354 enclosed in the request be processed by the CoAP origin server. The 2355 actual function performed by the POST method is determined by the 2356 origin server and dependent on the resource identified by the request 2357 URI. 2359 If the action performed by the POST method does not result in a 2360 resource that can be identified by a URI, a 200 (OK) or 204 (No 2361 Content) response MUST be returned to the client. If a resource has 2362 been created on the origin server, a 201 (Created) response MUST be 2363 returned. 2365 8.2.5. PUT 2367 The PUT method requests the proxy to update or create the CoAP 2368 resource identified by the Request-URI with the enclosed 2369 representation. 2371 If a new resource is created at the Request-URI, a 201 (Created) 2372 response MUST be returned to the client. If an existing resource is 2373 modified, either the 200 (OK) or 204 (No Content) response codes 2374 SHOULD be sent to indicate successful completion of the request. 2376 8.2.6. DELETE 2378 The DELETE method requests the proxy to delete the CoAP resource 2379 identified by the Request-URI at the CoAP origin server. 2381 A successful response SHOULD be 200 (OK) if the response includes an 2382 entity describing the status or 204 (No Content) if the action has 2383 been enacted but the response does not include an entity. 2385 8.2.7. CONNECT 2387 This method can not currently be satisfied by an HTTP-CoAP proxy 2388 function as TLS to DTLS tunneling has not been specified. It is 2389 however expected that such a tunneling mapping will be defined in the 2390 future. A 501 (Not Implemented) error SHOULD be returned to the 2391 client. 2393 9. Protocol Constants 2395 This section defines the relevant protocol constants defined in this 2396 document: 2398 RESPONSE_TIMEOUT 2 seconds 2400 RESPONSE_RANDOM_FACTOR 1.5 2402 MAX_RETRANSMIT 4 2404 Future specifications are expected that will allow implementations to 2405 use other sources for initializing RESPONSE_TIMEOUT. The 2406 RESPONSE_TIMEOUT variable MAY be configured with a different value 2407 for special environments that exhibit very short or very long RTTs. 2409 10. Security Considerations 2411 This section defines the DTLS binding for CoAP, the alternative use 2412 of IPsec, and analyzes the possible threats to the protocol and its 2413 limitations. 2415 During the provisioning phase, a CoAP device is provided with the 2416 security information that it needs, including keying materials and 2417 access control lists. This specification defines provisioning for 2418 the RawPublicKey mode in Appendix D.2. At the end of the 2419 provisioning phase, the device will be in one of four security modes 2420 with the following information for the given mode. The NoSec and 2421 RawPublicKey modes are mandatory to implement for this specification. 2423 NoSec: There is no protocol level security (DTLS is disabled). 2424 Alternative techniques to provide lower layer security SHOULD be 2425 used when appropriate. The use of IPsec is discussed in 2426 Section 10.2. 2428 PreSharedKey: DTLS is enabled and there is a list of pre-shared keys 2429 and each key includes a list of which nodes it can be used to 2430 communicate with as described in Section 10.1.1. At the extreme 2431 there may be one key for each node this CoAP node needs to 2432 communicate with (1:1 node/key ratio). 2434 RawPublicKey: DTLS is enabled and the device has an asymmetric key 2435 pair, but without an X.509 certificate as described in 2436 Section 10.1.2. The device also has an identity calculated from 2437 the public key and a list of identities of the nodes it can 2438 communicate with. 2440 Certificate: DTLS is enabled and the device has an asymmetric key 2441 pair with an X.509 [RFC5280] certificate that binds it to its 2442 Authority Name and is signed by some common trust root as 2443 described in Section 10.1.3. The device also has a list of root 2444 trust anchors that can be used for validating a certificate. 2446 In the "NoSec" mode, the system simply sends the packets over normal 2447 UDP over IP and is indicated by the "coap" scheme and the CoAP 2448 default port. The system is secured only by keeping attackers from 2449 being able to send or receive packets from the network with the CoAP 2450 nodes; see Section 10.3.5 for an additional complication with this 2451 approach. 2453 The other three security modes are achieved using DTLS and are 2454 indicated by the "coaps" scheme and DTLS-secured CoAP default port. 2455 The result is a security association that can be used to authenticate 2456 (within the limits of the security model) and, based on this 2457 authentication, authorize the communication partner. CoAP itself 2458 does not provide protocol primitives for authentication or 2459 authorization; where this is required, it can either be provided by 2460 communication security (i.e., IPsec or DTLS) or by object security 2461 (within the payload). Devices that require authorization for certain 2462 operations are expected to require one of these two forms of 2463 security. Necessarily, where an intermediary is involved, 2464 communication security only works when that intermediary is part of 2465 the trust relationships; CoAP does not provide a way to forward 2466 different levels of authorization that clients may have with an 2467 intermediary to further intermediaries or origin servers -- it 2468 therefore may be required to perform all authorization at the first 2469 intermediary. 2471 10.1. Securing CoAP with DTLS 2473 Just as HTTP is secured using Transport Layer Security (TLS) over 2474 TCP, CoAP is secured using Datagram TLS (DTLS) [RFC4347] over UDP. 2475 This section defines the CoAP binding to DTLS, along with the minimal 2476 MUST implement configurations appropriate for constrained 2477 environments. DTLS is in practice TLS with added features to deal 2478 with the unreliable nature of the UDP transport. 2480 In some constrained nodes (limited flash and/or RAM) and networks 2481 (limited bandwidth or high scalability requirements), and depending 2482 on the specific cipher suites in use, DTLS may not be applicable. 2483 Some of DTLS' cipher suites can add significant implementation 2484 complexity as well as some initial handshake overhead needed when 2485 setting up the security association. Once the initial handshake is 2486 completed, DTLS adds a limited per-datagram overhead of approximately 2487 13 bytes, not including any initialization vectors (which are 2488 generally implicitly derived with DTLS), integrity check values 2489 (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 2490 [I-D.mcgrew-tls-aes-ccm]) and padding required by the cipher suite. 2491 Whether and which mode of using DTLS is applicable for a CoAP-based 2492 application should be carefully weighed considering the specific 2493 cipher suites that may be applicable, and whether the session 2494 maintenance makes it compatible with application flows and sufficient 2495 resources are available on the constrained nodes and for the added 2496 network overhead. DTLS is not applicable to group keying (multicast 2497 communication); however, it may be a component in a future group key 2498 management protocol. 2500 Devices SHOULD support the Server Name Indication (SNI) to indicate 2501 their Authority Name in the SNI HostName field as defined in Section 2502 3 of [RFC6066]. This is needed so that when a host that acts as a 2503 virtual server for multiple Authorities receives a new DTLS 2504 connection, it knows which keys to use for the DTLS session. 2506 DTLS connections in RawPublicKey and Certificate mode are set up 2507 using mutual authentication so they can remain up and be reused for 2508 future message exchanges in either direction. Devices can close a 2509 DTLS connection when they need to recover resources but in general 2510 they should keep the connection up for as long as possible. Closing 2511 the DTLS connection after every CoAP message exchange is very 2512 inefficient. 2514 10.1.1. PreSharedKey Mode 2516 When forming a connection to a new node, the system selects an 2517 appropriate key based on which nodes it is trying to reach then forms 2518 a DTLS session using a PSK (Pre-Shared Key) mode of DTLS. 2519 Implementations in these modes MUST support the mandatory to 2520 implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in 2521 [I-D.mcgrew-tls-aes-ccm]. 2523 The security considerations of [RFC4279] (Section 7) apply. In 2524 particular, applications should carefully weigh whether they need 2525 Perfect Forward Secrecy (PFS) or not and select an appropriate cipher 2526 suite (7.1). The entropy of the PSK must be sufficient to mitigate 2527 against brute-force and (where the PSK is not chosen randomly but by 2528 a human) dictionary attacks (7.2). The cleartext communication of 2529 client identities may leak data or compromise privacy (7.3). 2531 10.1.2. RawPublicKey Mode 2533 In this mode the device has an asymmetric key pair but without an 2534 X.509 certificate (called a raw public key). A device MAY be 2535 configured with multiple raw public keys. The type and length of the 2536 raw public key depends on the cipher suite used. Implementations in 2537 RawPublicKey mode MUST support the mandatory to implement cipher 2538 suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in [RFC5246], 2539 [RFC4492]. 2541 TLS does not currently define a way to carry a raw public key during 2542 the handshake phase. The raw public key is therefore wrapped in an 2543 X.509 certificate [RFC5280]. The only requirement on this 2544 certificate is that it MUST have a subjectPublicKeyInfo field with 2545 the algorithm set to that of the cipher suite used and the public key 2546 placed in subjectPublicKey field. The certificate MAY additionally 2547 have validity information. If the validity field is present and not 2548 currently valid, the certificate MUST be rejected. 2550 10.1.3. Certificate Mode 2552 Implementations in Certificate Mode MUST support the mandatory to 2553 implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as 2554 specified in [RFC5246]. 2556 The Authority Name in the certificate is the name that would be used 2557 in the Authority part of a CoAP URI. It is worth noting that this 2558 would typically not be either an IP address or DNS name but would 2559 instead be a long term unique identifier for the device such as the 2560 EUI-64 [EUI64]. The discovery process used in the system would build 2561 up the mapping between IP addresses of the given devices and the 2562 Authority Name for each device. Some devices could have more than 2563 one Authority and would need more than a single certificate. 2565 When a new connection is formed, the certificate from the remote 2566 device needs to be verified. If the CoAP node has a source of 2567 absolute time, then the node SHOULD check the validity dates are of 2568 the certificate are within range. The certificate MUST also be 2569 signed by an appropriate chain of trust. If the certificate contains 2570 a SubjectAltName, then the Authority Name MUST match at least one of 2571 the authority names of any CoAP URI found in a URI type fields in the 2572 SubjectAltName set. If there is no SubjectAltName in the 2573 certificate, then the Authoritative Name must match the CN found in 2574 the certificate using the matching rules defined in [RFC2818] with 2575 the exception that certificates with wildcards are not allowed. 2576 Further access control is performed as described in Appendix D.3.3. 2578 If the system has a shared key in addition to the certificate, then a 2579 cipher suite that includes the shared key such as 2580 TLS_RSA_PSK_WITH_AES_128_CBC_SHA SHOULD be used. 2582 10.2. Using CoAP with IPsec 2584 One mechanism to secure CoAP in constrained environments is the IPsec 2585 Encapsulating Security Payload (ESP) [RFC4303] when CoAP is used 2586 without DTLS in NoSec Mode. Using IPsec ESP with the appropriate 2587 configuration, it is possible for many constrained devices to support 2588 encryption with built-in link-layer encryption hardware. For 2589 example, some IEEE 802.15.4 radio chips are compatible with AES-CBC 2590 (with 128-bit keys) [RFC3602] as defined for use with IPsec in 2591 [RFC4835]. Alternatively, particularly on more common IEEE 802.15.4 2592 hardware that supports AES encryption but not decryption, and to 2593 avoid the need for padding, nodes could directly use the more widely 2594 supported AES-CCM as defined for use with IPsec in [RFC4309], if the 2595 security considerations in Section 9 of that specification can be 2596 fulfilled. 2598 Necessarily for AES-CCM, but much preferably also for AES-CBC, static 2599 keying should be avoided and the initial keying material be derived 2600 into transient session keys, e.g. using a low-overhead mode of IKEv2 2601 [RFC5996] as described in [I-D.kivinen-ipsecme-ikev2-minimal]; such a 2602 protocol for managing keys and sequence numbers is also the only way 2603 to achieve anti-replay capabilities. However, no recommendation can 2604 be made at this point on how to manage group keys (i.e., for 2605 multicast) in a constrained environment. Once any initial setup is 2606 completed, IPsec ESP adds a limited overhead of approximately 10 2607 bytes per packet, not including initialization vectors, integrity 2608 check values and padding required by the cipher suite. 2610 When using IPsec to secure CoAP, both authentication and 2611 confidentiality SHOULD be applied as recommended in [RFC4303]. The 2612 use of IPsec between CoAP end-points is transparent to the 2613 application layer and does not require special consideration for a 2614 CoAP implementation. 2616 IPsec may not be appropriate for all environments. For example, 2617 IPsec support is not available for many embedded IP stacks and even 2618 in full PC operating systems or on back-end web servers, application 2619 developers may not have sufficient access to configure or enable 2620 IPsec or to add a security gateway to the infrastructure. Problems 2621 with firewalls and NATs may furthermore limit the use of IPsec. 2623 10.3. Threat analysis and protocol limitations 2625 This section is meant to inform protocol and application developers 2626 about the security limitations of CoAP as described in this document. 2627 As CoAP realizes a subset of the features in HTTP/1.1, the security 2628 considerations in Section 15 of [RFC2616] are also pertinent to CoAP. 2629 This section concentrates on describing limitations specific to CoAP. 2631 10.3.1. Protocol Parsing, Processing URIs 2633 A network-facing application can exhibit vulnerabilities in its 2634 processing logic for incoming packets. Complex parsers are well- 2635 known as a likely source of such vulnerabilities, such as the ability 2636 to remotely crash a node, or even remotely execute arbitrary code on 2637 it. CoAP attempts to narrow the opportunities for introducing such 2638 vulnerabilities by reducing parser complexity, by giving the entire 2639 range of encodable values a meaning where possible, and by 2640 aggressively reducing complexity that is often caused by unnecessary 2641 choice between multiple representations that mean the same thing. 2642 Much of the URI processing has been moved to the clients, further 2643 reducing the opportunities for introducing vulnerabilities into the 2644 servers. Even so, the URI processing code in CoAP implementations is 2645 likely to be a large source of remaining vulnerabilities and should 2646 be implemented with special care. The most complex parser remaining 2647 could be the one for the link-format, although this also has been 2648 designed with a goal of reduced implementation complexity 2649 [I-D.ietf-core-link-format]. (See also section 15.2 of [RFC2616].) 2651 10.3.2. Proxying and Caching 2653 As mentioned in 15.7 of [RFC2616], which see, proxies are by their 2654 very nature men-in-the-middle, breaking any IPsec or DTLS protection 2655 that a direct CoAP message exchange might have. They are therefore 2656 interesting targets for breaking confidentiality or integrity of CoAP 2657 message exchanges. As noted in [RFC2616], they are also interesting 2658 targets for breaking availability. 2660 The threat to confidentiality and integrity of request/response data 2661 is amplified where proxies also cache. Note that CoAP does not 2662 define any of the cache-suppressing Cache-Control options that 2663 HTTP/1.1 provides to better protect sensitive data. 2665 Finally, a proxy that fans out Separate Responses (as opposed to 2666 Piggy-backed Responses) to multiple original requesters may provide 2667 additional amplification (see below). 2669 10.3.3. Risk of amplification 2671 CoAP servers generally reply to a request packet with a response 2672 packet. This response packet may be significantly larger than the 2673 request packet. An attacker might use CoAP nodes to turn a small 2674 attack packet into a larger attack packet, an approach known as 2675 amplification. There is therefore a danger that CoAP nodes could 2676 become implicated in denial of service (DoS) attacks by using the 2677 amplifying properties of the protocol: An attacker that is attempting 2678 to overload a victim but is limited in the amount of traffic it can 2679 generate, can use amplification to generate a larger amount of 2680 traffic. 2682 This is particularly a problem in nodes that enable NoSec access, 2683 that are accessible from an attacker and can access potential victims 2684 (e.g. on the general Internet), as the UDP protocol provides no way 2685 to verify the source address given in the request packet. An 2686 attacker need only place the IP address of the victim in the source 2687 address of a suitable request packet to generate a larger packet 2688 directed at the victim. 2690 As a mitigating factor, many constrained networks will only be able 2691 to generate a small amount of traffic, which may make CoAP nodes less 2692 attractive for this attack. However, the limited capacity of the 2693 constrained network makes the network itself a likely victim of an 2694 amplification attack. 2696 A CoAP server can reduce the amount of amplification it provides to 2697 an attacker by using slicing/blocking modes of CoAP 2698 [I-D.ietf-core-block] and offering large resource representations 2699 only in relatively small slices. E.g., for a 1000 byte resource, a 2700 10-byte request might result in an 80-byte response (with a 64-byte 2701 block) instead of a 1016-byte response, considerably reducing the 2702 amplification provided. 2704 CoAP also supports the use of multicast IP addresses in requests, an 2705 important requirement for M2M. Multicast CoAP requests may be the 2706 source of accidental or deliberate denial of service attacks, 2707 especially over constrained networks. This specification attempts to 2708 reduce the amplification effects of multicast requests by limiting 2709 when a response is returned. To limit the possibility of malicious 2710 use, CoAP servers SHOULD NOT accept multicast requests that can not 2711 be authenticated. If possible a CoAP server SHOULD limit the support 2712 for multicast requests to specific resources where the feature is 2713 required. 2715 On some general purpose operating systems providing a Posix-style 2716 API, it is not straightforward to find out whether a packet received 2717 was addressed to a multicast address. While many implementations 2718 will know whether they have joined a multicast group, this creates a 2719 problem for packets addressed to multicast addresses of the form 2720 FF0x::1, which are received by every IPv6 node. Implementations 2721 SHOULD make use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if 2722 available, to make this determination. 2724 10.3.4. IP Address Spoofing Attacks 2726 Due to the lack of a handshake in UDP, a rogue endpoint which is free 2727 to read and write messages carried by the constrained network (i.e. 2728 NoSec or PreSharedKey deployments with nodes/key ratio > 1:1), may 2729 easily attack a single endpoint, a group of endpoints, as well as the 2730 whole network e.g. by: 2732 1. spoofing RST in response to a CON message, thus making an 2733 endpoint "deaf"; or 2735 2. spoofing the entire response with forged payload/options (this 2736 has different levels of impact: from single response disruption, 2737 to much bolder attacks on the supporting infrastructure, e.g. 2738 poisoning proxy caches, or tricking validation / lookup 2739 interfaces in resource directories and, more generally, any 2740 component that stores global network state and uses CoAP as the 2741 messaging facility to handle state set/update's is a potential 2742 target.); or 2744 3. spoofing a multicast request for a target node which may result 2745 in both network congestion/collapse and victim DoS'ing / forced 2746 wakeup from sleeping; or 2748 4. spoofing observe messages, etc. 2750 In principle, spoofing can be detected by CoAP only in case CON 2751 semantics is used, because of unexpected ACK/RSTs coming from the 2752 deceived endpoint. But this imposes keeping track of the used MIDs 2753 which is not always possible, and moreover detection becomes 2754 available usually after the damage is already done. This kind of 2755 attack can be prevented using security modes other than NoSec. 2757 10.3.5. Cross-Protocol Attacks 2759 The ability to incite a CoAP end-point to send packets to a fake 2760 source address can be used not only for amplification, but also for 2761 cross-protocol attacks: 2763 o the attacker sends a message to a CoAP end-point with a fake 2764 source address, 2766 o the CoAP end-point replies with a message to the given source 2767 address, 2769 o the victim at the given source address receives a UDP packet that 2770 it interprets according to the rules of a different protocol. 2772 This may be used to circumvent firewall rules that prevent direct 2773 communication from the attacker to the victim, but happen to allow 2774 communication from the CoAP end-point (which may also host a valid 2775 role in the other protocol) to the victim. 2777 Also, CoAP end-points may be the victim of a cross-protocol attack 2778 generated through an end-point of another UDP-based protocol such as 2779 DNS. In both cases, attacks are possible if the security properties 2780 of the end-points rely on checking IP addresses (and firewalling off 2781 direct attacks sent from outside using fake IP addresses). In 2782 general, because of their lack of context, UDP-based protocols are 2783 relatively easy targets for cross-protocol attacks. 2785 Finally, CoAP URIs transported by other means could be used to incite 2786 clients to send messages to end-points of other protocols. 2788 One mitigation against cross-protocol attacks is strict checking of 2789 the syntax of packets received, combined with sufficient difference 2790 in syntax. As an example, it might help if it were difficult to 2791 incite a DNS server to send a DNS response that would pass the checks 2792 of a CoAP end-point. Unfortunately, the first two bytes of a DNS 2793 reply are an ID that can be chosen by the attacker, which map into 2794 the interesting part of the CoAP header, and the next two bytes are 2795 then interpreted as CoAP's Message ID (i.e., any value is 2796 acceptable). The DNS count words may be interpreted as multiple 2797 instances of a (non-existent, but elective) CoAP option 0. The 2798 echoed query finally may be manufactured by the attacker to achieve a 2799 desired effect on the CoAP end-point; the response added by the 2800 server (if any) might then just be interpreted as added payload. 2802 1 1 1 1 1 1 2803 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 2804 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2805 | ID | T, OC, code 2806 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2807 |QR| Opcode |AA|TC|RD|RA| Z | RCODE | message id 2808 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2809 | QDCOUNT | (options 0) 2810 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2811 | ANCOUNT | (options 0) 2812 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2813 | NSCOUNT | (options 0) 2814 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2815 | ARCOUNT | (options 0) 2816 +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ 2818 Figure 10: DNS Header vs. CoAP Message 2820 In general, for any pair of protocols, one of the protocols can very 2821 well have been designed in a way that enables an attacker to cause 2822 the generation of replies that look like messages of the other 2823 protocol. It is often much harder to ensure or prove the absence of 2824 viable attacks than to generate examples that may not yet completely 2825 enable an attack but might be further developed by more creative 2826 minds. Cross-protocol attacks can therefore only be completely 2827 mitigated if end-points don't authorize actions desired by an 2828 attacker just based on trusting the source IP address of a packet. 2829 Conversely, a NoSec environment that completely relies on a firewall 2830 for CoAP security not only needs to firewall off the CoAP end-points 2831 but also all other end-points that might be incited to send UDP 2832 messages to CoAP end-points using some other UDP-based protocol. 2834 In addition to the considerations above, the security considerations 2835 for DTLS with respect to cross-protocol attacks apply. E.g., if the 2836 same DTLS security association ("connection") is used to carry data 2837 of multiple protocols, DTLS no longer provides protection against 2838 cross-protocol attacks between these protocols. 2840 11. IANA Considerations 2841 11.1. CoAP Code Registry 2843 This document defines a registry for the values of the Code field in 2844 the CoAP header. The name of the registry is "CoAP Codes". 2846 All values are assigned by sub-registries according to the following 2847 ranges: 2849 0 Indicates an empty message (see Section 4.4). 2851 1-31 Indicates a request. Values in this range are assigned by 2852 the "CoAP Method Codes" sub-registry (see Section 11.1.1). 2854 32-63 Reserved 2856 64-191 Indicates a response. Values in this range are assigned by 2857 the "CoAP Response Codes" sub-registry (see 2858 Section 11.1.2). 2860 192-255 Reserved 2862 11.1.1. Method Codes 2864 The name of the sub-registry is "CoAP Method Codes". 2866 Each entry in the sub-registry must include the Method Code in the 2867 range 1-31, the name of the method, and a reference to the method's 2868 documentation. 2870 Initial entries in this sub-registry are as follows: 2872 +------+--------+-----------+ 2873 | Code | Name | Reference | 2874 +------+--------+-----------+ 2875 | 1 | GET | [RFCXXXX] | 2876 | 2 | POST | [RFCXXXX] | 2877 | 3 | PUT | [RFCXXXX] | 2878 | 4 | DELETE | [RFCXXXX] | 2879 +------+--------+-----------+ 2881 Table 2: CoAP Method Codes 2883 All other Method Codes are Unassigned. 2885 The IANA policy for future additions to this registry is "IETF 2886 Review" as described in [RFC5226]. 2888 The documentation of a method code should specify the semantics of a 2889 request with that code, including the following properties: 2891 o The response codes the method returns in the success case. 2893 o Whether the method is idempotent, safe, or both. 2895 o Whether the request causes a cache to mark responses stored for 2896 the request URI as not fresh. 2898 11.1.2. Response Codes 2900 The name of the sub-registry is "CoAP Response Codes". 2902 Each entry in the sub-registry must include the Response Code in the 2903 range 64-191, a description of the Response Code, and a reference to 2904 the Response Code's documentation. 2906 Initial entries in this sub-registry are as follows: 2908 +------+-------------------------------+-----------+ 2909 | Code | Description | Reference | 2910 +------+-------------------------------+-----------+ 2911 | 65 | 2.01 Created | [RFCXXXX] | 2912 | 66 | 2.02 Deleted | [RFCXXXX] | 2913 | 67 | 2.03 Valid | [RFCXXXX] | 2914 | 68 | 2.04 Changed | [RFCXXXX] | 2915 | 69 | 2.05 Content | [RFCXXXX] | 2916 | 128 | 4.00 Bad Request | [RFCXXXX] | 2917 | 129 | 4.01 Unauthorized | [RFCXXXX] | 2918 | 130 | 4.02 Bad Option | [RFCXXXX] | 2919 | 131 | 4.03 Forbidden | [RFCXXXX] | 2920 | 132 | 4.04 Not Found | [RFCXXXX] | 2921 | 133 | 4.05 Method Not Allowed | [RFCXXXX] | 2922 | 134 | 4.06 Not Acceptable | [RFCXXXX] | 2923 | 140 | 4.12 Precondition Failed | [RFCXXXX] | 2924 | 141 | 4.13 Request Entity Too Large | [RFCXXXX] | 2925 | 143 | 4.15 Unsupported Media Type | [RFCXXXX] | 2926 | 160 | 5.00 Internal Server Error | [RFCXXXX] | 2927 | 161 | 5.01 Not Implemented | [RFCXXXX] | 2928 | 162 | 5.02 Bad Gateway | [RFCXXXX] | 2929 | 163 | 5.03 Service Unavailable | [RFCXXXX] | 2930 | 164 | 5.04 Gateway Timeout | [RFCXXXX] | 2931 | 165 | 5.05 Proxying Not Supported | [RFCXXXX] | 2932 +------+-------------------------------+-----------+ 2934 Table 3: CoAP Response Codes 2936 The Response Codes 96-127 are Reserved for future use. All other 2937 Response Codes are Unassigned. 2939 The IANA policy for future additions to this registry is "IETF 2940 Review" as described in [RFC5226]. 2942 The documentation of a response code should specify the semantics of 2943 a response with that code, including the following properties: 2945 o The methods the response code applies to. 2947 o Whether payload is required, optional or not allowed. 2949 o The semantics of the payload. For example, the payload of a 2.05 2950 (Content) response is a representation of the target resource; the 2951 payload in an error response is a human-readable diagnostic 2952 message. 2954 o The format of the payload. For example, the format in a 2.05 2955 (Content) response is indicated by the Content-Type Option; the 2956 format of the payload in an error response is always Net-Unicode 2957 text. 2959 o Whether the response is cacheable according to the freshness 2960 model. 2962 o Whether the response is validatable according to the validation 2963 model. 2965 o Whether the response causes a cache to mark responses stored for 2966 the request URI as not fresh. 2968 11.2. Option Number Registry 2970 This document defines a registry for the Option Numbers used in CoAP 2971 options. The name of the registry is "CoAP Option Numbers". 2973 Each entry in the registry must include the Option Number, the name 2974 of the option and a reference to the option's documentation. 2976 Initial entries in this registry are as follows: 2978 +--------+----------------+-----------+ 2979 | Number | Name | Reference | 2980 +--------+----------------+-----------+ 2981 | 1 | Content-Type | [RFCXXXX] | 2982 | 2 | Max-Age | [RFCXXXX] | 2983 | 3 | Proxy-Uri | [RFCXXXX] | 2984 | 4 | ETag | [RFCXXXX] | 2985 | 5 | Uri-Host | [RFCXXXX] | 2986 | 6 | Location-Path | [RFCXXXX] | 2987 | 7 | Uri-Port | [RFCXXXX] | 2988 | 8 | Location-Query | [RFCXXXX] | 2989 | 9 | Uri-Path | [RFCXXXX] | 2990 | 11 | Token | [RFCXXXX] | 2991 | 12 | Accept | [RFCXXXX] | 2992 | 13 | If-Match | [RFCXXXX] | 2993 | 15 | Uri-Query | [RFCXXXX] | 2994 | 21 | If-None-Match | [RFCXXXX] | 2995 +--------+----------------+-----------+ 2997 Table 4: CoAP Option Numbers 2999 The Option Number 0 is Reserved for future use. The Option Numbers 3000 14, 28, 42, ... are Reserved for "fenceposting" (see Section 3.2). 3001 All other Option Numbers are Unassigned. 3003 The IANA policy for future additions to this registry is "IETF 3004 Review" as described in [RFC5226]. 3006 The documentation of an Option Number should specify the semantics of 3007 an option with that number, including the following properties: 3009 o The meaning of the option in a request. 3011 o The meaning of the option in a response. 3013 o Whether the option is critical of elective, as determined by the 3014 Option Number. 3016 o The format and length of the option's value. 3018 o Whether the option must occur at most once or whether it can occur 3019 multiple times. 3021 o The default value, if any. 3023 11.3. Media Type Registry 3025 Media types are identified by a string, such as "application/xml" 3026 [RFC2046]. In order to minimize the overhead of using these media 3027 types to indicate the format of payloads, this document defines a 3028 registry for a subset of Internet media types to be used in CoAP and 3029 assigns each a numeric identifier. The name of the registry is "CoAP 3030 Media Types". 3032 Each entry in the registry must include the media type registered 3033 with IANA, the numeric identifier in the range 0-65535 to be used for 3034 that media type in CoAP, and a reference to a document describing 3035 what payload with that media type means semantically. 3037 Initial entries in this registry are as follows: 3039 +---------------------------+-----+-----------------------------+ 3040 | Media type | Id. | Reference | 3041 +---------------------------+-----+-----------------------------+ 3042 | text/plain; charset=utf-8 | 0 | [RFC2046][RFC3676][RFC5147] | 3043 | application/link-format | 40 | [I-D.ietf-core-link-format] | 3044 | application/xml | 41 | [RFC3023] | 3045 | application/octet-stream | 42 | [RFC2045][RFC2046] | 3046 | application/exi | 47 | [EXIMIME] | 3047 | application/json | 50 | [RFC4627] | 3048 +---------------------------+-----+-----------------------------+ 3050 Table 5: CoAP Media Types 3052 The identifiers between 201 and 255 inclusive are reserved for 3053 Private Use. All other identifiers are Unassigned. 3055 Because the name space of single-byte identifiers is so small, the 3056 IANA policy for future additions in the range 0-200 inclusive to the 3057 registry is "Expert Review" as described in [RFC5226]. The IANA 3058 policy for additions in the range 256-65535 inclusive is "First Come 3059 First Served" as described in [RFC5226]. 3061 In machine to machine applications, it is not expected that generic 3062 Internet media types such as text/plain, application/xml or 3063 application/octet-stream are useful for real applications in the long 3064 term. It is recommended that M2M applications making use of CoAP 3065 will request new Internet media types from IANA indicating semantic 3066 information about how to create or parse a payload. For example, a 3067 Smart Energy application payload carried as XML might request a more 3068 specific type like application/se+xml or application/se+exi. 3070 11.4. URI Scheme Registration 3072 This document requests the registration of the Uniform Resource 3073 Identifier (URI) scheme "coap". The registration request complies 3074 with [RFC4395]. 3076 URI scheme name. 3077 coap 3079 Status. 3080 Permanent. 3082 URI scheme syntax. 3083 Defined in Section 6.1 of [RFCXXXX]. 3085 URI scheme semantics. 3086 The "coap" URI scheme provides a way to identify resources that 3087 are potentially accessible over the Constrained Application 3088 Protocol (CoAP). The resources can be located by contacting the 3089 governing CoAP server and operated on by sending CoAP requests to 3090 the server. This scheme can thus be compared to the "http" URI 3091 scheme [RFC2616]. See Section 6 of [RFCXXXX] for the details of 3092 operation. 3094 Encoding considerations. 3095 The scheme encoding conforms to the encoding rules established for 3096 URIs in [RFC3986], i.e. internationalized and reserved characters 3097 are expressed using UTF-8-based percent-encoding. 3099 Applications/protocols that use this URI scheme name. 3100 The scheme is used by CoAP end-points to access CoAP resources. 3102 Interoperability considerations. 3103 None. 3105 Security considerations. 3106 See Section 10.3.1 of [RFCXXXX]. 3108 Contact. 3109 IETF Chair 3111 Author/Change controller. 3112 IESG 3114 References. 3115 [RFCXXXX] 3117 11.5. Secure URI Scheme Registration 3119 This document requests the registration of the Uniform Resource 3120 Identifier (URI) scheme "coaps". The registration request complies 3121 with [RFC4395]. 3123 URI scheme name. 3124 coaps 3126 Status. 3127 Permanent. 3129 URI scheme syntax. 3130 Defined in Section 6.2 of [RFCXXXX]. 3132 URI scheme semantics. 3133 The "coaps" URI scheme provides a way to identify resources that 3134 are potentially accessible over the Constrained Application 3135 Protocol (CoAP) using DTLS for session security. The resources 3136 can be located by contacting the governing CoAP server and 3137 operated on by sending CoAP requests to the server. This scheme 3138 can thus be compared to the "https" URI scheme [RFC2616]. See 3139 Section 6 of [RFCXXXX] for the details of operation. 3141 Encoding considerations. 3142 The scheme encoding conforms to the encoding rules established for 3143 URIs in [RFC3986], i.e. internationalized and reserved characters 3144 are expressed using UTF-8-based percent-encoding. 3146 Applications/protocols that use this URI scheme name. 3147 The scheme is used by CoAP end-points to access CoAP resources 3148 using DTLS. 3150 Interoperability considerations. 3151 None. 3153 Security considerations. 3154 See Section 10.3.1 of [RFCXXXX]. 3156 Contact. 3157 IETF Chair 3159 Author/Change controller. 3160 IESG 3162 References. 3163 [RFCXXXX] 3165 11.6. Service Name and Port Number Registration 3167 One of the functions of CoAP is resource discovery: a CoAP client can 3168 ask a CoAP server about the resources offered by it (see 3169 Section 7.1). To enable resource discovery just based on the 3170 knowledge of an IP address, the CoAP port for resource discovery 3171 needs to be standardized. 3173 IANA has assigned the port number 5683 and the service name "coap", 3174 in accordance with [I-D.ietf-tsvwg-iana-ports]. 3176 Besides unicast, CoAP can be used with both multicast and anycast. 3178 Service Name. 3179 coap 3181 Transport Protocol. 3182 UDP 3184 Assignee. 3185 IESG 3187 Contact. 3188 IETF Chair 3190 Description. 3191 Constrained Application Protocol (CoAP) 3193 Reference. 3194 [RFCXXXX] 3196 Port Number. 3197 5683 3199 11.7. Secure Service Name and Port Number Registration 3201 CoAP resource discovery may also be provided using the DTLS-secured 3202 CoAP "coaps" scheme. Thus the CoAP port for secure resource 3203 discovery needs to be standardized. 3205 This document requests the assignment of the port number 3206 [IANA_TBD_PORT] and the service name "coaps", in accordance with 3207 [I-D.ietf-tsvwg-iana-ports]. 3209 Besides unicast, Secure CoAP can be used with anycast. 3211 Service Name. 3212 coaps 3214 Transport Protocol. 3215 UDP 3217 Assignee. 3218 IESG 3220 Contact. 3221 IETF Chair 3223 Description. 3224 DTLS-secured CoAP 3226 Reference. 3227 [RFCXXXX] 3229 Port Number. 3230 [IANA_TBD_PORT] 3232 12. Acknowledgements 3234 Special thanks to Peter Bigot and Cullen Jennings for substantial 3235 contributions to the ideas and text in the document, along with 3236 countless detailed reviews and discussions. 3238 Thanks to Michael Stuber, Richard Kelsey, Guido Moritz, Peter Van Der 3239 Stok, Adriano Pezzuto, Lisa Dussealt, Alexey Melnikov, Gilbert Clark, 3240 Salvatore Loreto, Petri Mutka, Szymon Sasin, Robert Quattlebaum, 3241 Robert Cragie, Angelo Castellani, Tom Herbst, Ed Beroset, Gilman 3242 Tolle, Robby Simpson, Colin O'Flynn, Eric Rescorla, Matthieu Vial, 3243 Linyi Tian, Kerry Lynn, Dale Seed, Akbar Rahman, Charles Palmer, 3244 Thomas Fossati and David Ryan for helpful comments and discussions 3245 that have shaped the document. 3247 Some of the text has been lifted from the working documents of the 3248 IETF httpbis working group. 3250 13. References 3252 13.1. Normative References 3254 [I-D.ietf-core-link-format] 3255 Shelby, Z., "CoRE Link Format", 3256 draft-ietf-core-link-format-07 (work in progress), 3257 July 2011. 3259 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3260 Extensions (MIME) Part One: Format of Internet Message 3261 Bodies", RFC 2045, November 1996. 3263 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 3264 Extensions (MIME) Part Two: Media Types", RFC 2046, 3265 November 1996. 3267 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3268 Requirement Levels", BCP 14, RFC 2119, March 1997. 3270 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3271 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3272 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3274 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3276 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 3277 Types", RFC 3023, January 2001. 3279 [RFC3602] Frankel, S., Glenn, R., and S. Kelly, "The AES-CBC Cipher 3280 Algorithm and Its Use with IPsec", RFC 3602, 3281 September 2003. 3283 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3284 10646", STD 63, RFC 3629, November 2003. 3286 [RFC3676] Gellens, R., "The Text/Plain Format and DelSp Parameters", 3287 RFC 3676, February 2004. 3289 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3290 Resource Identifier (URI): Generic Syntax", STD 66, 3291 RFC 3986, January 2005. 3293 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 3294 for Transport Layer Security (TLS)", RFC 4279, 3295 December 2005. 3297 [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", 3298 RFC 4303, December 2005. 3300 [RFC4309] Housley, R., "Using Advanced Encryption Standard (AES) CCM 3301 Mode with IPsec Encapsulating Security Payload (ESP)", 3302 RFC 4309, December 2005. 3304 [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3305 Security", RFC 4347, April 2006. 3307 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 3308 Registration Procedures for New URI Schemes", BCP 35, 3309 RFC 4395, February 2006. 3311 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 3312 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 3313 for Transport Layer Security (TLS)", RFC 4492, May 2006. 3315 [RFC4627] Crockford, D., "The application/json Media Type for 3316 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 3318 [RFC4835] Manral, V., "Cryptographic Algorithm Implementation 3319 Requirements for Encapsulating Security Payload (ESP) and 3320 Authentication Header (AH)", RFC 4835, April 2007. 3322 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 3323 text/plain Media Type", RFC 5147, April 2008. 3325 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 3326 Interchange", RFC 5198, March 2008. 3328 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3329 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3330 May 2008. 3332 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3333 Specifications: ABNF", STD 68, RFC 5234, January 2008. 3335 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3336 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3338 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3339 Housley, R., and W. Polk, "Internet X.509 Public Key 3340 Infrastructure Certificate and Certificate Revocation List 3341 (CRL) Profile", RFC 5280, May 2008. 3343 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3344 Uniform Resource Identifiers (URIs)", RFC 5785, 3345 April 2010. 3347 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 3348 Address Text Representation", RFC 5952, August 2010. 3350 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 3352 [RFC5996] Kaufman, C., Hoffman, P., Nir, Y., and P. Eronen, 3353 "Internet Key Exchange Protocol Version 2 (IKEv2)", 3354 RFC 5996, September 2010. 3356 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 3357 Extension Definitions", RFC 6066, January 2011. 3359 13.2. Informative References 3361 [EUI64] "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) 3362 REGISTRATION AUTHORITY", April 2010, . 3365 [EXIMIME] "Efficient XML Interchange (EXI) Format 1.0", 3366 December 2009, . 3369 [I-D.eggert-core-congestion-control] 3370 Eggert, L., "Congestion Control for the Constrained 3371 Application Protocol (CoAP)", 3372 draft-eggert-core-congestion-control-01 (work in 3373 progress), January 2011. 3375 [I-D.ietf-core-block] 3376 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 3377 draft-ietf-core-block-04 (work in progress), July 2011. 3379 [I-D.ietf-httpbis-p1-messaging] 3380 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 3381 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 3382 J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and 3383 Message Parsing", draft-ietf-httpbis-p1-messaging-17 (work 3384 in progress), October 2011. 3386 [I-D.ietf-tsvwg-iana-ports] 3387 Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 3388 Cheshire, "Internet Assigned Numbers Authority (IANA) 3389 Procedures for the Management of the Service Name and 3390 Transport Protocol Port Number Registry", 3391 draft-ietf-tsvwg-iana-ports-10 (work in progress), 3392 February 2011. 3394 [I-D.kivinen-ipsecme-ikev2-minimal] 3395 Kivinen, T., "Minimal IKEv2", 3396 draft-kivinen-ipsecme-ikev2-minimal-00 (work in progress), 3397 February 2011. 3399 [I-D.mcgrew-tls-aes-ccm] 3400 McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for TLS", 3401 draft-mcgrew-tls-aes-ccm-01 (work in progress), 3402 March 2011. 3404 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 3405 with Session Description Protocol (SDP)", RFC 3264, 3406 June 2002. 3408 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 3409 "Advanced Sockets Application Program Interface (API) for 3410 IPv6", RFC 3542, May 2003. 3412 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 3413 "Transmission of IPv6 Packets over IEEE 802.15.4 3414 Networks", RFC 4944, September 2007. 3416 [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence 3417 Protocol (XMPP): Core", RFC 6120, March 2011. 3419 Appendix A. Integer Option Value Format 3421 Options of type uint contain a non-negative integer that is 3422 represented in network byte order using a variable number of bytes, 3423 as shown below. 3425 Length = 0 (implies value of 0) 3427 0 3428 0 1 2 3 4 5 6 7 3429 +-+-+-+-+-+-+-+-+ 3430 Length = 1 | 0-255 | 3431 +-+-+-+-+-+-+-+-+ 3433 0 1 3434 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 3435 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3436 Length = 2 | 0-65535 | 3437 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3439 Length = 3 is 24 bits, Length = 4 is 32 bits etc. 3441 Appendix B. Examples 3443 This section gives a number of short examples with message flows for 3444 GET requests. These examples demonstrate the basic operation, the 3445 operation in the presence of retransmissions, and multicast. 3447 Figure 11 shows a basic GET request causing a piggy-backed response: 3448 The client sends a Confirmable GET request for the resource 3449 coap://server/temperature to the server with a Message ID of 0x7d34. 3450 The request includes one Uri-Path Option (Delta 0 + 9 = 9, Length 11, 3451 Value "temperature"); the Token is left at its default value (empty). 3452 This request is a total of 16 bytes long. A 2.05 (Content) response 3453 is returned in the Acknowledgement message that acknowledges the 3454 Confirmable request, echoing both the Message ID 0x7d34 and the 3455 (implicitly empty) Token value. The response includes a Payload of 3456 "22.3 C" and is 10 bytes long. 3458 Client Server 3459 | | 3460 | | 3461 +----->| Header: GET (T=CON, Code=1, MID=0x7d34) 3462 | GET | Uri-Path: "temperature" 3463 | | 3464 | | 3465 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d34) 3466 | 2.05 | Payload: "22.3 C" 3467 | | 3469 0 1 2 3 3470 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 3471 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3472 | 1 | 0 | 1 | GET=1 | MID=0x7d34 | 3473 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3474 | 9 | 11 | "temperature" (11 B) ... 3475 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3477 0 1 2 3 3478 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 3479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3480 | 1 | 2 | 0 | 2.05=69 | MID=0x7d34 | 3481 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3482 | "22.3 C" (6 B) ... 3483 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3485 Figure 11: Confirmable request; piggy-backed response 3487 Figure 12 shows a similar example, but with the inclusion of an 3488 explicit Token Option (Delta 9 + 2 = 11, Length 1, Value 0x20) in the 3489 request and (Delta 11 + 0 = 11) in the response, increasing the sizes 3490 to 18 and 12 bytes, respectively. 3492 Client Server 3493 | | 3494 | | 3495 +----->| Header: GET (T=CON, Code=1, MID=0x7d35) 3496 | GET | Token: 0x20 3497 | | Uri-Path: "temperature" 3498 | | 3499 | | 3500 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d35) 3501 | 2.05 | Token: 0x20 3502 | | Payload: "22.3 C" 3503 | | 3505 0 1 2 3 3506 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 3507 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3508 | 1 | 0 | 2 | GET=1 | MID=0x7d35 | 3509 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3510 | 9 | 11 | "temperature" (11 B) ... 3511 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3512 | 2 | 1 | 0x20 | 3513 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3515 0 1 2 3 3516 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 3517 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3518 | 1 | 2 | 1 | 2.05=69 | MID=0x7d35 | 3519 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3520 | 11 | 1 | 0x20 | "22.3 C" (6 B) ... 3521 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 3523 Figure 12: Confirmable request; piggy-backed response 3525 In Figure 13, the Confirmable GET request is lost. After 3526 RESPONSE_TIMEOUT seconds, the client retransmits the request, 3527 resulting in a piggy-backed response as in the previous example. 3529 Client Server 3530 | | 3531 | | 3532 +----X | Header: GET (T=CON, Code=1, MID=0x7d36) 3533 | GET | Token: 0x31 3534 | | Uri-Path: "temperature" 3535 TIMEOUT | 3536 | | 3537 +----->| Header: GET (T=CON, Code=1, MID=0x7d36) 3538 | GET | Token: 0x31 3539 | | Uri-Path: "temperature" 3540 | | 3541 | | 3542 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d36) 3543 | 2.05 | Token: 0x31 3544 | | Payload: "22.3 C" 3545 | | 3547 Figure 13: Confirmable request (retransmitted); piggy-backed response 3549 In Figure 14, the first Acknowledgement message from the server to 3550 the client is lost. After RESPONSE_TIMEOUT seconds, the client 3551 retransmits the request. 3553 Client Server 3554 | | 3555 | | 3556 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 3557 | GET | Token: 0x42 3558 | | Uri-Path: "temperature" 3559 | | 3560 | | 3561 | X----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 3562 | 2.05 | Token: 0x42 3563 | | Payload: "22.3 C" 3564 TIMEOUT | 3565 | | 3566 +----->| Header: GET (T=CON, Code=1, MID=0x7d37) 3567 | GET | Token: 0x42 3568 | | Uri-Path: "temperature" 3569 | | 3570 | | 3571 |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d37) 3572 | 2.05 | Token: 0x42 3573 | | Payload: "22.3 C" 3574 | | 3576 Figure 14: Confirmable request; piggy-backed response (retransmitted) 3577 In Figure 15, the server acknowledges the Confirmable request and 3578 sends a 2.05 (Content) response separately in a Confirmable message. 3579 Note that the Acknowledgement message and the Confirmable response do 3580 not necessarily arrive in the same order as they were sent. The 3581 client acknowledges the Confirmable response. 3583 Client Server 3584 | | 3585 | | 3586 +----->| Header: GET (T=CON, Code=1, MID=0x7d38) 3587 | GET | Token: 0x53 3588 | | Uri-Path: "temperature" 3589 | | 3590 | | 3591 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d38) 3592 | | 3593 | | 3594 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7b) 3595 | 2.05 | Token: 0x53 3596 | | Payload: "22.3 C" 3597 | | 3598 | | 3599 +- - ->| Header: (T=ACK, Code=0, MID=0xad7b) 3600 | | 3602 Figure 15: Confirmable request; separate response 3604 Figure 16 shows an example where the client loses its state (e.g., 3605 crashes and is rebooted) right after sending a Confirmable request, 3606 so the separate response arriving some time later comes unexpected. 3607 In this case, the client rejects the Confirmable response with a 3608 Reset message. Note that the unexpected ACK is silently ignored. 3610 Client Server 3611 | | 3612 | | 3613 +----->| Header: GET (T=CON, Code=1, MID=0x7d39) 3614 | GET | Token: 0x64 3615 | | Uri-Path: "temperature" 3616 CRASH | 3617 | | 3618 |<- - -+ Header: (T=ACK, Code=0, MID=0x7d39) 3619 | | 3620 | | 3621 |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7c) 3622 | 2.05 | Token: 0x64 3623 | | Payload: "22.3 C" 3624 | | 3625 | | 3626 +- - ->| Header: (T=RST, Code=0, MID=0xad7c) 3627 | | 3629 Figure 16: Confirmable request; separate response (unexpected) 3631 Figure 17 shows a basic GET request where the request and the 3632 response are non-confirmable, so both may be lost without notice. 3634 Client Server 3635 | | 3636 | | 3637 +----->| Header: GET (T=NON, Code=1, MID=0x7d40) 3638 | GET | Token: 0x75 3639 | | Uri-Path: "temperature" 3640 | | 3641 | | 3642 |<-----+ Header: 2.05 Content (T=NON, Code=69, MID=0xad7d) 3643 | 2.05 | Token: 0x75 3644 | | Payload: "22.3 C" 3645 | | 3647 Figure 17: Non-confirmable request; Non-confirmable response 3649 In Figure 18, the client sends a Non-confirmable GET request to a 3650 multicast address: all nodes in link-local scope. There are 3 3651 servers on the link: A, B and C. Servers A and B have a matching 3652 resource, therefore they send back a Non-confirmable 2.05 (Content) 3653 response. The response sent by B is lost. C does not have matching 3654 response, therefore it sends a Non-confirmable 4.04 (Not Found) 3655 response. 3657 Client ff02::1 A B C 3658 | | | | | 3659 | | | | | 3660 +------>| | | | Header: GET (T=NON, Code=1, MID=0x7d41) 3661 | GET | | | | Token: 0x86 3662 | | | | Uri-Path: "temperature" 3663 | | | | 3664 | | | | 3665 |<------------+ | | Header: 2.05 (T=NON, Code=69, MID=0x60b1) 3666 | 2.05 | | | Token: 0x86 3667 | | | | Payload: "22.3 C" 3668 | | | | 3669 | | | | 3670 | X------------+ | Header: 2.05 (T=NON, Code=69, MID=0x01a0) 3671 | 2.05 | | | Token: 0x86 3672 | | | | Payload: "20.9 C" 3673 | | | | 3674 | | | | 3675 |<------------------+ Header: 4.04 (T=NON, Code=132, MID=0x952a) 3676 | 4.04 | | | Token: 0x86 3677 | | | | 3679 Figure 18: Non-confirmable request (multicast); Non-confirmable 3680 response 3682 Appendix C. URI Examples 3684 The following examples demonstrate different sets of Uri options, and 3685 the result after constructing an URI from them. 3687 o coap://[2001:db8::2:1]/ 3689 Destination IP Address = [2001:db8::2:1] 3691 Destination UDP Port = 5683 3693 o coap://example.net/ 3695 Destination IP Address = [2001:db8::2:1] 3697 Destination UDP Port = 5683 3699 Uri-Host = "example.net" 3701 o coap://example.net/.well-known/core 3702 Destination IP Address = [2001:db8::2:1] 3704 Destination UDP Port = 5683 3706 Uri-Host = "example.net" 3708 Uri-Path = ".well-known" 3710 Uri-Path = "core" 3712 o coap:// 3713 xn--18j4d.example/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF 3715 Destination IP Address = [2001:db8::2:1] 3717 Destination UDP Port = 5683 3719 Uri-Host = "xn--18j4d.example" 3721 Uri-Path = the string composed of the Unicode characters U+3053 3722 U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as 3723 E38193E38293E381ABE381A1E381AF hexadecimal 3725 o coap://198.51.100.1:61616//%2F//?%2F%2F&?%26 3727 Destination IP Address = 198.51.100.1 3729 Destination UDP Port = 61616 3731 Uri-Path = "" 3733 Uri-Path = "/" 3735 Uri-Path = "" 3737 Uri-Path = "" 3739 Uri-Query = "//" 3741 Uri-Query = "?&" 3743 Appendix D. Security Provisioning and Access Control 3745 This Annex contains further information about ways to perform 3746 provisioning and access control for CoAP Security. 3748 D.1. RawPublicKey Identity 3750 An identity for the device configured with this asymmetric key pair 3751 is calculated from the public key and is used for provisioning 3752 devices and performing access control. The identity is an (TBD)-bit 3753 one-way hash of the public key. This is calculated by performing a 3754 (TBD) hash over the raw public key. 3756 D.2. Provisioning 3758 The RawPublicKey mode was designed to be easily provisioned in M2M 3759 deployments. It is assumed that each device has an appropriate 3760 asymmetric public key pair installed, and the identity of that public 3761 key has been calculated as described in Appendix D.1. During 3762 provisioning, the identity of each node is collected, for example by 3763 reading a barcode on the outside of the device or by obtaining a pre- 3764 compiled list of the identities. These identities are then installed 3765 in the corresponding end-point, for example an M2M data collection 3766 server. The identity is used for two purposes, to associate the end- 3767 point with further device information and to perform access control. 3768 During provisioning, an access control list of identities the device 3769 may start DTLS sessions with SHOULD also be installed. 3771 D.3. Access Control 3773 D.3.1. PreSharedKey Mode 3775 In this mode in order to perform access control, identity needs to be 3776 assigned when installing or negotiating keys for the device. This 3777 identity may also be needed to choose the correct key to use in a 3778 DTLS session. The exact mechanism for provisioning keys, maintaining 3779 identities and using those for access control in PreSharedKey mode is 3780 out of scope for this specification. 3782 D.3.2. RawPublicKey Mode 3784 In this mode the identity of the public key for a device is used for 3785 access control. An end-point SHOULD keep a list of identities that 3786 it allows to access its resource, and MAY also support more detailed 3787 access control on the method or resource level. When a DTLS session 3788 is negotiated, a CoAP server that has an access control list MUST 3789 check the identity of the client. This is done by calculating the 3790 identity of the client's public key as described in Appendix D.1. A 3791 client SHOULD also verify the identity of the server if it has been 3792 configured with the appropriate access control list. 3794 D.3.3. Certificate Mode 3796 When in Certificate mode, access control is performed using the 3797 Authority Name from the certificate (e.g. the EUI-64 of the device). 3798 An end-point is provisioned with the list of Authority Names it can 3799 communicate with, and MAY also support more detailed access control 3800 on the method or resource level. When a DTLS session is negotiated, 3801 a CoAP server that has an access control list MUST check the 3802 Authority Name of the client's certificate. A client SHOULD also 3803 verify the identity of the server if it has been configured with the 3804 appropriate access control list. 3806 Appendix E. Changelog 3808 Changed from ietf-07 to ietf-08: 3810 o Clarified matching rules for messages (#175) 3812 o Fixed a bug in Section 8.2.2 on Etags (#168) 3814 o Added an IP address spoofing threat analysis contribution (#167) 3816 o Re-focused the security section on raw public keys (#166) 3818 o Added an 4.06 error to Accept (#165) 3820 Changed from ietf-06 to ietf-07: 3822 o application/link-format added to Media types registration (#160) 3824 o Moved content-type attribute to the document from link-format. 3826 o Added coaps scheme and DTLS-secured CoAP default port (#154) 3828 o Allowed 0-length Content-type options (#150) 3830 o Added congestion control recommendations (#153) 3832 o Improved text on PUT/POST response payloads (#149) 3834 o Added an Accept option for content-negotiation (#163) 3836 o Added If-Match and If-None-Match options (#155) 3838 o Improved Token Option explanation (#147) 3839 o Clarified mandatory to implement security (#156) 3841 o Added first come first server policy for 2-byte Media type codes 3842 (#161) 3844 o Clarify matching rules for messages and tokens (#151) 3846 o Changed OPTIONS and TRACE to always return 501 in HTTP-CoAP 3847 mapping (#164) 3849 Changed from ietf-05 to ietf-06: 3851 o HTTP mapping section improved with the minimal protocol standard 3852 text for CoAP-HTTP and HTTP-CoAP forward proxying (#137). 3854 o Eradicated percent-encoding by including one Uri-Query Option per 3855 &-delimited argument in a query. 3857 o Allowed RST message in reply to a NON message with unexpected 3858 token (#134). 3860 o Cache Invalidation only happens upon successful responses (#135). 3862 o 50% jitter added to the initial retransmit timer (#142). 3864 o DTLS cipher suites aligned with ZigBee IP, DTLS clarified as 3865 default CoAP security mechanism (#138, #139) 3867 o Added a minimal reference to draft-kivinen-ipsecme-ikev2-minimal 3868 (#140). 3870 o Clarified the comparison of UTF-8s (#136). 3872 o Minimized the initial media type registry (#101). 3874 Changed from ietf-04 to ietf-05: 3876 o Renamed Immediate into Piggy-backed and Deferred into Separate -- 3877 should finally end the confusion on what this is about. 3879 o GET requests now return a 2.05 (Content) response instead of 2.00 3880 (OK) response (#104). 3882 o Added text to allow 2.02 (Deleted) responses in reply to POST 3883 requests (#105). 3885 o Improved message deduplication rules (#106). 3887 o Section added on message size implementation considerations 3888 (#103). 3890 o Clarification made on human readable error payloads (#109). 3892 o Definition of CoAP methods improved (#108). 3894 o Max-Age removed from requests (#107). 3896 o Clarified uniqueness of tokens (#112). 3898 o Location-Query Option added (#113). 3900 o ETag length set to 1-8 bytes (#123). 3902 o Clarified relation between elective/critical and option numbers 3903 (#110). 3905 o Defined when to update Version header field (#111). 3907 o URI scheme registration improved (#102). 3909 o Added review guidelines for new CoAP codes and numbers. 3911 Changes from ietf-03 to ietf-04: 3913 o Major document reorganization (#51, #63, #71, #81). 3915 o Max-age length set to 0-4 bytes (#30). 3917 o Added variable unsigned integer definition (#31). 3919 o Clarification made on human readable error payloads (#50). 3921 o Definition of POST improved (#52). 3923 o Token length changed to 0-8 bytes (#53). 3925 o Section added on multiplexing CoAP, DTLS and STUN (#56). 3927 o Added cross-protocol attack considerations (#61). 3929 o Used new Immediate/Deferred response definitions (#73). 3931 o Improved request/response matching rules (#74). 3933 o Removed unnecessary media types and added recommendations for 3934 their use in M2M (#76). 3936 o Response codes changed to base 32 coding, new Y.XX naming (#77). 3938 o References updated as per AD review (#79). 3940 o IANA section completed (#80). 3942 o Proxy-Uri Option added to disambiguate between proxy and non-proxy 3943 requests (#82). 3945 o Added text on critical options in cached states (#83). 3947 o HTTP mapping sections improved (#88). 3949 o Added text on reverse proxies (#72). 3951 o Some security text on multicast added (#54). 3953 o Trust model text added to introduction (#58, #60). 3955 o AES-CCM vs. AES-CCB text added (#55). 3957 o Text added about device capabilities (#59). 3959 o DTLS section improvements (#87). 3961 o Caching semantics aligned with RFC2616 (#78). 3963 o Uri-Path Option split into multiple path segments. 3965 o MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2. 3967 Changes from ietf-02 to ietf-03: 3969 o Token Option and related use in asynchronous requests added (#25). 3971 o CoAP specific error codes added (#26). 3973 o Erroring out on unknown critical options changed to a MUST (#27). 3975 o Uri-Query Option added. 3977 o Terminology and definitions of URIs improved. 3979 o Security section completed (#22). 3981 Changes from ietf-01 to ietf-02: 3983 o Sending an error on a critical option clarified (#18). 3985 o Clarification on behavior of PUT and idempotent operations (#19). 3987 o Use of Uri-Authority clarified along with server processing rules; 3988 Uri-Scheme Option removed (#20, #23). 3990 o Resource discovery section removed to a separate CoRE Link Format 3991 draft (#21). 3993 o Initial security section outline added. 3995 Changes from ietf-00 to ietf-01: 3997 o New cleaner transaction message model and header (#5). 3999 o Removed subscription while being designed (#1). 4001 o Section 2 re-written (#3). 4003 o Text added about use of short URIs (#4). 4005 o Improved header option scheme (#5, #14). 4007 o Date option removed whiled being designed (#6). 4009 o New text for CoAP default port (#7). 4011 o Completed proxying section (#8). 4013 o Completed resource discovery section (#9). 4015 o Completed HTTP mapping section (#10). 4017 o Several new examples added (#11). 4019 o URI split into 3 options (#12). 4021 o MIME type defined for link-format (#13, #16). 4023 o New text on maximum message size (#15). 4025 o Location Option added. 4027 Changes from shelby-01 to ietf-00: 4029 o Removed the TCP binding section, left open for the future. 4031 o Fixed a bug in the example. 4033 o Marked current Sub/Notify as (Experimental) while under WG 4034 discussion. 4036 o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for 4037 CoAP-CoAP proxying to work). 4039 o Temporarily removed the Magic Byte header as TCP is no longer 4040 included as a binding. 4042 o Removed the Uri-code Option as different URI encoding schemes are 4043 being discussed. 4045 o Changed the rel= field to desc= for resource discovery. 4047 o Changed the maximum message size to 1024 bytes to allow for IP/UDP 4048 headers. 4050 o Made the URI slash optimization and method impotence MUSTs 4052 o Minor editing and bug fixing. 4054 Changes from shelby-00 to shelby-01: 4056 o Unified the message header and added a notify message type. 4058 o Renamed methods with HTTP names and removed the NOTIFY method. 4060 o Added a number of options field to the header. 4062 o Combines the Option Type and Length into an 8-bit field. 4064 o Added the magic byte header. 4066 o Added new ETag Option. 4068 o Added new Date Option. 4070 o Added new Subscription Option. 4072 o Completed the HTTP Code - CoAP Code mapping table appendix. 4074 o Completed the Content-type Identifier appendix and tables. 4076 o Added more simplifications for URI support. 4078 o Initial subscription and discovery sections. 4080 o A Flag requirements simplified. 4082 Authors' Addresses 4084 Zach Shelby 4085 Sensinode 4086 Kidekuja 2 4087 Vuokatti 88600 4088 Finland 4090 Phone: +358407796297 4091 Email: zach@sensinode.com 4093 Klaus Hartke 4094 Universitaet Bremen TZI 4095 Postfach 330440 4096 Bremen D-28359 4097 Germany 4099 Phone: +49-421-218-63905 4100 Fax: +49-421-218-7000 4101 Email: hartke@tzi.org 4103 Carsten Bormann 4104 Universitaet Bremen TZI 4105 Postfach 330440 4106 Bremen D-28359 4107 Germany 4109 Phone: +49-421-218-63921 4110 Fax: +49-421-218-7000 4111 Email: cabo@tzi.org 4113 Brian Frank 4114 SkyFoundry 4115 Richmond, VA 4116 USA 4118 Phone: 4119 Email: brian@skyfoundry.com