由于物联网中的很多设备都是资源受限型的，即只有少量的内存空间和有限的计算能力，所以传统的HTTP协议应用在物联网上就显得过于庞大而不适用。 IETF的CoRE工作组提出了一种基于REST架构的CoAP协议。CoAP是6LowPAN协议栈中的应用层协议。该文在详细介绍了CoAP协议的内容、特点和交互模型后，在uIPv6 START KIT无线网络开发套件上，使用Contiki嵌入式操作系统，不仅在浏览器端实现了CoAP协议而且用自己编写的客户端程序实现了CoAP协议，增加了和数据库之间的交互功能，从而实现了在Web界面上不仅可以查看实时数据，还可以查看历史数据的功能。
http://coap.technology/
https://tools.ietf.org/html/rfc7252
The Constrained Application Protocol (CoAP)
Abstract The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7252. Shelby, et al. Standards Track [Page 1]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 2. Constrained Application Protocol . . . . . . . . . . . . . . 10 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 11 2.2. Request/Response Model . . . . . . . . . . . . . . . . . 12 2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 15 2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . 15 3. Message Format . . . . . . . . . . . . . . . . . . . . . . . 15 3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 17 3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 19 4. Message Transmission . . . . . . . . . . . . . . . . . . . . 20 4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20 4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 21 4.3. Messages Transmitted without Reliability . . . . . . . . 23 4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 24 4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 24 4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 25 4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 26 4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 27 4.8.1. Changing the Parameters . . . . . . . . . . . . . . . 27 4.8.2. Time Values Derived from Transmission Parameters . . 28 5. Request/Response Semantics . . . . . . . . . . . . . . . . . 31 5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 31 5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 31 5.2.1. Piggybacked . . . . . . . . . . . . . . . . . . . . . 33 5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 33 5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 34 5.3. Request/Response Matching . . . . . . . . . . . . . . . . 34 5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 34 5.3.2. Request/Response Matching Rules . . . . . . . . . . . 35 Shelby, et al. Standards Track [Page 2]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 36 5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 37 5.4.2. Proxy Unsafe or Safe-to-Forward and NoCacheKey . . . 38 5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 38 5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 38 5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 39 5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 39 5.5. Payloads and Representations . . . . . . . . . . . . . . 40 5.5.1. Representation . . . . . . . . . . . . . . . . . . . 40 5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 41 5.5.3. Selected Representation . . . . . . . . . . . . . . . 41 5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 41 5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 42 5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 43 5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 43 5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 44 5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 44 5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 46 5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 46 5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 47 5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 47 5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 47 5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 48 5.9. Response Code Definitions . . . . . . . . . . . . . . . . 48 5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 48 5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 50 5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 51 5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 52 5.10.1. Uri-Host, Uri-Port, Uri-Path, and Uri-Query . . . . 53 5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 54 5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 55 5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 55 5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . 55 5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 56 5.10.7. Location-Path and Location-Query . . . . . . . . . . 57 5.10.8. Conditional Request Options . . . . . . . . . . . . 57 5.10.9. Size1 Option . . . . . . . . . . . . . . . . . . . . 59 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 59 6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 59 6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 60 6.3. Normalization and Comparison Rules . . . . . . . . . . . 61 6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 61 6.5. Composing URIs from Options . . . . . . . . . . . . . . . 62 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 64 7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 64 7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 64 7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 64 Shelby, et al. Standards Track [Page 3]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 65 8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 65 8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 66 8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 67 8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 67 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 68 9.1. DTLS-Secured CoAP . . . . . . . . . . . . . . . . . . . . 69 9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 70 9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 71 9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 71 10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 74 10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 75 10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 76 10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . 77 10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 77 10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 77 10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 77 10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . 78 10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . 78 10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 79 10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 79 10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . 79 10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 80 10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . 80 11. Security Considerations . . . . . . . . . . . . . . . . . . . 80 11.1. Parsing the Protocol and Processing URIs . . . . . . . . 80 11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 81 11.3. Risk of Amplification . . . . . . . . . . . . . . . . . 81 11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . 83 11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 84 11.6. Constrained-Node Considerations . . . . . . . . . . . . 86 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 86 12.1. CoAP Code Registries . . . . . . . . . . . . . . . . . . 86 12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 87 12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 88 12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 89 12.3. CoAP Content-Formats Registry . . . . . . . . . . . . . 91 12.4. URI Scheme Registration . . . . . . . . . . . . . . . . 93 12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 94 12.6. Service Name and Port Number Registration . . . . . . . 95 12.7. Secure Service Name and Port Number Registration . . . . 96 12.8. Multicast Address Registration . . . . . . . . . . . . . 97 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 97 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 98 14.1. Normative References . . . . . . . . . . . . . . . . . . 98 14.2. Informative References . . . . . . . . . . . . . . . . . 100 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 104 Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 110 Shelby, et al. Standards Track [Page 4]
RFC 7252 The Constrained Application Protocol (CoAP) June 20141. Introduction
The use of web services (web APIs) on the Internet has become ubiquitous in most applications and depends on the fundamental Representational State Transfer [REST] architecture of the Web. The work on Constrained RESTful Environments (CoRE) aims at realizing the REST architecture in a suitable form for the most constrained nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and networks (e.g., 6LoWPAN, [RFC4944]). Constrained networks such as 6LoWPAN support the fragmentation of IPv6 packets into small link- layer frames; however, this causes significant reduction in packet delivery probability. One design goal of CoAP has been to keep message overhead small, thus limiting the need for fragmentation. One of the main goals of CoAP is to design a generic web protocol for the special requirements of this constrained environment, especially considering energy, building automation, and other machine-to-machine (M2M) applications. The goal of CoAP is not to blindly compress HTTP [RFC2616], but rather to realize a subset of REST common with HTTP but optimized for M2M applications. Although CoAP could be used for refashioning simple HTTP interfaces into a more compact protocol, more importantly it also offers features for M2M such as built-in discovery, multicast support, and asynchronous message exchanges. This document specifies the Constrained Application Protocol (CoAP), which easily translates to HTTP for integration with the existing Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments and M2M applications.1.1. Features
CoAP has the following main features: o Web protocol fulfilling M2M requirements in constrained environments o UDP [RFC0768] binding with optional reliability supporting unicast and multicast requests. o Asynchronous message exchanges. o Low header overhead and parsing complexity. o URI and Content-type support. o Simple proxy and caching capabilities. Shelby, et al. Standards Track [Page 5]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 o A stateless HTTP mapping, allowing proxies to be built providing access to CoAP resources via HTTP in a uniform way or for HTTP simple interfaces to be realized alternatively over CoAP. o Security binding to Datagram Transport Layer Security (DTLS) [RFC6347].1.2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] when they appear in ALL CAPS. These words may also appear in this document in lowercase, absent their normative meanings. This specification requires readers to be familiar with all the terms and concepts that are discussed in [RFC2616], including "resource", "representation", "cache", and "fresh". (Having been completed before the updated set of HTTP RFCs, RFC 7230 to RFC 7235, became available, this specification specifically references the predecessor version -- RFC 2616.) In addition, this specification defines the following terminology: Endpoint An entity participating in the CoAP protocol. Colloquially, an endpoint lives on a "Node", although "Host" would be more consistent with Internet standards usage, and is further identified by transport-layer multiplexing information that can include a UDP port number and a security association (Section 4.1). Sender The originating endpoint of a message. When the aspect of identification of the specific sender is in focus, also "source endpoint". Recipient The destination endpoint of a message. When the aspect of identification of the specific recipient is in focus, also "destination endpoint". Client The originating endpoint of a request; the destination endpoint of a response. Server The destination endpoint of a request; the originating endpoint of a response. Shelby, et al. Standards Track [Page 6]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Origin Server The server on which a given resource resides or is to be created. Intermediary A CoAP endpoint that acts both as a server and as a client towards an origin server (possibly via further intermediaries). A common form of an intermediary is a proxy; several classes of such proxies are discussed in this specification. Proxy An intermediary that mainly is concerned with forwarding requests and relaying back responses, possibly performing caching, namespace translation, or protocol translation in the process. As opposed to intermediaries in the general sense, proxies generally do not implement specific application semantics. Based on the position in the overall structure of the request forwarding, there are two common forms of proxy: forward-proxy and reverse-proxy. In some cases, a single endpoint might act as an origin server, forward-proxy, or reverse-proxy, switching behavior based on the nature of each request. Forward-Proxy An endpoint selected by a client, usually via local configuration rules, to perform requests on behalf of the client, doing any necessary translations. Some translations are minimal, such as for proxy requests for "coap" URIs, whereas other requests might require translation to and from entirely different application- layer protocols. Reverse-Proxy An endpoint that stands in for one or more other server(s) and satisfies requests on behalf of these, doing any necessary translations. Unlike a forward-proxy, the client may not be aware that it is communicating with a reverse-proxy; a reverse-proxy receives requests as if it were the origin server for the target resource. CoAP-to-CoAP Proxy A proxy that maps from a CoAP request to a CoAP request, i.e., uses the CoAP protocol both on the server and the client side. Contrast to cross-proxy. Cross-Proxy A cross-protocol proxy, or "cross-proxy" for short, is a proxy that translates between different protocols, such as a CoAP-to- HTTP proxy or an HTTP-to-CoAP proxy. While this specification makes very specific demands of CoAP-to-CoAP proxies, there is more variation possible in cross-proxies.
Confirmable Message
Some messages require an acknowledgement. These messages are
called "Confirmable". When no packets are lost, each Confirmable
message elicits exactly one return message of type Acknowledgement
or type Reset.
Non-confirmable Message
Some other messages do not require an acknowledgement. This is
particularly true for messages that are repeated regularly for
application requirements, such as repeated readings from a sensor.
Acknowledgement Message
An Acknowledgement message acknowledges that a specific
Confirmable message arrived. By itself, an Acknowledgement
message does not indicate success or failure of any request
encapsulated in the Confirmable message, but the Acknowledgement
message may also carry a Piggybacked Response (see below).
Reset Message
A Reset message indicates that a specific message (Confirmable or
Non-confirmable) was received, but some context is missing to
properly process it. This condition is usually caused when the
receiving node has rebooted and has forgotten some state that
would be required to interpret the message. Provoking a Reset
message (e.g., by sending an Empty Confirmable message) is also
useful as an inexpensive check of the liveness of an endpoint
("CoAP ping").
Piggybacked Response
A piggybacked Response is included right in a CoAP Acknowledgement
(ACK) message that is sent to acknowledge receipt of the Request
for this Response (Section 5.2.1).
Separate Response
When a Confirmable message carrying a request is acknowledged with
an Empty message (e.g., because the server doesn't have the answer
right away), a Separate Response is sent in a separate message
exchange (Section 5.2.2).
Empty Message
A message with a Code of 0.00; neither a request nor a response.
An Empty message only contains the 4-byte header.
Shelby, et al. Standards Track [Page 8]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Critical Option An option that would need to be understood by the endpoint ultimately receiving the message in order to properly process the message (Section 5.4.1). Note that the implementation of critical options is, as the name "Option" implies, generally optional: unsupported critical options lead to an error response or summary rejection of the message. Elective Option An option that is intended to be ignored by an endpoint that does not understand it. Processing the message even without understanding the option is acceptable (Section 5.4.1). Unsafe Option An option that would need to be understood by a proxy receiving the message in order to safely forward the message (Section 5.4.2). Not every critical option is an unsafe option. Safe-to-Forward Option An option that is intended to be safe for forwarding by a proxy that does not understand it. Forwarding the message even without understanding the option is acceptable (Section 5.4.2). Resource Discovery The process where a CoAP client queries a server for its list of hosted resources (i.e., links as defined in Section 7). Content-Format The combination of an Internet media type, potentially with specific parameters given, and a content-coding (which is often the identity content-coding), identified by a numeric identifier defined by the "CoAP Content-Formats" registry. When the focus is less on the numeric identifier than on the combination of these characteristics of a resource representation, this is also called "representation format". Additional terminology for constrained nodes and constrained-node networks can be found in [RFC7228]. In this specification, the term "byte" is used in its now customary sense as a synonym for "octet". All multi-byte integers in this protocol are interpreted in network byte order. Where arithmetic is used, this specification uses the notation familiar from the programming language C, except that the operator "**" stands for exponentiation. Shelby, et al. Standards Track [Page 9]
RFC 7252 The Constrained Application Protocol (CoAP) June 20142. Constrained Application Protocol
The interaction model of CoAP is similar to the client/server model of HTTP. However, machine-to-machine interactions typically result in a CoAP implementation acting in both client and server roles. A CoAP request is equivalent to that of HTTP and is sent by a client to request an action (using a Method Code) on a resource (identified by a URI) on a server. The server then sends a response with a Response Code; this response may include a resource representation. Unlike HTTP, CoAP deals with these interchanges asynchronously over a datagram-oriented transport such as UDP. This is done logically using a layer of messages that supports optional reliability (with exponential back-off). CoAP defines four types of messages: Confirmable, Non-confirmable, Acknowledgement, Reset. Method Codes and Response Codes included in some of these messages make them carry requests or responses. The basic exchanges of the four types of messages are somewhat orthogonal to the request/response interactions; requests can be carried in Confirmable and Non- confirmable messages, and responses can be carried in these as well as piggybacked in Acknowledgement messages. One could think of CoAP logically as using a two-layer approach, a CoAP messaging layer used to deal with UDP and the asynchronous nature of the interactions, and the request/response interactions using Method and Response Codes (see Figure 1). CoAP is however a single protocol, with messaging and request/response as just features of the CoAP header. +----------------------+ | Application | +----------------------+ +----------------------+ \ | Requests/Responses | | |----------------------| | CoAP | Messages | | +----------------------+ / +----------------------+ | UDP | +----------------------+ Figure 1: Abstract Layering of CoAP Shelby, et al. Standards Track [Page 10]
RFC 7252 The Constrained Application Protocol (CoAP) June 20142.1. Messaging Model
The CoAP messaging model is based on the exchange of messages over UDP between endpoints. CoAP uses a short fixed-length binary header (4 bytes) that may be followed by compact binary options and a payload. This message format is shared by requests and responses. The CoAP message format is specified in Section 3. Each message contains a Message ID used to detect duplicates and for optional reliability. (The Message ID is compact; its 16-bit size enables up to about 250 messages per second from one endpoint to another with default protocol parameters.) Reliability is provided by marking a message as Confirmable (CON). A Confirmable message is retransmitted using a default timeout and exponential back-off between retransmissions, until the recipient sends an Acknowledgement message (ACK) with the same Message ID (in this example, 0x7d34) from the corresponding endpoint; see Figure 2. When a recipient is not at all able to process a Confirmable message (i.e., not even able to provide a suitable error response), it replies with a Reset message (RST) instead of an Acknowledgement (ACK). Client Server | | | CON [0x7d34] | +----------------->| | | | ACK [0x7d34] | |<-----------------+ | | Figure 2: Reliable Message Transmission A message that does not require reliable transmission (for example, each single measurement out of a stream of sensor data) can be sent as a Non-confirmable message (NON). These are not acknowledged, but still have a Message ID for duplicate detection (in this example, 0x01a0); see Figure 3. When a recipient is not able to process a Non-confirmable message, it may reply with a Reset message (RST). Shelby, et al. Standards Track [Page 11]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Client Server | | | NON [0x01a0] | +----------------->| | | Figure 3: Unreliable Message Transmission See Section 4 for details of CoAP messages. As CoAP runs over UDP, it also supports the use of multicast IP destination addresses, enabling multicast CoAP requests. Section 8 discusses the proper use of CoAP messages with multicast addresses and precautions for avoiding response congestion. Several security modes are defined for CoAP in Section 9 ranging from no security to certificate-based security. This document specifies a binding to DTLS for securing the protocol; the use of IPsec with CoAP is discussed in [IPsec-CoAP].2.2. Request/Response Model
CoAP request and response semantics are carried in CoAP messages, which include either a Method Code or Response Code, respectively. Optional (or default) request and response information, such as the URI and payload media type are carried as CoAP options. A Token is used to match responses to requests independently from the underlying messages (Section 5.3). (Note that the Token is a concept separate from the Message ID.) A request is carried in a Confirmable (CON) or Non-confirmable (NON) message, and, if immediately available, the response to a request carried in a Confirmable message is carried in the resulting Acknowledgement (ACK) message. This is called a piggybacked response, detailed in Section 5.2.1. (There is no need for separately acknowledging a piggybacked response, as the client will retransmit the request if the Acknowledgement message carrying the piggybacked response is lost.) Two examples for a basic GET request with piggybacked response are shown in Figure 4, one successful, one resulting in a 4.04 (Not Found) response. Shelby, et al. Standards Track [Page 12]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Client Server Client Server | | | | | CON [0xbc90] | | CON [0xbc91] | | GET /temperature | | GET /temperature | | (Token 0x71) | | (Token 0x72) | +----------------->| +----------------->| | | | | | ACK [0xbc90] | | ACK [0xbc91] | | 2.05 Content | | 4.04 Not Found | | (Token 0x71) | | (Token 0x72) | | "22.5 C" | | "Not found" | |<-----------------+ |<-----------------+ | | | | Figure 4: Two GET Requests with Piggybacked Responses If the server is not able to respond immediately to a request carried in a Confirmable message, it simply responds with an Empty Acknowledgement message so that the client can stop retransmitting the request. When the response is ready, the server sends it in a new Confirmable message (which then in turn needs to be acknowledged by the client). This is called a "separate response", as illustrated in Figure 5 and described in more detail in Section 5.2.2. Client Server | | | CON [0x7a10] | | GET /temperature | | (Token 0x73) | +----------------->| | | | ACK [0x7a10] | |<-----------------+ | | ... Time Passes ... | | | CON [0x23bb] | | 2.05 Content | | (Token 0x73) | | "22.5 C" | |<-----------------+ | | | ACK [0x23bb] | +----------------->| | | Figure 5: A GET Request with a Separate Response Shelby, et al. Standards Track [Page 13]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 If a request is sent in a Non-confirmable message, then the response is sent using a new Non-confirmable message, although the server may instead send a Confirmable message. This type of exchange is illustrated in Figure 6. Client Server | | | NON [0x7a11] | | GET /temperature | | (Token 0x74) | +----------------->| | | | NON [0x23bc] | | 2.05 Content | | (Token 0x74) | | "22.5 C" | |<-----------------+ | | Figure 6: A Request and a Response Carried in Non-confirmable Messages CoAP makes use of GET, PUT, POST, and DELETE methods in a similar manner to HTTP, with the semantics specified in Section 5.8. (Note that the detailed semantics of CoAP methods are "almost, but not entirely unlike" [HHGTTG] those of HTTP methods: intuition taken from HTTP experience generally does apply well, but there are enough differences that make it worthwhile to actually read the present specification.) Methods beyond the basic four can be added to CoAP in separate specifications. New methods do not necessarily have to use requests and responses in pairs. Even for existing methods, a single request may yield multiple responses, e.g., for a multicast request (Section 8) or with the Observe option [OBSERVE]. URI support in a server is simplified as the client already parses the URI and splits it into host, port, path, and query components, making use of default values for efficiency. Response Codes relate to a small subset of HTTP status codes with a few CoAP-specific codes added, as defined in Section 5.9. Shelby, et al. Standards Track [Page 14]
RFC 7252 The Constrained Application Protocol (CoAP) June 20142.3. Intermediaries and Caching
The protocol supports the caching of responses in order to efficiently fulfill requests. Simple caching is enabled using freshness and validity information carried with CoAP responses. A cache could be located in an endpoint or an intermediary. Caching functionality is specified in Section 5.6. Proxying is useful in constrained networks for several reasons, including to limit network traffic, to improve performance, to access resources of sleeping devices, and for security reasons. The proxying of requests on behalf of another CoAP endpoint is supported in the protocol. When using a proxy, the URI of the resource to request is included in the request, while the destination IP address is set to the address of the proxy. See Section 5.7 for more information on proxy functionality. As CoAP was designed according to the REST architecture [REST], and thus exhibits functionality similar to that of the HTTP protocol, it is quite straightforward to map from CoAP to HTTP and from HTTP to CoAP. Such a mapping may be used to realize an HTTP REST interface using CoAP or to convert between HTTP and CoAP. This conversion can be carried out by a cross-protocol proxy ("cross-proxy"), which converts the Method or Response Code, media type, and options to the corresponding HTTP feature. Section 10 provides more detail about HTTP mapping.2.4. Resource Discovery
Resource discovery is important for machine-to-machine interactions and is supported using the CoRE Link Format [RFC6690] as discussed in Section 7.3. Message Format
CoAP is based on the exchange of compact messages that, by default, are transported over UDP (i.e., each CoAP message occupies the data section of one UDP datagram). CoAP may also be used over Datagram Transport Layer Security (DTLS) (see Section 9.1). It could also be used over other transports such as SMS, TCP, or SCTP, the specification of which is out of this document's scope. (UDP-lite [RFC3828] and UDP zero checksum [RFC6936] are not supported by CoAP.) CoAP messages are encoded in a simple binary format. The message format starts with a fixed-size 4-byte header. This is followed by a variable-length Token value, which can be between 0 and 8 bytes long. Shelby, et al. Standards Track [Page 15]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Following the Token value comes a sequence of zero or more CoAP Options in Type-Length-Value (TLV) format, optionally followed by a payload that takes up the rest of the datagram. 0 1 2 3 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Ver| T | TKL | Code | Message ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Token (if any, TKL bytes) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 7: Message Format The fields in the header are defined as follows: Version (Ver): 2-bit unsigned integer. Indicates the CoAP version number. Implementations of this specification MUST set this field to 1 (01 binary). Other values are reserved for future versions. Messages with unknown version numbers MUST be silently ignored. Type (T): 2-bit unsigned integer. Indicates if this message is of type Confirmable (0), Non-confirmable (1), Acknowledgement (2), or Reset (3). The semantics of these message types are defined in Section 4. Token Length (TKL): 4-bit unsigned integer. Indicates the length of the variable-length Token field (0-8 bytes). Lengths 9-15 are reserved, MUST NOT be sent, and MUST be processed as a message format error. Code: 8-bit unsigned integer, split into a 3-bit class (most significant bits) and a 5-bit detail (least significant bits), documented as "c.dd" where "c" is a digit from 0 to 7 for the 3-bit subfield and "dd" are two digits from 00 to 31 for the 5-bit subfield. The class can indicate a request (0), a success response (2), a client error response (4), or a server error response (5). (All other class values are reserved.) As a special case, Code 0.00 indicates an Empty message. In case of a request, the Code field indicates the Request Method; in case of a response, a Response Code. Possible values are maintained in the CoAP Code Registries (Section 12.1). The semantics of requests and responses are defined in Section 5. Shelby, et al. Standards Track [Page 16]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Message ID: 16-bit unsigned integer in network byte order. Used to detect message duplication and to match messages of type Acknowledgement/Reset to messages of type Confirmable/Non- confirmable. The rules for generating a Message ID and matching messages are defined in Section 4. The header is followed by the Token value, which may be 0 to 8 bytes, as given by the Token Length field. The Token value is used to correlate requests and responses. The rules for generating a Token and correlating requests and responses are defined in Section 5.3.1. Header and Token are followed by zero or more Options (Section 3.1). An Option can be followed by the end of the message, by another Option, or by the Payload Marker and the payload. Following the header, token, and options, if any, comes the optional payload. If present and of non-zero length, it is prefixed by a fixed, one-byte Payload Marker (0xFF), which indicates the end of options and the start of the payload. The payload data extends from after the marker to the end of the UDP datagram, i.e., the Payload Length is calculated from the datagram size. The absence of the Payload Marker denotes a zero-length payload. The presence of a marker followed by a zero-length payload MUST be processed as a message format error. Implementation Note: The byte value 0xFF may also occur within an option length or value, so simple byte-wise scanning for 0xFF is not a viable technique for finding the payload marker. The byte 0xFF has the meaning of a payload marker only where the beginning of another option could occur.3.1. Option Format
CoAP defines a number of options that can be included in a message. Each option instance in a message specifies the Option Number of the defined CoAP option, the length of the Option Value, and the Option Value itself. Instead of specifying the Option Number directly, the instances MUST appear in order of their Option Numbers and a delta encoding is used between them: the Option Number for each instance is calculated as the sum of its delta and the Option Number of the preceding instance in the message. For the first instance in a message, a preceding option instance with Option Number zero is assumed. Multiple instances of the same option can be included by using a delta of zero. Shelby, et al. Standards Track [Page 17]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Option Numbers are maintained in the "CoAP Option Numbers" registry (Section 12.2). See Section 5.4 for the semantics of the options defined in this document. 0 1 2 3 4 5 6 7 +---------------+---------------+ | | | | Option Delta | Option Length | 1 byte | | | +---------------+---------------+ \ \ / Option Delta / 0-2 bytes \ (extended) \ +-------------------------------+ \ \ / Option Length / 0-2 bytes \ (extended) \ +-------------------------------+ \ \ / / \ \ / Option Value / 0 or more bytes \ \ / / \ \ +-------------------------------+ Figure 8: Option Format The fields in an option are defined as follows:
Option Delta: 4-bit unsigned integer. A value between 0 and 12
indicates the Option Delta. Three values are reserved for special
constructs:
13: An 8-bit unsigned integer follows the initial byte and
indicates the Option Delta minus 13.
14: A 16-bit unsigned integer in network byte order follows the
initial byte and indicates the Option Delta minus 269.
15: Reserved for the Payload Marker. If the field is set to this
value but the entire byte is not the payload marker, this MUST
be processed as a message format error.
Shelby, et al. Standards Track [Page 18]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 The resulting Option Delta is used as the difference between the Option Number of this option and that of the previous option (or zero for the first option). In other words, the Option Number is calculated by simply summing the Option Delta values of this and all previous options before it. Option Length: 4-bit unsigned integer. A value between 0 and 12 indicates the length of the Option Value, in bytes. Three values are reserved for special constructs: 13: An 8-bit unsigned integer precedes the Option Value and indicates the Option Length minus 13. 14: A 16-bit unsigned integer in network byte order precedes the Option Value and indicates the Option Length minus 269. 15: Reserved for future use. If the field is set to this value, it MUST be processed as a message format error. Value: A sequence of exactly Option Length bytes. The length and format of the Option Value depend on the respective option, which MAY define variable-length values. See Section 3.2 for the formats used in this document; options defined in other documents MAY make use of other option value formats.3.2. Option Value Formats
The options defined in this document make use of the following option value formats. empty: A zero-length sequence of bytes. opaque: An opaque sequence of bytes. uint: A non-negative integer that is represented in network byte order using the number of bytes given by the Option Length field. An option definition may specify a range of permissible numbers of bytes; if it has a choice, a sender SHOULD represent the integer with as few bytes as possible, i.e., without leading zero bytes. For example, the number 0 is represented with an empty option value (a zero-length sequence of bytes) and the number 1 by a single byte with the numerical value of 1 (bit combination 00000001 in most significant bit first notation). A recipient MUST be prepared to process values with leading zero bytes. Shelby, et al. Standards Track [Page 19]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Implementation Note: The exceptional behavior permitted for the sender is intended for highly constrained, templated implementations (e.g., hardware implementations) that use fixed-size options in the templates. string: A Unicode string that is encoded using UTF-8 [RFC3629] in Net-Unicode form [RFC5198]. Note that here, and in all other places where UTF-8 encoding is used in the CoAP protocol, the intention is that the encoded strings can be directly used and compared as opaque byte strings by CoAP protocol implementations. There is no expectation and no need to perform normalization within a CoAP implementation (except where Unicode strings that are not known to be normalized are imported from sources outside the CoAP protocol). Note also that ASCII strings (that do not make use of special control characters) are always valid UTF-8 Net-Unicode strings.4. Message Transmission
CoAP messages are exchanged asynchronously between CoAP endpoints. They are used to transport CoAP requests and responses, the semantics of which are defined in Section 5. As CoAP is bound to unreliable transports such as UDP, CoAP messages may arrive out of order, appear duplicated, or go missing without notice. For this reason, CoAP implements a lightweight reliability mechanism, without trying to re-create the full feature set of a transport like TCP. It has the following features: o Simple stop-and-wait retransmission reliability with exponential back-off for Confirmable messages. o Duplicate detection for both Confirmable and Non-confirmable messages.4.1. Messages and Endpoints
A CoAP endpoint is the source or destination of a CoAP message. The specific definition of an endpoint depends on the transport being used for CoAP. For the transports defined in this specification, the endpoint is identified depending on the security mode used (see Section 9): With no security, the endpoint is solely identified by an IP address and a UDP port number. With other security modes, the endpoint is identified as defined by the security mode. Shelby, et al. Standards Track [Page 20]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 There are different types of messages. The type of a message is specified by the Type field of the CoAP Header. Separate from the message type, a message may carry a request, a response, or be Empty. This is signaled by the Request/Response Code field in the CoAP Header and is relevant to the request/response model. Possible values for the field are maintained in the CoAP Code Registries (Section 12.1). An Empty message has the Code field set to 0.00. The Token Length field MUST be set to 0 and bytes of data MUST NOT be present after the Message ID field. If there are any bytes, they MUST be processed as a message format error.4.2. Messages Transmitted Reliably
The reliable transmission of a message is initiated by marking the message as Confirmable in the CoAP header. A Confirmable message always carries either a request or response, unless it is used only to elicit a Reset message, in which case it is Empty. A recipient MUST either (a) acknowledge a Confirmable message with an Acknowledgement message or (b) reject the message if the recipient lacks context to process the message properly, including situations where the message is Empty, uses a code with a reserved class (1, 6, or 7), or has a message format error. Rejecting a Confirmable message is effected by sending a matching Reset message and otherwise ignoring it. The Acknowledgement message MUST echo the Message ID of the Confirmable message and MUST carry a response or be Empty (see Sections 5.2.1 and 5.2.2). The Reset message MUST echo the Message ID of the Confirmable message and MUST be Empty. Rejecting an Acknowledgement or Reset message (including the case where the Acknowledgement carries a request or a code with a reserved class, or the Reset message is not Empty) is effected by silently ignoring it. More generally, recipients of Acknowledgement and Reset messages MUST NOT respond with either Acknowledgement or Reset messages. The sender retransmits the Confirmable message at exponentially increasing intervals, until it receives an acknowledgement (or Reset message) or runs out of attempts. Retransmission is controlled by two things that a CoAP endpoint MUST keep track of for each Confirmable message it sends while waiting for an acknowledgement (or reset): a timeout and a retransmission counter. For a new Confirmable message, the initial timeout is set to a random duration (often not an integral number of seconds) between ACK_TIMEOUT and (ACK_TIMEOUT * ACK_RANDOM_FACTOR) (see Section 4.8), and the retransmission counter is set to 0. When the timeout is triggered and the retransmission counter is less than Shelby, et al. Standards Track [Page 21]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 MAX_RETRANSMIT, the message is retransmitted, the retransmission counter is incremented, and the timeout is doubled. If the retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the endpoint receives a Reset message, then the attempt to transmit the message is canceled and the application process informed of failure. On the other hand, if the endpoint receives an acknowledgement in time, transmission is considered successful. This specification makes no strong requirements on the accuracy of the clocks used to implement the above binary exponential back-off algorithm. In particular, an endpoint may be late for a specific retransmission due to its sleep schedule and may catch up on the next one. However, the minimum spacing before another retransmission is ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST stay in the envelope of MAX_TRANSMIT_SPAN (see Section 4.8.2), even if that means a sender may miss an opportunity to transmit. A CoAP endpoint that sent a Confirmable message MAY give up in attempting to obtain an ACK even before the MAX_RETRANSMIT counter value is reached. For example, the application has canceled the request as it no longer needs a response, or there is some other indication that the CON message did arrive. In particular, a CoAP request message may have elicited a separate response, in which case it is clear to the requester that only the ACK was lost and a retransmission of the request would serve no purpose. However, a responder MUST NOT in turn rely on this cross-layer behavior from a requester, i.e., it MUST retain the state to create the ACK for the request, if needed, even if a Confirmable response was already acknowledged by the requester. Another reason for giving up retransmission MAY be the receipt of ICMP errors. If it is desired to take account of ICMP errors, to mitigate potential spoofing attacks, implementations SHOULD take care to check the information about the original datagram in the ICMP message, including port numbers and CoAP header information such as message type and code, Message ID, and Token; if this is not possible due to limitations of the UDP service API, ICMP errors SHOULD be ignored. Packet Too Big errors [RFC4443] ("fragmentation needed and DF set" for IPv4 [RFC0792]) cannot properly occur and SHOULD be ignored if the implementation note in Section 4.6 is followed; otherwise, they SHOULD feed into a path MTU discovery algorithm [RFC4821]. Source Quench and Time Exceeded ICMP messages SHOULD be ignored. Host, network, port, or protocol unreachable errors or parameter problem errors MAY, after appropriate vetting, be used to inform the application of a failure in sending. Shelby, et al. Standards Track [Page 22]
RFC 7252 The Constrained Application Protocol (CoAP) June 20144.3. Messages Transmitted without Reliability
Some messages do not require an acknowledgement. This is particularly true for messages that are repeated regularly for application requirements, such as repeated readings from a sensor where eventual success is sufficient. As a more lightweight alternative, a message can be transmitted less reliably by marking the message as Non-confirmable. A Non- confirmable message always carries either a request or response and MUST NOT be Empty. A Non-confirmable message MUST NOT be acknowledged by the recipient. A recipient MUST reject the message if it lacks context to process the message properly, including the case where the message is Empty, uses a code with a reserved class (1, 6, or 7), or has a message format error. Rejecting a Non- confirmable message MAY involve sending a matching Reset message, and apart from the Reset message the rejected message MUST be silently ignored. At the CoAP level, there is no way for the sender to detect if a Non- confirmable message was received or not. A sender MAY choose to transmit multiple copies of a Non-confirmable message within MAX_TRANSMIT_SPAN (limited by the provisions of Section 4.7, in particular, by PROBING_RATE if no response is received), or the network may duplicate the message in transit. To enable the receiver to act only once on the message, Non-confirmable messages specify a Message ID as well. (This Message ID is drawn from the same number space as the Message IDs for Confirmable messages.) Summarizing Sections 4.2 and 4.3, the four message types can be used as in Table 1. "*" means that the combination is not used in normal operation but only to elicit a Reset message ("CoAP ping"). +----------+-----+-----+-----+-----+ | | CON | NON | ACK | RST | +----------+-----+-----+-----+-----+ | Request | X | X | - | - | | Response | X | X | X | - | | Empty | * | - | X | X | +----------+-----+-----+-----+-----+ Table 1: Usage of Message Types Shelby, et al. Standards Track [Page 23]
RFC 7252 The Constrained Application Protocol (CoAP) June 20144.4. Message Correlation
An Acknowledgement or Reset message is related to a Confirmable message or Non-confirmable message by means of a Message ID along with additional address information of the corresponding endpoint. The Message ID is a 16-bit unsigned integer that is generated by the sender of a Confirmable or Non-confirmable message and included in the CoAP header. The Message ID MUST be echoed in the Acknowledgement or Reset message by the recipient. The same Message ID MUST NOT be reused (in communicating with the same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2). Implementation Note: Several implementation strategies can be employed for generating Message IDs. In the simplest case, a CoAP endpoint generates Message IDs by keeping a single Message ID variable, which is changed each time a new Confirmable or Non- confirmable message is sent, regardless of the destination address or port. Endpoints dealing with large numbers of transactions could keep multiple Message ID variables, for example, per prefix or destination address. (Note that some receiving endpoints may not be able to distinguish unicast and multicast packets addressed to it, so endpoints generating Message IDs need to make sure these do not overlap.) It is strongly recommended that the initial value of the variable (e.g., on startup) be randomized, in order to make successful off-path attacks on the protocol less likely. For an Acknowledgement or Reset message to match a Confirmable or Non-confirmable message, the Message ID and source endpoint of the Acknowledgement or Reset message MUST match the Message ID and destination endpoint of the Confirmable or Non-confirmable message.4.5. Message Deduplication
A recipient might receive the same Confirmable message (as indicated by the Message ID and source endpoint) multiple times within the EXCHANGE_LIFETIME (Section 4.8.2), for example, when its Acknowledgement went missing or didn't reach the original sender before the first timeout. The recipient SHOULD acknowledge each duplicate copy of a Confirmable message using the same Acknowledgement or Reset message but SHOULD process any request or response in the message only once. This rule MAY be relaxed in case the Confirmable message transports a request that is idempotent (see Section 5.1) or can be handled in an idempotent fashion. Examples for relaxed message deduplication: Shelby, et al. Standards Track [Page 24]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 o A server might relax the requirement to answer all retransmissions of an idempotent request with the same response (Section 4.2), so that it does not have to maintain state for Message IDs. For example, an implementation might want to process duplicate transmissions of a GET, PUT, or DELETE request as separate requests if the effort incurred by duplicate processing is less expensive than keeping track of previous responses would be. o A constrained server might even want to relax this requirement for certain non-idempotent requests if the application semantics make this trade-off favorable. For example, if the result of a POST request is just the creation of some short-lived state at the server, it may be less expensive to incur this effort multiple times for a request than keeping track of whether a previous transmission of the same request already was processed. A recipient might receive the same Non-confirmable message (as indicated by the Message ID and source endpoint) multiple times within NON_LIFETIME (Section 4.8.2). As a general rule that MAY be relaxed based on the specific semantics of a message, the recipient SHOULD silently ignore any duplicated Non-confirmable message and SHOULD process any request or response in the message only once.4.6. Message Size
While specific link layers make it beneficial to keep CoAP messages small enough to fit into their link-layer packets (see Section 1), this is a matter of implementation quality. The CoAP specification itself provides only an upper bound to the message size. Messages larger than an IP packet result in undesirable packet fragmentation. A CoAP message, appropriately encapsulated, SHOULD fit within a single IP packet (i.e., avoid IP fragmentation) and (by fitting into one UDP payload) obviously needs to fit within a single IP datagram. If the Path MTU is not known for a destination, an IP MTU of 1280 bytes SHOULD be assumed; if nothing is known about the size of the headers, good upper bounds are 1152 bytes for the message size and 1024 bytes for the payload size. Implementation Note: CoAP's choice of message size parameters works well with IPv6 and with most of today's IPv4 paths. (However, with IPv4, it is harder to absolutely ensure that there is no IP fragmentation. If IPv4 support on unusual networks is a consideration, implementations may want to limit themselves to more conservative IPv4 datagram sizes such as 576 bytes; per [RFC0791], the absolute minimum value of the IP MTU for IPv4 is as low as 68 bytes, which would leave only 40 bytes minus security overhead for a UDP payload. Implementations extremely focused on this problem set might also set the IPv4 DF bit and perform some Shelby, et al. Standards Track [Page 25]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 form of path MTU discovery [RFC4821]; this should generally be unnecessary in realistic use cases for CoAP, however.) A more important kind of fragmentation in many constrained networks is that on the adaptation layer (e.g., 6LoWPAN L2 packets are limited to 127 bytes including various overheads); this may motivate implementations to be frugal in their packet sizes and to move to block-wise transfers [BLOCK] when approaching three-digit message sizes. Message sizes are also of considerable importance to implementations on constrained nodes. Many implementations will need to allocate a buffer for incoming messages. If an implementation is too constrained to allow for allocating the above-mentioned upper bound, it could apply the following implementation strategy for messages not using DTLS security: Implementations receiving a datagram into a buffer that is too small are usually able to determine if the trailing portion of a datagram was discarded and to retrieve the initial portion. So, at least the CoAP header and options, if not all of the payload, are likely to fit within the buffer. A server can thus fully interpret a request and return a 4.13 (Request Entity Too Large; see Section 5.9.2.9) Response Code if the payload was truncated. A client sending an idempotent request and receiving a response larger than would fit in the buffer can repeat the request with a suitable value for the Block Option [BLOCK].4.7. Congestion Control
Basic congestion control for CoAP is provided by the exponential back-off mechanism in Section 4.2. In order not to cause congestion, clients (including proxies) MUST strictly limit the number of simultaneous outstanding interactions that they maintain to a given server (including proxies) to NSTART. An outstanding interaction is either a CON for which an ACK has not yet been received but is still expected (message layer) or a request for which neither a response nor an Acknowledgment message has yet been received but is still expected (which may both occur at the same time, counting as one outstanding interaction). The default value of NSTART for this specification is 1. Further congestion control optimizations and considerations are expected in the future, may for example provide automatic initialization of the CoAP transmission parameters defined in Section 4.8, and thus may allow a value for NSTART greater than one. After EXCHANGE_LIFETIME, a client stops expecting a response to a Confirmable request for which no acknowledgment message was received. Shelby, et al. Standards Track [Page 26]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 The specific algorithm by which a client stops to "expect" a response to a Confirmable request that was acknowledged, or to a Non- confirmable request, is not defined. Unless this is modified by additional congestion control optimizations, it MUST be chosen in such a way that an endpoint does not exceed an average data rate of PROBING_RATE in sending to another endpoint that does not respond. Note: CoAP places the onus of congestion control mostly on the clients. However, clients may malfunction or actually be attackers, e.g., to perform amplification attacks (Section 11.3). To limit the damage (to the network and to its own energy resources), a server SHOULD implement some rate limiting for its response transmission based on reasonable assumptions about application requirements. This is most helpful if the rate limit can be made effective for the misbehaving endpoints, only.4.8. Transmission Parameters
Message transmission is controlled by the following parameters: +-------------------+---------------+ | name | default value | +-------------------+---------------+ | ACK_TIMEOUT | 2 seconds | | ACK_RANDOM_FACTOR | 1.5 | | MAX_RETRANSMIT | 4 | | NSTART | 1 | | DEFAULT_LEISURE | 5 seconds | | PROBING_RATE | 1 byte/second | +-------------------+---------------+ Table 2: CoAP Protocol Parameters4.8.1. Changing the Parameters
The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT, NSTART, DEFAULT_LEISURE (Section 8.2), and PROBING_RATE may be configured to values specific to the application environment (including dynamically adjusted values); however, the configuration method is out of scope of this document. It is RECOMMENDED that an application environment use consistent values for these parameters; the specific effects of operating with inconsistent values in an application environment are outside the scope of the present specification. The transmission parameters have been chosen to achieve a behavior in the presence of congestion that is safe in the Internet. If a configuration desires to use different values, the onus is on the Shelby, et al. Standards Track [Page 27]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 configuration to ensure these congestion control properties are not violated. In particular, a decrease of ACK_TIMEOUT below 1 second would violate the guidelines of [RFC5405]. ([RTO-CONSIDER] provides some additional background.) CoAP was designed to enable implementations that do not maintain round-trip-time (RTT) measurements. However, where it is desired to decrease the ACK_TIMEOUT significantly or increase NSTART, this can only be done safely when maintaining such measurements. Configurations MUST NOT decrease ACK_TIMEOUT or increase NSTART without using mechanisms that ensure congestion control safety, either defined in the configuration or in future standards documents. ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have a value that is sufficiently different from 1.0 to provide some protection from synchronization effects. MAX_RETRANSMIT can be freely adjusted, but a value that is too small will reduce the probability that a Confirmable message is actually received, while a larger value than given here will require further adjustments in the time values (see Section 4.8.2). If the choice of transmission parameters leads to an increase of derived time values (see Section 4.8.2), the configuration mechanism MUST ensure the adjusted value is also available to all the endpoints with which these adjusted values are to be used to communicate.4.8.2. Time Values Derived from Transmission Parameters
The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR, and MAX_RETRANSMIT influences the timing of retransmissions, which in turn influences how long certain information items need to be kept by an implementation. To be able to unambiguously reference these derived time values, we give them names as follows: o MAX_TRANSMIT_SPAN is the maximum time from the first transmission of a Confirmable message to its last retransmission. For the default transmission parameters, the value is (2+4+8+16)*1.5 = 45 seconds, or more generally: ACK_TIMEOUT * ((2 ** MAX_RETRANSMIT) - 1) * ACK_RANDOM_FACTOR Shelby, et al. Standards Track [Page 28]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 o MAX_TRANSMIT_WAIT is the maximum time from the first transmission of a Confirmable message to the time when the sender gives up on receiving an acknowledgement or reset. For the default transmission parameters, the value is (2+4+8+16+32)*1.5 = 93 seconds, or more generally: ACK_TIMEOUT * ((2 ** (MAX_RETRANSMIT + 1)) - 1) * ACK_RANDOM_FACTOR In addition, some assumptions need to be made on the characteristics of the network and the nodes. o MAX_LATENCY is the maximum time a datagram is expected to take from the start of its transmission to the completion of its reception. This constant is related to the MSL (Maximum Segment Lifetime) of [RFC0793], which is "arbitrarily defined to be 2 minutes" ([RFC0793] glossary, page 81). Note that this is not necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not intended to describe a situation when the protocol works well, but the worst-case situation against which the protocol has to guard. We, also arbitrarily, define MAX_LATENCY to be 100 seconds. Apart from being reasonably realistic for the bulk of configurations as well as close to the historic choice for TCP, this value also allows Message ID lifetime timers to be represented in 8 bits (when measured in seconds). In these calculations, there is no assumption that the direction of the transmission is irrelevant (i.e., that the network is symmetric); there is just the assumption that the same value can reasonably be used as a maximum value for both directions. If that is not the case, the following calculations become only slightly more complex. o PROCESSING_DELAY is the time a node takes to turn around a Confirmable message into an acknowledgement. We assume the node will attempt to send an ACK before having the sender time out, so as a conservative assumption we set it equal to ACK_TIMEOUT. o MAX_RTT is the maximum round-trip time, or: (2 * MAX_LATENCY) + PROCESSING_DELAY From these values, we can derive the following values relevant to the protocol operation: o EXCHANGE_LIFETIME is the time from starting to send a Confirmable message to the time when an acknowledgement is no longer expected, i.e., message-layer information about the message exchange can be purged. EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the Shelby, et al. Standards Track [Page 29]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 way back. Note that there is no need to consider MAX_TRANSMIT_WAIT if the configuration is chosen such that the last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY is a worst-case value unlikely to be met in the real world. In this case, EXCHANGE_LIFETIME simplifies to: MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY or 247 seconds with the default transmission parameters. o NON_LIFETIME is the time from sending a Non-confirmable message to the time its Message ID can be safely reused. If multiple transmission of a NON message is not used, its value is MAX_LATENCY, or 100 seconds. However, a CoAP sender might send a NON message multiple times, in particular for multicast applications. While the period of reuse is not bounded by the specification, an expectation of reliable detection of duplication at the receiver is on the timescales of MAX_TRANSMIT_SPAN. Therefore, for this purpose, it is safer to use the value: MAX_TRANSMIT_SPAN + MAX_LATENCY or 145 seconds with the default transmission parameters; however, an implementation that just wants to use a single timeout value for retiring Message IDs can safely use the larger value for EXCHANGE_LIFETIME. Table 3 lists the derived parameters introduced in this subsection with their default values. +-------------------+---------------+ | name | default value | +-------------------+---------------+ | MAX_TRANSMIT_SPAN | 45 s | | MAX_TRANSMIT_WAIT | 93 s | | MAX_LATENCY | 100 s | | PROCESSING_DELAY | 2 s | | MAX_RTT | 202 s | | EXCHANGE_LIFETIME | 247 s | | NON_LIFETIME | 145 s | +-------------------+---------------+ Table 3: Derived Protocol Parameters Shelby, et al. Standards Track [Page 30]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145. Request/Response Semantics
CoAP operates under a similar request/response model as HTTP: a CoAP endpoint in the role of a "client" sends one or more CoAP requests to a "server", which services the requests by sending CoAP responses. Unlike HTTP, requests and responses are not sent over a previously established connection but are exchanged asynchronously over CoAP messages.5.1. Requests
A CoAP request consists of the method to be applied to the resource, the identifier of the resource, a payload and Internet media type (if any), and optional metadata about the request. CoAP supports the basic methods of GET, POST, PUT, and DELETE, which are easily mapped to HTTP. They have the same properties of safe (only retrieval) and idempotent (you can invoke it multiple times with the same effects) as HTTP (see Section 9.1 of [RFC2616]). The GET method is safe; therefore, it MUST NOT take any other action on a resource other than retrieval. The GET, PUT, and DELETE methods MUST be performed in such a way that they are idempotent. POST is not idempotent, because its effect is determined by the origin server and dependent on the target resource; it usually results in a new resource being created or the target resource being updated. A request is initiated by setting the Code field in the CoAP header of a Confirmable or a Non-confirmable message to a Method Code and including request information. The methods used in requests are described in detail in Section 5.8.5.2. Responses
After receiving and interpreting a request, a server responds with a CoAP response that is matched to the request by means of a client- generated token (Section 5.3); note that this is different from the Message ID that matches a Confirmable message to its Acknowledgement. A response is identified by the Code field in the CoAP header being set to a Response Code. Similar to the HTTP Status Code, the CoAP Response Code indicates the result of the attempt to understand and satisfy the request. These codes are fully defined in Section 5.9. The Response Code numbers to be set in the Code field of the CoAP header are maintained in the CoAP Response Code Registry (Section 12.1.2). Shelby, et al. Standards Track [Page 31]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 0 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+-+ |class| detail | +-+-+-+-+-+-+-+-+ Figure 9: Structure of a Response Code The upper three bits of the 8-bit Response Code number define the class of response. The lower five bits do not have any categorization role; they give additional detail to the overall class (Figure 9). As a human-readable notation for specifications and protocol diagnostics, CoAP code numbers including the Response Code are documented in the format "c.dd", where "c" is the class in decimal, and "dd" is the detail as a two-digit decimal. For example, "Forbidden" is written as 4.03 -- indicating an 8-bit code value of hexadecimal 0x83 (4*0x20+3) or decimal 131 (4*32+3). There are 3 classes of Response Codes: 2 - Success: The request was successfully received, understood, and accepted. 4 - Client Error: The request contains bad syntax or cannot be fulfilled. 5 - Server Error: The server failed to fulfill an apparently valid request. The Response Codes are designed to be extensible: Response Codes in the Client Error or Server Error class that are unrecognized by an endpoint are treated as being equivalent to the generic Response Code of that class (4.00 and 5.00, respectively). However, there is no generic Response Code indicating success, so a Response Code in the Success class that is unrecognized by an endpoint can only be used to determine that the request was successful without any further details. The possible Response Codes are described in detail in Section 5.9. Responses can be sent in multiple ways, which are defined in the following subsections. Shelby, et al. Standards Track [Page 32]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.2.1. Piggybacked
In the most basic case, the response is carried directly in the Acknowledgement message that acknowledges the request (which requires that the request was carried in a Confirmable message). This is called a "Piggybacked Response". The response is returned in the Acknowledgement message, independent of whether the response indicates success or failure. In effect, the response is piggybacked on the Acknowledgement message, and no separate message is required to return the response. Implementation Note: The protocol leaves the decision whether to piggyback a response or not (i.e., send a separate response) to the server. The client MUST be prepared to receive either. On the quality-of-implementation level, there is a strong expectation that servers will implement code to piggyback whenever possible -- saving resources in the network and both at the client and at the server.5.2.2. Separate
It may not be possible to return a piggybacked response in all cases. For example, a server might need longer to obtain the representation of the resource requested than it can wait to send back the Acknowledgement message, without risking the client repeatedly retransmitting the request message (see also the discussion of PROCESSING_DELAY in Section 4.8.2). The response to a request carried in a Non-confirmable message is always sent separately (as there is no Acknowledgement message). One way to implement this in a server is to initiate the attempt to obtain the resource representation and, while that is in progress, time out an acknowledgement timer. A server may also immediately send an acknowledgement if it knows in advance that there will be no piggybacked response. In both cases, the acknowledgement effectively is a promise that the request will be acted upon later. When the server finally has obtained the resource representation, it sends the response. When it is desired that this message is not lost, it is sent as a Confirmable message from the server to the client and answered by the client with an Acknowledgement, echoing the new Message ID chosen by the server. (It may also be sent as a Non-confirmable message; see Section 5.2.3.) When the server chooses to use a separate response, it sends the Acknowledgement to the Confirmable request as an Empty message. Once the server sends back an Empty Acknowledgement, it MUST NOT send back Shelby, et al. Standards Track [Page 33]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 the response in another Acknowledgement, even if the client retransmits another identical request. If a retransmitted request is received (perhaps because the original Acknowledgement was delayed), another Empty Acknowledgement is sent, and any response MUST be sent as a separate response. If the server then sends a Confirmable response, the client's Acknowledgement to that response MUST also be an Empty message (one that carries neither a request nor a response). The server MUST stop retransmitting its response on any matching Acknowledgement (silently ignoring any Response Code or payload) or Reset message. Implementation Notes: Note that, as the underlying datagram transport may not be sequence-preserving, the Confirmable message carrying the response may actually arrive before or after the Acknowledgement message for the request; for the purposes of terminating the retransmission sequence, this also serves as an acknowledgement. Note also that, while the CoAP protocol itself does not make any specific demands here, there is an expectation that the response will come within a time frame that is reasonable from an application point of view. As there is no underlying transport protocol that could be instructed to run a keep-alive mechanism, the requester may want to set up a timeout that is unrelated to CoAP's retransmission timers in case the server is destroyed or otherwise unable to send the response.5.2.3. Non-confirmable
If the request message is Non-confirmable, then the response SHOULD be returned in a Non-confirmable message as well. However, an endpoint MUST be prepared to receive a Non-confirmable response (preceded or followed by an Empty Acknowledgement message) in reply to a Confirmable request, or a Confirmable response in reply to a Non-confirmable request.5.3. Request/Response Matching
Regardless of how a response is sent, it is matched to the request by means of a token that is included by the client in the request, along with additional address information of the corresponding endpoint.5.3.1. Token
The Token is used to match a response with a request. The token value is a sequence of 0 to 8 bytes. (Note that every message carries a token, even if it is of zero length.) Every request carries a client-generated token that the server MUST echo (without modification) in any resulting response. Shelby, et al. Standards Track [Page 34]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 A token is intended for use as a client-local identifier for differentiating between concurrent requests (see Section 5.3); it could have been called a "request ID". The client SHOULD generate tokens in such a way that tokens currently in use for a given source/destination endpoint pair are unique. (Note that a client implementation can use the same token for any request if it uses a different endpoint each time, e.g., a different source port number.) An empty token value is appropriate e.g., when no other tokens are in use to a destination, or when requests are made serially per destination and receive piggybacked responses. There are, however, multiple possible implementation strategies to fulfill this. A client sending a request without using Transport Layer Security (Section 9) SHOULD use a nontrivial, randomized token to guard against spoofing of responses (Section 11.4). This protective use of tokens is the reason they are allowed to be up to 8 bytes in size. The actual size of the random component to be used for the Token depends on the security requirements of the client and the level of threat posed by spoofing of responses. A client that is connected to the general Internet SHOULD use at least 32 bits of randomness, keeping in mind that not being directly connected to the Internet is not necessarily sufficient protection against spoofing. (Note that the Message ID adds little in protection as it is usually sequentially assigned, i.e., guessable, and can be circumvented by spoofing a separate response.) Clients that want to optimize the Token length may further want to detect the level of ongoing attacks (e.g., by tallying recent Token mismatches in incoming messages) and adjust the Token length upwards appropriately. [RFC4086] discusses randomness requirements for security. An endpoint receiving a token it did not generate MUST treat the token as opaque and make no assumptions about its content or structure.
5.3.2. Request/Response Matching Rules
The exact rules for matching a response to a request are as follows: 1. The source endpoint of the response MUST be the same as the destination endpoint of the original request. 2. In a piggybacked response, the Message ID of the Confirmable request and the Acknowledgement MUST match, and the tokens of the response and original request MUST match. In a separate response, just the tokens of the response and original request MUST match. Shelby, et al. Standards Track [Page 35]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 In case a message carrying a response is unexpected (the client is not waiting for a response from the identified endpoint, at the endpoint addressed, and/or with the given token), the response is rejected (Sections 4.2 and 4.3). Implementation Note: A client that receives a response in a CON message may want to clean up the message state right after sending the ACK. If that ACK is lost and the server retransmits the CON, the client may no longer have any state to which to correlate this response, making the retransmission an unexpected message; the client will likely send a Reset message so it does not receive any more retransmissions. This behavior is normal and not an indication of an error. (Clients that are not aggressively optimized in their state memory usage will still have message state that will identify the second CON as a retransmission. Clients that actually expect more messages from the server [OBSERVE] will have to keep state in any case.)5.4. Options
Both requests and responses may include a list of one or more options. For example, the URI in a request is transported in several options, and metadata that would be carried in an HTTP header in HTTP is supplied as options as well. CoAP defines a single set of options that are used in both requests and responses: o Content-Format o ETag o Location-Path o Location-Query o Max-Age o Proxy-Uri o Proxy-Scheme o Uri-Host o Uri-Path o Uri-Port Shelby, et al. Standards Track [Page 36]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 o Uri-Query o Accept o If-Match o If-None-Match o Size1 The semantics of these options along with their properties are defined in detail in Section 5.10. Not all options are defined for use with all methods and Response Codes. The possible options for methods and Response Codes are defined in Sections 5.8 and 5.9, respectively. In case an option is not defined for a Method or Response Code, it MUST NOT be included by a sender and MUST be treated like an unrecognized option by a recipient.5.4.1. Critical/Elective
Options fall into one of two classes: "critical" or "elective". The difference between these is how an option unrecognized by an endpoint is handled: o Upon reception, unrecognized options of class "elective" MUST be silently ignored. o Unrecognized options of class "critical" that occur in a Confirmable request MUST cause the return of a 4.02 (Bad Option) response. This response SHOULD include a diagnostic payload describing the unrecognized option(s) (see Section 5.5.2). o Unrecognized options of class "critical" that occur in a Confirmable response, or piggybacked in an Acknowledgement, MUST cause the response to be rejected (Section 4.2). o Unrecognized options of class "critical" that occur in a Non- confirmable message MUST cause the message to be rejected (Section 4.3). Note that, whether critical or elective, an option is never "mandatory" (it is always optional): these rules are defined in order to enable implementations to stop processing options they do not understand or implement. Shelby, et al. Standards Track [Page 37]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Critical/elective rules apply to non-proxying endpoints. A proxy processes options based on Unsafe/Safe-to-Forward classes as defined in Section 5.7.5.4.2. Proxy Unsafe or Safe-to-Forward and NoCacheKey
In addition to an option being marked as critical or elective, options are also classified based on how a proxy is to deal with the option if it does not recognize it. For this purpose, an option can either be considered Unsafe to forward (UnSafe is set) or Safe-to- Forward (UnSafe is clear). In addition, for an option that is marked Safe-to-Forward, the option number indicates whether or not it is intended to be part of the Cache-Key (Section 5.6) in a request. If some of the NoCacheKey bits are 0, it is; if all NoCacheKey bits are 1, it is not (see Section 5.4.6). Note: The Cache-Key indication is relevant only for proxies that do not implement the given option as a request option and instead rely on the Unsafe/Safe-to-Forward indication only. For example, for ETag, actually using the request option as a part of the Cache-Key is grossly inefficient, but it is the best thing one can do if ETag is not implemented by a proxy, as the response is going to differ based on the presence of the request option. A more useful proxy that does implement the ETag request option is not using ETag as a part of the Cache-Key. NoCacheKey is indicated in three bits so that only one out of eight codepoints is qualified as NoCacheKey, leaving seven out of eight codepoints for what appears to be the more likely case. Proxy behavior with regard to these classes is defined in Section 5.7.5.4.3. Length
Option values are defined to have a specific length, often in the form of an upper and lower bound. If the length of an option value in a request is outside the defined range, that option MUST be treated like an unrecognized option (see Section 5.4.1).5.4.4. Default Values
Options may be defined to have a default value. If the value of an option is intended to be this default value, the option SHOULD NOT be included in the message. If the option is not present, the default value MUST be assumed. Shelby, et al. Standards Track [Page 38]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Where a critical option has a default value, this is chosen in such a way that the absence of the option in a message can be processed properly both by implementations unaware of the critical option and by implementations that interpret this absence as the presence of the default value for the option.5.4.5. Repeatable Options
The definition of some options specifies that those options are repeatable. An option that is repeatable MAY be included one or more times in a message. An option that is not repeatable MUST NOT be included more than once in a message. If a message includes an option with more occurrences than the option is defined for, each supernumerary option occurrence that appears subsequently in the message MUST be treated like an unrecognized option (see Section 5.4.1).5.4.6. Option Numbers
An Option is identified by an option number, which also provides some additional semantics information, e.g., odd numbers indicate a critical option, while even numbers indicate an elective option. Note that this is not just a convention, it is a feature of the protocol: Whether an option is elective or critical is entirely determined by whether its option number is even or odd. More generally speaking, an Option number is constructed with a bit mask to indicate if an option is Critical or Elective, Unsafe or Safe-to-Forward, and, in the case of Safe-to-Forward, to provide a Cache-Key indication as shown by the following figure. In the following text, the bit mask is expressed as a single byte that is applied to the least significant byte of the option number in unsigned integer representation. When bit 7 (the least significant bit) is 1, an option is Critical (and likewise Elective when 0). When bit 6 is 1, an option is Unsafe (and likewise Safe-to-Forward when 0). When bit 6 is 0, i.e., the option is not Unsafe, it is not a Cache-Key (NoCacheKey) if and only if bits 3-5 are all set to 1; all other bit combinations mean that it indeed is a Cache-Key. These classes of options are explained in the next sections. 0 1 2 3 4 5 6 7 +---+---+---+---+---+---+---+---+ | | NoCacheKey| U | C | +---+---+---+---+---+---+---+---+ Figure 10: Option Number Mask (Least Significant Byte) Shelby, et al. Standards Track [Page 39]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 An endpoint may use an equivalent of the C code in Figure 11 to derive the characteristics of an option number "onum". Critical = (onum & 1); UnSafe = (onum & 2); NoCacheKey = ((onum & 0x1e) == 0x1c); Figure 11: Determining Characteristics from an Option Number The option numbers for the options defined in this document are listed in the "CoAP Option Numbers" registry (Section 12.2).5.5. Payloads and Representations
Both requests and responses may include a payload, depending on the Method or Response Code, respectively. If a Method or Response Code is not defined to have a payload, then a sender MUST NOT include one, and a recipient MUST ignore it.5.5.1. Representation
The payload of requests or of responses indicating success is typically a representation of a resource ("resource representation") or the result of the requested action ("action result"). Its format is specified by the Internet media type and content coding given by the Content-Format Option. In the absence of this option, no default value is assumed, and the format will need to be inferred by the application (e.g., from the application context). Payload "sniffing" SHOULD only be attempted if no content type is given. Implementation Note: On a quality-of-implementation level, there is a strong expectation that a Content-Format indication will be provided with resource representations whenever possible. This is not a "SHOULD" level requirement solely because it is not a protocol requirement, and it also would be difficult to outline exactly in what cases this expectation can be violated. For responses indicating a client or server error, the payload is considered a representation of the result of the requested action only if a Content-Format Option is given. In the absence of this option, the payload is a Diagnostic Payload (Section 5.5.2). Shelby, et al. Standards Track [Page 40]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.5.2. Diagnostic Payload
If no Content-Format option is given, the payload of responses indicating a client or server error is a brief human-readable diagnostic message, explaining the error situation. This diagnostic message MUST be encoded using UTF-8 [RFC3629], more specifically using Net-Unicode form [RFC5198]. The message is similar to the Reason-Phrase on an HTTP status line. It is not intended for end users but for software engineers that during debugging need to interpret it in the context of the present, English-language specification; therefore, no mechanism for language tagging is needed or provided. In contrast to what is usual in HTTP, the payload SHOULD be empty if there is no additional information beyond the Response Code.5.5.3. Selected Representation
Not all responses carry a payload that provides a representation of the resource addressed by the request. It is, however, sometimes useful to be able to refer to such a representation in relation to a response, independent of whether it actually was enclosed. We use the term "selected representation" to refer to the current representation of a target resource that would have been selected in a successful response if the corresponding request had used the method GET and excluded any conditional request options (Section 5.10.8). Certain response options provide metadata about the selected representation, which might differ from the representation included in the message for responses to some state-changing methods. Of the response options defined in this specification, only the ETag response option (Section 5.10.6) is defined as metadata about the selected representation.5.5.4. Content Negotiation
A server may be able to supply a representation for a resource in one of multiple representation formats. Without further information from the client, it will provide the representation in the format it prefers. By using the Accept Option (Section 5.10.4) in a request, the client can indicate which content-format it prefers to receive. Shelby, et al. Standards Track [Page 41]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.6. Caching
CoAP endpoints MAY cache responses in order to reduce the response time and network bandwidth consumption on future, equivalent requests. The goal of caching in CoAP is to reuse a prior response message to satisfy a current request. In some cases, a stored response can be reused without the need for a network request, reducing latency and network round-trips; a "freshness" mechanism is used for this purpose (see Section 5.6.1). Even when a new request is required, it is often possible to reuse the payload of a prior response to satisfy the request, thereby reducing network bandwidth usage; a "validation" mechanism is used for this purpose (see Section 5.6.2). Unlike HTTP, the cacheability of CoAP responses does not depend on the request method, but it depends on the Response Code. The cacheability of each Response Code is defined along the Response Code definitions in Section 5.9. Response Codes that indicate success and are unrecognized by an endpoint MUST NOT be cached. For a presented request, a CoAP endpoint MUST NOT use a stored response, unless: o the presented request method and that used to obtain the stored response match, o all options match between those in the presented request and those of the request used to obtain the stored response (which includes the request URI), except that there is no need for a match of any request options marked as NoCacheKey (Section 5.4) or recognized by the Cache and fully interpreted with respect to its specified cache behavior (such as the ETag request option described in Section 5.10.6; see also Section 5.4.2), and o the stored response is either fresh or successfully validated as defined below. The set of request options that is used for matching the cache entry is also collectively referred to as the "Cache-Key". For URI schemes other than coap and coaps, matching of those options that constitute the request URI may be performed under rules specific to the URI scheme. Shelby, et al. Standards Track [Page 42]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.6.1. Freshness Model
When a response is "fresh" in the cache, it can be used to satisfy subsequent requests without contacting the origin server, thereby improving efficiency. The mechanism for determining freshness is for an origin server to provide an explicit expiration time in the future, using the Max-Age Option (see Section 5.10.5). The Max-Age Option indicates that the response is to be considered not fresh after its age is greater than the specified number of seconds. The Max-Age Option defaults to a value of 60. Thus, if it is not present in a cacheable response, then the response is considered not fresh after its age is greater than 60 seconds. If an origin server wishes to prevent caching, it MUST explicitly include a Max-Age Option with a value of zero seconds. If a client has a fresh stored response and makes a new request matching the request for that stored response, the new response invalidates the old response.5.6.2. Validation Model
When an endpoint has one or more stored responses for a GET request, but cannot use any of them (e.g., because they are not fresh), it can use the ETag Option (Section 5.10.6) in the GET request to give the origin server an opportunity both to select a stored response to be used, and to update its freshness. This process is known as "validating" or "revalidating" the stored response. When sending such a request, the endpoint SHOULD add an ETag Option specifying the entity-tag of each stored response that is applicable. A 2.03 (Valid) response indicates the stored response identified by the entity-tag given in the response's ETag Option can be reused after updating it as described in Section 5.9.1.3. Any other Response Code indicates that none of the stored responses nominated in the request is suitable. Instead, the response SHOULD be used to satisfy the request and MAY replace the stored response. Shelby, et al. Standards Track [Page 43]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.7. Proxying
A proxy is a CoAP endpoint that can be tasked by CoAP clients to perform requests on their behalf. This may be useful, for example, when the request could otherwise not be made, or to service the response from a cache in order to reduce response time and network bandwidth or energy consumption. In an overall architecture for a Constrained RESTful Environment, proxies can serve quite different purposes. Proxies can be explicitly selected by clients, a role that we term "forward-proxy". Proxies can also be inserted to stand in for origin servers, a role that we term "reverse-proxy". Orthogonal to this distinction, a proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP proxy) or translate from or to a different protocol ("cross-proxy"). Full definitions of these terms are provided in Section 1.2. Notes: The terminology in this specification has been selected to be culturally compatible with the terminology used in the wider web application environments, without necessarily matching it in every detail (which may not even be relevant to Constrained RESTful Environments). Not too much semantics should be ascribed to the components of the terms (such as "forward", "reverse", or "cross"). HTTP proxies, besides acting as HTTP proxies, often offer a transport-protocol proxying function ("CONNECT") to enable end-to- end transport layer security through the proxy. No such function is defined for CoAP-to-CoAP proxies in this specification, as forwarding of UDP packets is unlikely to be of much value in Constrained RESTful Environments. See also Section 10.2.7 for the cross-proxy case. When a client uses a proxy to make a request that will use a secure URI scheme (e.g., "coaps" or "https"), the request towards the proxy SHOULD be sent using DTLS except where equivalent lower-layer security is used for the leg between the client and the proxy.5.7.1. Proxy Operation
A proxy generally needs a way to determine potential request parameters for a request it places to a destination, based on the request it received from its client. This way is fully specified for a forward-proxy but may depend on the specific configuration for a reverse-proxy. In particular, the client of a reverse-proxy generally does not indicate a locator for the destination, Shelby, et al. Standards Track [Page 44]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 necessitating some form of namespace translation in the reverse- proxy. However, some aspects of the operation of proxies are common to all its forms. If a proxy does not employ a cache, then it simply forwards the translated request to the determined destination. Otherwise, if it does employ a cache but does not have a stored response that matches the translated request and is considered fresh, then it needs to refresh its cache according to Section 5.6. For options in the request that the proxy recognizes, it knows whether the option is intended to act as part of the key used in looking up the cached value or not. For example, since requests for different Uri-Path values address different resources, Uri-Path values are always part of the Cache-Key, while, e.g., Token values are never part of the Cache-Key. For options that the proxy does not recognize but that are marked Safe-to-Forward in the option number, the option also indicates whether it is to be included in the Cache-Key (NoCacheKey is not all set) or not (NoCacheKey is all set). (Options that are unrecognized and marked Unsafe lead to 4.02 Bad Option.) If the request to the destination times out, then a 5.04 (Gateway Timeout) response MUST be returned. If the request to the destination returns a response that cannot be processed by the proxy (e.g, due to unrecognized critical options or message format errors), then a 5.02 (Bad Gateway) response MUST be returned. Otherwise, the proxy returns the response to the client. If a response is generated out of a cache, the generated (or implied) Max-Age Option MUST NOT extend the max-age originally set by the server, considering the time the resource representation spent in the cache. For example, the Max-Age Option could be adjusted by the proxy for each response using the formula: proxy-max-age = original-max-age - cache-age For example, if a request is made to a proxied resource that was refreshed 20 seconds ago and had an original Max-Age of 60 seconds, then that resource's proxied max-age is now 40 seconds. Considering potential network delays on the way from the origin server, a proxy should be conservative in the max-age values offered. All options present in a proxy request MUST be processed at the proxy. Unsafe options in a request that are not recognized by the proxy MUST lead to a 4.02 (Bad Option) response being returned by the proxy. A CoAP-to-CoAP proxy MUST forward to the origin server all Safe-to-Forward options that it does not recognize. Similarly, Shelby, et al. Standards Track [Page 45]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 Unsafe options in a response that are not recognized by the CoAP-to- CoAP proxy server MUST lead to a 5.02 (Bad Gateway) response. Again, Safe-to-Forward options that are not recognized MUST be forwarded. Additional considerations for cross-protocol proxying between CoAP and HTTP are discussed in Section 10.5.7.2. Forward-Proxies
CoAP distinguishes between requests made (as if) to an origin server and requests made through a forward-proxy. CoAP requests to a forward-proxy are made as normal Confirmable or Non-confirmable requests to the forward-proxy endpoint, but they specify the request URI in a different way: The request URI in a proxy request is specified as a string in the Proxy-Uri Option (see Section 5.10.2), while the request URI in a request to an origin server is split into the Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options (see Section 5.10.1). Alternatively, the URI in a proxy request can be assembled from a Proxy-Scheme option and the split options mentioned. When a proxy request is made to an endpoint and the endpoint is unwilling or unable to act as proxy for the request URI, it MUST return a 5.05 (Proxying Not Supported) response. If the authority (host and port) is recognized as identifying the proxy endpoint itself (see Section 5.10.2), then the request MUST be treated as a local (non-proxied) request. Unless a proxy is configured to forward the proxy request to another proxy, it MUST translate the request as follows: the scheme of the request URI defines the outgoing protocol and its details (e.g., CoAP is used over UDP for the "coap" scheme and over DTLS for the "coaps" scheme.) For a CoAP-to-CoAP proxy, the origin server's IP address and port are determined by the authority component of the request URI, and the request URI is decoded and split into the Uri-Host, Uri- Port, Uri-Path and Uri-Query Options. This consumes the Proxy-Uri or Proxy-Scheme option, which is therefore not forwarded to the origin server.5.7.3. Reverse-Proxies
Reverse-proxies do not make use of the Proxy-Uri or Proxy-Scheme options but need to determine the destination (next hop) of a request from information in the request and information in their configuration. For example, a reverse-proxy might offer various resources as if they were its own resources, after having learned of their existence through resource discovery. The reverse-proxy is free to build a namespace for the URIs that identify these resources. A reverse-proxy may also build a namespace that gives the client more Shelby, et al. Standards Track [Page 46]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 control over where the request goes, e.g., by embedding host identifiers and port numbers into the URI path of the resources offered. In processing the response, a reverse-proxy has to be careful that ETag option values from different sources are not mixed up on one resource offered to its clients. In many cases, the ETag can be forwarded unchanged. If the mapping from a resource offered by the reverse-proxy to resources offered by its various origin servers is not unique, the reverse-proxy may need to generate a new ETag, making sure the semantics of this option are properly preserved.5.8. Method Definitions
In this section, each method is defined along with its behavior. A request with an unrecognized or unsupported Method Code MUST generate a 4.05 (Method Not Allowed) piggybacked response.5.8.1. GET
The GET method retrieves a representation for the information that currently corresponds to the resource identified by the request URI. If the request includes an Accept Option, that indicates the preferred content-format of a response. If the request includes an ETag Option, the GET method requests that ETag be validated and that the representation be transferred only if validation failed. Upon success, a 2.05 (Content) or 2.03 (Valid) Response Code SHOULD be present in the response. The GET method is safe and idempotent.5.8.2. POST
The POST method requests that the representation enclosed in the request be processed. The actual function performed by the POST method is determined by the origin server and dependent on the target resource. It usually results in a new resource being created or the target resource being updated. If a resource has been created on the server, the response returned by the server SHOULD have a 2.01 (Created) Response Code and SHOULD include the URI of the new resource in a sequence of one or more Location-Path and/or Location-Query Options (Section 5.10.7). If the POST succeeds but does not result in a new resource being created on the server, the response SHOULD have a 2.04 (Changed) Response Code. If the POST succeeds and results in the target resource being deleted, the response SHOULD have a 2.02 (Deleted) Response Code. POST is neither safe nor idempotent. Shelby, et al. Standards Track [Page 47]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.8.3. PUT
The PUT method requests that the resource identified by the request URI be updated or created with the enclosed representation. The representation format is specified by the media type and content coding given in the Content-Format Option, if provided. If a resource exists at the request URI, the enclosed representation SHOULD be considered a modified version of that resource, and a 2.04 (Changed) Response Code SHOULD be returned. If no resource exists, then the server MAY create a new resource with that URI, resulting in a 2.01 (Created) Response Code. If the resource could not be created or modified, then an appropriate error Response Code SHOULD be sent. Further restrictions to a PUT can be made by including the If-Match (see Section 5.10.8.1) or If-None-Match (see Section 5.10.8.2) options in the request. PUT is not safe but is idempotent.5.8.4. DELETE
The DELETE method requests that the resource identified by the request URI be deleted. A 2.02 (Deleted) Response Code SHOULD be used on success or in case the resource did not exist before the request. DELETE is not safe but is idempotent.5.9. Response Code Definitions
Each Response Code is described below, including any options required in the response. Where appropriate, some of the codes will be specified in regards to related Response Codes in HTTP [RFC2616]; this does not mean that any such relationship modifies the HTTP mapping specified in Section 10.5.9.1. Success 2.xx
This class of Response Code indicates that the clients request was successfully received, understood, and accepted.5.9.1.1. 2.01 Created
Like HTTP 201 "Created", but only used in response to POST and PUT requests. The payload returned with the response, if any, is a representation of the action result. Shelby, et al. Standards Track [Page 48]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 If the response includes one or more Location-Path and/or Location- Query Options, the values of these options specify the location at which the resource was created. Otherwise, the resource was created at the request URI. A cache receiving this response MUST mark any stored response for the created resource as not fresh. This response is not cacheable.5.9.1.2. 2.02 Deleted
This Response Code is like HTTP 204 "No Content" but only used in response to requests that cause the resource to cease being available, such as DELETE and, in certain circumstances, POST. The payload returned with the response, if any, is a representation of the action result. This response is not cacheable. However, a cache MUST mark any stored response for the deleted resource as not fresh.5.9.1.3. 2.03 Valid
This Response Code is related to HTTP 304 "Not Modified" but only used to indicate that the response identified by the entity-tag identified by the included ETag Option is valid. Accordingly, the response MUST include an ETag Option and MUST NOT include a payload. When a cache that recognizes and processes the ETag response option receives a 2.03 (Valid) response, it MUST update the stored response with the value of the Max-Age Option included in the response (explicitly, or implicitly as a default value; see also Section 5.6.2). For each type of Safe-to-Forward option present in the response, the (possibly empty) set of options of this type that are present in the stored response MUST be replaced with the set of options of this type in the response received. (Unsafe options may trigger similar option-specific processing as defined by the option.)5.9.1.4. 2.04 Changed
This Response Code is like HTTP 204 "No Content" but only used in response to POST and PUT requests. The payload returned with the response, if any, is a representation of the action result. This response is not cacheable. However, a cache MUST mark any stored response for the changed resource as not fresh. Shelby, et al. Standards Track [Page 49]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.9.1.5. 2.05 Content
This Response Code is like HTTP 200 "OK" but only used in response to GET requests. The payload returned with the response is a representation of the target resource. This response is cacheable: Caches can use the Max-Age Option to determine freshness (see Section 5.6.1) and (if present) the ETag Option for validation (see Section 5.6.2).5.9.2. Client Error 4.xx
This class of Response Code is intended for cases in which the client seems to have erred. These Response Codes are applicable to any request method. The server SHOULD include a diagnostic payload under the conditions detailed in Section 5.5.2. Responses of this class are cacheable: Caches can use the Max-Age Option to determine freshness (see Section 5.6.1). They cannot be validated.5.9.2.1. 4.00 Bad Request
This Response Code is Like HTTP 400 "Bad Request".5.9.2.2. 4.01 Unauthorized
The client is not authorized to perform the requested action. The client SHOULD NOT repeat the request without first improving its authentication status to the server. Which specific mechanism can be used for this is outside this document's scope; see also Section 9.5.9.2.3. 4.02 Bad Option
The request could not be understood by the server due to one or more unrecognized or malformed options. The client SHOULD NOT repeat the request without modification.5.9.2.4. 4.03 Forbidden
This Response Code is like HTTP 403 "Forbidden". Shelby, et al. Standards Track [Page 50]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.9.2.5. 4.04 Not Found
This Response Code is like HTTP 404 "Not Found".5.9.2.6. 4.05 Method Not Allowed
This Response Code is like HTTP 405 "Method Not Allowed" but with no parallel to the "Allow" header field.5.9.2.7. 4.06 Not Acceptable
This Response Code is like HTTP 406 "Not Acceptable", but with no response entity.5.9.2.8. 4.12 Precondition Failed
This Response Code is like HTTP 412 "Precondition Failed".5.9.2.9. 4.13 Request Entity Too Large
This Response Code is like HTTP 413 "Request Entity Too Large". The response SHOULD include a Size1 Option (Section 5.10.9) to indicate the maximum size of request entity the server is able and willing to handle, unless the server is not in a position to make this information available.5.9.2.10. 4.15 Unsupported Content-Format
This Response Code is like HTTP 415 "Unsupported Media Type".5.9.3. Server Error 5.xx
This class of Response Code indicates cases in which the server is aware that it has erred or is incapable of performing the request. These Response Codes are applicable to any request method. The server SHOULD include a diagnostic payload under the conditions detailed in Section 5.5.2. Responses of this class are cacheable: Caches can use the Max-Age Option to determine freshness (see Section 5.6.1). They cannot be validated.5.9.3.1. 5.00 Internal Server Error
This Response Code is like HTTP 500 "Internal Server Error". Shelby, et al. Standards Track [Page 51]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.9.3.2. 5.01 Not Implemented
This Response Code is like HTTP 501 "Not Implemented".5.9.3.3. 5.02 Bad Gateway
This Response Code is like HTTP 502 "Bad Gateway".5.9.3.4. 5.03 Service Unavailable
This Response Code is like HTTP 503 "Service Unavailable" but uses the Max-Age Option in place of the "Retry-After" header field to indicate the number of seconds after which to retry.5.9.3.5. 5.04 Gateway Timeout
This Response Code is like HTTP 504 "Gateway Timeout".5.9.3.6. 5.05 Proxying Not Supported
The server is unable or unwilling to act as a forward-proxy for the URI specified in the Proxy-Uri Option or using Proxy-Scheme (see Section 5.10.2).5.10. Option Definitions
The individual CoAP options are summarized in Table 4 and explained in the subsections of this section. In this table, the C, U, and N columns indicate the properties Critical, UnSafe, and NoCacheKey, respectively. Since NoCacheKey only has a meaning for options that are Safe-to-Forward (not marked Unsafe), the column is filled with a dash for UnSafe options. Shelby, et al. Standards Track [Page 52]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 +-----+---+---+---+---+----------------+--------+--------+----------+ | No. | C | U | N | R | Name | Format | Length | Default | +-----+---+---+---+---+----------------+--------+--------+----------+ | 1 | x | | | x | If-Match | opaque | 0-8 | (none) | | 3 | x | x | - | | Uri-Host | string | 1-255 | (see | | | | | | | | | | below) | | 4 | | | | x | ETag | opaque | 1-8 | (none) | | 5 | x | | | | If-None-Match | empty | 0 | (none) | | 7 | x | x | - | | Uri-Port | uint | 0-2 | (see | | | | | | | | | | below) | | 8 | | | | x | Location-Path | string | 0-255 | (none) | | 11 | x | x | - | x | Uri-Path | string | 0-255 | (none) | | 12 | | | | | Content-Format | uint | 0-2 | (none) | | 14 | | x | - | | Max-Age | uint | 0-4 | 60 | | 15 | x | x | - | x | Uri-Query | string | 0-255 | (none) | | 17 | x | | | | Accept | uint | 0-2 | (none) | | 20 | | | | x | Location-Query | string | 0-255 | (none) | | 35 | x | x | - | | Proxy-Uri | string | 1-1034 | (none) | | 39 | x | x | - | | Proxy-Scheme | string | 1-255 | (none) | | 60 | | | x | | Size1 | uint | 0-4 | (none) | +-----+---+---+---+---+----------------+--------+--------+----------+ C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable Table 4: Options5.10.1. Uri-Host, Uri-Port, Uri-Path, and Uri-Query
The Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options are used to specify the target resource of a request to a CoAP origin server. The options encode the different components of the request URI in a way that no percent-encoding is visible in the option values and that the full URI can be reconstructed at any involved endpoint. The syntax of CoAP URIs is defined in Section 6. The steps for parsing URIs into options is defined in Section 6.4. These steps result in zero or more Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options being included in a request, where each option holds the following values: o the Uri-Host Option specifies the Internet host of the resource being requested, o the Uri-Port Option specifies the transport-layer port number of the resource, o each Uri-Path Option specifies one segment of the absolute path to the resource, and Shelby, et al. Standards Track [Page 53]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 o each Uri-Query Option specifies one argument parameterizing the resource. Note: Fragments ([RFC3986], Section 3.5) are not part of the request URI and thus will not be transmitted in a CoAP request. The default value of the Uri-Host Option is the IP literal representing the destination IP address of the request message. Likewise, the default value of the Uri-Port Option is the destination UDP port. The default values for the Uri-Host and Uri-Port Options are sufficient for requests to most servers. Explicit Uri-Host and Uri-Port Options are typically used when an endpoint hosts multiple virtual servers. The Uri-Path and Uri-Query Option can contain any character sequence. No percent-encoding is performed. The value of a Uri-Path Option MUST NOT be "." or ".." (as the request URI must be resolved before parsing it into options). The steps for constructing the request URI from the options are defined in Section 6.5. Note that an implementation does not necessarily have to construct the URI; it can simply look up the target resource by examining the individual options. Examples can be found in Appendix B.5.10.2. Proxy-Uri and Proxy-Scheme
The Proxy-Uri Option is used to make a request to a forward-proxy (see Section 5.7). The forward-proxy is requested to forward the request or service it from a valid cache and return the response. The option value is an absolute-URI ([RFC3986], Section 4.3). Note that the forward-proxy MAY forward the request on to another proxy or directly to the server specified by the absolute-URI. In order to avoid request loops, a proxy MUST be able to recognize all of its server names, including any aliases, local variations, and the numeric IP addresses. An endpoint receiving a request with a Proxy-Uri Option that is unable or unwilling to act as a forward-proxy for the request MUST cause the return of a 5.05 (Proxying Not Supported) response. The Proxy-Uri Option MUST take precedence over any of the Uri-Host, Uri-Port, Uri-Path or Uri-Query options (each of which MUST NOT be included in a request containing the Proxy-Uri Option). Shelby, et al. Standards Track [Page 54]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 As a special case to simplify many proxy clients, the absolute-URI can be constructed from the Uri-* options. When a Proxy-Scheme Option is present, the absolute-URI is constructed as follows: a CoAP URI is constructed from the Uri-* options as defined in Section 6.5. In the resulting URI, the initial scheme up to, but not including, the following colon is then replaced by the content of the Proxy- Scheme Option. Note that this case is only applicable if the components of the desired URI other than the scheme component actually can be expressed using Uri-* options; for example, to represent a URI with a userinfo component in the authority, only Proxy-Uri can be used.5.10.3. Content-Format
The Content-Format Option indicates the representation format of the message payload. The representation format is given as a numeric Content-Format identifier that is defined in the "CoAP Content- Formats" registry (Section 12.3). In the absence of the option, no default value is assumed, i.e., the representation format of any representation message payload is indeterminate (Section 5.5).5.10.4. Accept
The CoAP Accept option can be used to indicate which Content-Format is acceptable to the client. The representation format is given as a numeric Content-Format identifier that is defined in the "CoAP Content-Formats" registry (Section 12.3). If no Accept option is given, the client does not express a preference (thus no default value is assumed). The client prefers the representation returned by the server to be in the Content-Format indicated. The server returns the preferred Content-Format if available. If the preferred Content- Format cannot be returned, then a 4.06 "Not Acceptable" MUST be sent as a response, unless another error code takes precedence for this response.5.10.5. Max-Age
The Max-Age Option indicates the maximum time a response may be cached before it is considered not fresh (see Section 5.6.1). The option value is an integer number of seconds between 0 and 2**32-1 inclusive (about 136.1 years). A default value of 60 seconds is assumed in the absence of the option in a response. The value is intended to be current at the time of transmission. Servers that provide resources with strict tolerances on the value of Max-Age SHOULD update the value before each retransmission. (See also Section 5.7.1.) Shelby, et al. Standards Track [Page 55]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.10.6. ETag
An entity-tag is intended for use as a resource-local identifier for differentiating between representations of the same resource that vary over time. It is generated by the server providing the resource, which may generate it in any number of ways including a version, checksum, hash, or time. An endpoint receiving an entity- tag MUST treat it as opaque and make no assumptions about its content or structure. (Endpoints that generate an entity-tag are encouraged to use the most compact representation possible, in particular in regards to clients and intermediaries that may want to store multiple ETag values.)5.10.6.1. ETag as a Response Option
The ETag Option in a response provides the current value (i.e., after the request was processed) of the entity-tag for the "tagged representation". If no Location-* options are present, the tagged representation is the selected representation (Section 5.5.3) of the target resource. If one or more Location-* options are present and thus a location URI is indicated (Section 5.10.7), the tagged representation is the representation that would be retrieved by a GET request to the location URI. An ETag response option can be included with any response for which there is a tagged representation (e.g., it would not be meaningful in a 4.04 or 4.00 response). The ETag Option MUST NOT occur more than once in a response. There is no default value for the ETag Option; if it is not present in a response, the server makes no statement about the entity-tag for the tagged representation.5.10.6.2. ETag as a Request Option
In a GET request, an endpoint that has one or more representations previously obtained from the resource, and has obtained ETag response options with these, can specify an instance of the ETag Option for one or more of these stored responses. A server can issue a 2.03 Valid response (Section 5.9.1.3) in place of a 2.05 Content response if one of the ETags given is the entity- tag for the current representation, i.e., is valid; the 2.03 Valid response then echoes this specific ETag in a response option. In effect, a client can determine if any of the stored representations is current (see Section 5.6.2) without needing to transfer them again. Shelby, et al. Standards Track [Page 56]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 The ETag Option MAY occur zero, one, or multiple times in a request.5.10.7. Location-Path and Location-Query
The Location-Path and Location-Query Options together indicate a relative URI that consists either of an absolute path, a query string, or both. A combination of these options is included in a 2.01 (Created) response to indicate the location of the resource created as the result of a POST request (see Section 5.8.2). The location is resolved relative to the request URI. If a response with one or more Location-Path and/or Location-Query Options passes through a cache that interprets these options and the implied URI identifies one or more currently stored responses, those entries MUST be marked as not fresh. Each Location-Path Option specifies one segment of the absolute path to the resource, and each Location-Query Option specifies one argument parameterizing the resource. The Location-Path and Location-Query Option can contain any character sequence. No percent-encoding is performed. The value of a Location-Path Option MUST NOT be "." or "..". The steps for constructing the location URI from the options are analogous to Section 6.5, except that the first five steps are skipped and the result is a relative URI-reference, which is then interpreted relative to the request URI. Note that the relative URI- reference constructed this way always includes an absolute path (e.g., leaving out Location-Path but supplying Location-Query means the path component in the URI is "/"). The options that are used to compute the relative URI-reference are collectively called Location-* options. Beyond Location-Path and Location-Query, more Location-* options may be defined in the future and have been reserved option numbers 128, 132, 136, and 140. If any of these reserved option numbers occurs in addition to Location-Path and/or Location-Query and are not supported, then a 4.02 (Bad Option) error MUST be returned.5.10.8. Conditional Request Options
Conditional request options enable a client to ask the server to perform the request only if certain conditions specified by the option are fulfilled. Shelby, et al. Standards Track [Page 57]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 For each of these options, if the condition given is not fulfilled, then the server MUST NOT perform the requested method. Instead, the server MUST respond with the 4.12 (Precondition Failed) Response Code. If the condition is fulfilled, the server performs the request method as if the conditional request options were not present. If the request would, without the conditional request options, result in anything other than a 2.xx or 4.12 Response Code, then any conditional request options MAY be ignored.5.10.8.1. If-Match
The If-Match Option MAY be used to make a request conditional on the current existence or value of an ETag for one or more representations of the target resource. If-Match is generally useful for resource update requests, such as PUT requests, as a means for protecting against accidental overwrites when multiple clients are acting in parallel on the same resource (i.e., the "lost update" problem). The value of an If-Match option is either an ETag or the empty string. An If-Match option with an ETag matches a representation with that exact ETag. An If-Match option with an empty value matches any existing representation (i.e., it places the precondition on the existence of any current representation for the target resource). The If-Match Option can occur multiple times. If any of the options match, then the condition is fulfilled. If there is one or more If-Match Options, but none of the options match, then the condition is not fulfilled.5.10.8.2. If-None-Match
The If-None-Match Option MAY be used to make a request conditional on the nonexistence of the target resource. If-None-Match is useful for resource creation requests, such as PUT requests, as a means for protecting against accidental overwrites when multiple clients are acting in parallel on the same resource. The If-None-Match Option carries no value. If the target resource does exist, then the condition is not fulfilled. (It is not very useful to combine If-Match and If-None-Match options in one request, because the condition will then never be fulfilled.) Shelby, et al. Standards Track [Page 58]
RFC 7252 The Constrained Application Protocol (CoAP) June 20145.10.9. Size1 Option
The Size1 option provides size information about the resource representation in a request. The option value is an integer number of bytes. Its main use is with block-wise transfers [BLOCK]. In the present specification, it is used in 4.13 responses (Section 5.9.2.9) to indicate the maximum size of request entity that the server is able and willing to handle.6. CoAP URIs
CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP resources and providing a means of locating the resource. Resources are organized hierarchically and governed by a potential CoAP origin server listening for CoAP requests ("coap") or DTLS-secured CoAP requests ("coaps") on a given UDP port. The CoAP server is identified via the generic syntax's authority component, which includes a host component and optional UDP port number. The remainder of the URI is considered to be identifying a resource that can be operated on by the methods defined by the CoAP protocol. The "coap" and "coaps" URI schemes can thus be compared to the "http" and "https" URI schemes, respectively. The syntax of the "coap" and "coaps" URI schemes is specified in this section in Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of "host", "port", "path-abempty", "query", "segment", "IP-literal", "IPv4address", and "reg-name" are adopted from [RFC3986]. Implementation Note: Unfortunately, over time, the URI format has acquired significant complexity. Implementers are encouraged to examine [RFC3986] closely. For example, the ABNF for IPv6 addresses is more complicated than maybe expected. Also, implementers should take care to perform the processing of percent-decoding or percent-encoding exactly once on the way from a URI to its decoded components or back. Percent-encoding is crucial for data transparency but may lead to unusual results such as a slash character in a path component.6.1. coap URI Scheme
coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ] If the host component is provided as an IP-literal or IPv4address, then the CoAP server can be reached at that IP address. If host is a registered name, then that name is considered an indirect identifier and the endpoint might use a name resolution service, such as DNS, to find the address of that host. The host MUST NOT be empty; if a URI Shelby, et al. Standards Track [Page 59]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014 is received with a missing authority or an empty host, then it MUST be considered invalid. The port subcomponent indicates the UDP port at which the CoAP server is located. If it is empty or not given, then the default port 5683 is assumed. The path identifies a resource within the scope of the host and port. It consists of a sequence of path segments separated by a slash character (U+002F SOLIDUS "/"). The query serves to further parameterize the resource. It consists of a sequence of arguments separated by an ampersand character (U+0026 AMPERSAND "&"). An argument is often in the form of a "key=value" pair. The "coap" URI scheme supports the path prefix "/.well-known/" defined by [RFC5785] for "well-known locations" in the namespace of a host. This enables discovery of policy or other information about a host ("site-wide metadata"), such as hosted resources (see Section 7). Application designers are encouraged to make use of short but descriptive URIs. As the environments that CoAP is used in are usually constrained for bandwidth and energy, the trade-off between these two qualities should lean towards the shortness, without ignoring descriptiveness.6.2. coaps URI Scheme
coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty [ "?" query ] All of the requirements listed above for the "coap" scheme are also requirements for the "coaps" scheme, except that a default UDP port of 5684 is assumed if the port subcomponent is empty or not given, and the UDP datagrams MUST be secured through the use of DTLS as described in Section 9.1. Considerations for caching of responses to "coaps" identified requests are discussed in Section 11.2. Resources made available via the "coaps" scheme have no shared identity with the "coap" scheme even if their resource identifiers indicate the same authority (the same host listening to the same UDP port). They are distinct namespaces and are considered to be distinct origin servers.
361
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
