One document matched: draft-ietf-core-coap-02.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC0792 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0792.xml">
<!ENTITY RFC2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
<!ENTITY RFC2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
<!ENTITY RFC2406 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2406.xml">
<!ENTITY RFC2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC3602 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3602.xml">
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC4288 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4288.xml">
<!ENTITY RFC4346 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4346.xml">
<!ENTITY RFC4347 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4347.xml">
<!ENTITY RFC4835 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4835.xml">
<!ENTITY RFC4944 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4944.xml">
<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
<!ENTITY RFC5246 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml">
<!ENTITY RFC5785 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5785.xml">
<!ENTITY I-D.bormann-6lowpan-6lowapp-problem SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.bormann-6lowpan-6lowapp-problem.xml">
<!ENTITY I-D.shelby-6lowapp-encoding SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.shelby-6lowapp-encoding.xml">
<!ENTITY I-D.frank-6lowapp-chopan SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.frank-6lowapp-chopan.xml">
<!ENTITY I-D.gold-6lowapp-sensei SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-gold-6lowapp-sensei-00.xml">
<!ENTITY I-D.martocci-6lowapp-building-applications SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-martocci-6lowapp-building-applications-00.xml">
<!ENTITY I-D.sturek-6lowapp-smartenergy SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-sturek-6lowapp-smartenergy-00.xml">
<!ENTITY I-D.moritz-6lowapp-dpws-enhancements SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-moritz-6lowapp-dpws-enhancements-00.xml">
<!ENTITY I-D.shelby-core-coap-req SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-shelby-core-coap-req-01.xml">
<!ENTITY I-D.nottingham-http-link-header SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-nottingham-http-link-header-09.xml">
<!ENTITY I-D.cheshire-dnsext-multicastdns SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-cheshire-dnsext-multicastdns-11.xml">
<!ENTITY I-D.cheshire-dnsext-dns-sd SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-cheshire-dnsext-dns-sd-06.xml">
<!ENTITY I-D.eggert-core-congestion-control SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-eggert-core-congestion-control-00.xml">
<!ENTITY I-D.hartke-coap-observe SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hartke-coap-observe-00.xml">
<!ENTITY I-D.oflynn-core-bootstrapping SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-oflynn-core-bootstrapping-01.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs),
please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
(Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="3"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space
(using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="std" ipr="trust200902" docName="draft-ietf-core-coap-02">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<front>
<title>Constrained Application Protocol (CoAP)</title>
<author initials="Z" surname="Shelby" fullname="Zach Shelby">
<organization>
Sensinode
</organization>
<address>
<postal>
<street>Kidekuja 2</street>
<city>Vuokatti</city>
<code>88600</code>
<country>FINLAND</country>
</postal>
<phone>+358407796297</phone>
<email>zach@sensinode.com</email>
</address>
</author>
<author initials="B" surname="Frank" fullname="Brian Frank">
<organization>
SkyFoundry
</organization>
<address>
<postal>
<street></street>
<city>Richmond, VA</city>
<code></code>
<country>USA</country>
</postal>
<phone></phone>
<email>brian@skyfoundry.com</email>
</address>
</author>
<author initials="D" surname="Sturek" fullname="Don Sturek">
<organization>
Pacific Gas & Electric
</organization>
<address>
<postal>
<street>77 Beale Street</street>
<city>San Francisco, CA</city>
<code></code>
<country>USA</country>
</postal>
<phone>+1-619-504-3615</phone>
<email>d.sturek@att.net</email>
</address>
</author>
<date year="2010"/>
<area>Internet</area>
<workgroup>CoRE</workgroup>
<keyword>CoAP, Constrained Application Protocol, REST</keyword>
<abstract>
<t>
This document specifies the Constrained Application Protocol (CoAP), a specialized web transfer protocol for use with constrained networks and nodes for machine-to-machine applications such as smart energy and building automation. These constrained nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while networks such as 6LoWPAN often have high packet error rates and a typical throughput of 10s of kbit/s.
CoAP provides a method/response interaction model between application end-points, supports built-in resource discovery, and includes key web concepts such as URIs and content-types. CoAP easily translates to HTTP for integration with the web while meeting specialized requirements such as multicast support, very low overhead and simplicity for constrained environments.
</t>
</abstract>
</front>
<middle>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='introduction' title="Introduction">
<t>
The use of web services on the Internet has become ubiquitous in most applications, and depends on the fundamental Representational State Transfer (REST) architecture of the web.
</t>
<t>
The Constrained RESTful Environments (CoRE) working group 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). Constrained networks like 6LoWPAN support the expensive fragmentation of IPv6 packets into small link-layer frames. One design goal of CoRE has been to keep message overhead small, thus limiting the use of fragmentation.
</t>
<t>One of the main goals of CoRE is to design a generic web protocol for the special requirements of this constrained environment, especially considering energy, building automation and other M2M applications. The goal of CoAP is not to blindly compress HTTP, but rather to realize a subset of REST common with HTTP but optimized for M2M applications. Although CoRE could be used for compressing simple HTTP interfaces, it more importantly also offers features for M2M such as built-in discovery, multicast support and asynchronous transactions.
</t>
<t>
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 <xref target="I-D.shelby-core-coap-req"/>. CoAP has the following main features:
<list style="symbols">
<t>Constrained web protocol fulfilling M2M requirements.</t>
<t>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.</t>
<t>UDP binding with reliable unicast and best-effort multicast support.</t>
<t>Asynchronous transaction support.</t>
<t>Low header overhead and parsing complexity.</t>
<t>URI and Content-type support.</t>
<t>Built-in resource discovery.</t>
<t>Simple proxy and caching capabilities.</t>
</list>
</t>
<t>
</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='protocol' title="Constrained Application Protocol">
<t>
This section specifies the basic functionality and processing rules of the protocol.
</t>
<section anchor='interaction' title="Interaction Model">
<t>
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 (called an end-point). A CoAP exchange 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. A response is then sent with a Response Code and resource representation if appropriate. </t>
<t>
Unlike HTTP, CoAP deals with these interchanges asynchronously over a UDP transport with support for both unicast and multicast interactions. This is achieved using transaction messages (Confirmable, Non-Confirmable, Acknowledgment, Reset) supporting optional reliability (with exponential back-off) and transaction IDs between end-points to carry requests and responses. These transactions are transparent to the request/response interchanges. The only difference being that responses may arrive asynchronously.
</t>
<t>
One could think of CoAP as using a two-layer approach, a transactional layer used to deal with UDP and the asynchronous nature of the interactions, and the request/response interactions using Method and Response codes.
</t>
<figure anchor='fig-layers' title="Abstract layering of CoAP">
<artwork>
+---------------------+
| Application |
+---------------------+
+---------------------+
| CoAP Req/Res |
|---------------------|
| CoAP Transactions |
+---------------------+
+---------------------+
| UDP |
+---------------------+
</artwork>
</figure>
<section anchor="synchronous-response" title="Synchronous response">
<t>The most basic interaction between the Req/Res and Transaction layers works by sending a request in a confirmable CoAP message and waiting for
an acknowledgment message that also carries the response.
E.g., two possible interactions for a basic GET are shown in <xref target="get-basic"/>.</t>
<figure anchor="get-basic" title="Two basic GET transactions, one successful, one not found"><artwork><![CDATA[
Client Server Client Server
| | | |
| CON tid=47 | | CON tid=53 |
| GET /foo | | GET /baz |
+---------------->| +---------------->|
| | | |
| ACK tid=47 | | ACK tid=53 |
| 200 "<temp... | | 404 "Not... |
|<----------------+ |<----------------+
| | | |
]]></artwork></figure>
<t>Note that at the transaction layer, the response is returned in an ACK
message, independent of whether the request was successful at the Req/Res layer.
In effect, the response is piggy-backed on the ACK message, so no
separate acknowledgment is required that the GET message was received.</t>
<t>The relationship between the confirmable message (CON) and the
acknowledgment message (ACK) is indicated by the transaction ID,
which is echoed back by the server in the ACK.
Transaction IDs are short-lived, they only serve to couple CON and ACK
messages.</t>
<t>The tight coupling between CON and ACK also relieves the ACK of the
need to echo back information from the request, such as the URI or a
request token supplied by the client. We say that a response
carried in an ACK <spanx style='emph'>pertains</spanx> to the request in the corresponding
CON.</t>
</section>
<section anchor="asynchronous-response" title="Asynchronous response">
<t>Not all interactions are as simple as the basic synchronous exchange
shown. For example, a server might need longer to obtain the
representation of the resource requested than it can wait sending back
the acknowledgment, without risking the client to repeatedly
retransmit the request. To handle this case, the response is
decoupled from the transaction layer acknowledgment. Actually, the
latter does not carry any message at all.</t>
<t>As the client cannot know that this will be the case, it sends exactly
the same confirmable message with the same request. The server
maybe attempts to obtain the resource (e.g., by acting as a proxy) and
times out an ACK timer, or it immediately sends an acknowledgment
knowing in advance that there will be no quick answer. The
acknowledgment effectively is a promise that the request will be
acted upon, see <xref target="get-async"/>.</t>
<figure anchor="get-async" title="An asynchronous GET transaction"><artwork><![CDATA[
Client Server
| |
| CON tid=48 |
| GET http://n.. |
+---------------->|
| |
| ACK tid=48 |
|<----------------+
| |
... Time Passes ...
| |
| CON tid=783 |
| 200 http://n.. |
| "<html.. |
|<----------------+
| |
| ACK tid=783 |
+---------------->|
| |
]]></artwork></figure>
<t>When the server finally has obtained the resource representation and
is ready to send the response, it initiates a transaction to the
client. This new transaction has its own transaction ID, so there is
no automatic coupling of the response to the request. Instead, the
URI (and possibly token) is echoed back to the client in order to
associate the response to the original request.
To ensure that this message is not lost, it is again sent as a
confirmable message and answered by the client with an ACK, citing the
new TID chosen by the server.</t>
<t>As a special failure situation, a client may no longer be aware that
it sent a request, e.g., if it does not have stable storage and was
rebooted in the meantime. This can be indicated by a special "Reset"
message, as shown in <xref target="get-orphaned"/>.</t>
<figure anchor="get-orphaned" title="An orphaned transaction"><artwork><![CDATA[
Client Server
... Client reboots ...
| |
| CON tid=783 |
| 200 http://n.. |
| "<html.. |
|<----------------+
| |
| RST tid=783 |
+---------------->|
| |
]]></artwork></figure>
</section>
</section>
<section anchor='transactions' title="Transaction messages">
<t>The CoAP transactions make use of four different message types, described in this section. These messages are transparent to the request/response carried over them.</t>
<section anchor='confirmable' title="Confirmable (CON)">
<t>
Some messages require an acknowledgment, either just to know they did
arrive or also to deliver the reply to a request. We call these
messages "Confirmable". When no packets are lost, each Confirmable
message elicits exactly one return message of type Acknowledgment or
type Reset.
</t>
</section>
<section anchor='non-confirmable' title="Non-Confirmable (NON)">
<t>
Some other messages do not require an acknowledgment. This is
particularly true for messages that are repeated regularly for
application requirements, such as repeated readings from a sensor
where eventual arrival is sufficient.
</t>
</section>
<section anchor='acknowledgment' title="Acknowledgment (ACK)">
<t>
An Acknowledgment message acknowledges that a specific Confirmable
message (identified by its Transaction ID) arrived. As with all of
the message types itself, it may carry a payload and some options to
provide more details, such as the result of a request that was carried
in the Confirmable.
</t>
</section>
<section anchor='reset' title="Reset (RST)">
<t>
A Reset message indicates that a specific Confirmable message 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.
</t>
</section>
<section anchor='transactionid' title="Transaction IDs">
<t>
The Transaction ID is an unsigned integer kept by a CoAP end-point for all of the CoAP Confirmable or Non-Confirmable messages it sends. Each CoAP end-point keeps a single Transaction ID variable, which is changed each time a new Confirmable or Non-Confirmable message is sent regardless of the destination address or port. The Transaction ID is used to match an Acknowledgment with an outstanding request, for retransmission and to discard duplicate messages. The initial Transaction ID should be randomized. The same Transaction ID MUST NOT be re-used within the potential retransmission window, calculated as RESPONSE_TIMEOUT * (2 ^ MAX_RETRANSMIT - 1).
</t>
<!-- TODO: This specification does not work for a large client interacting with thousands of servers. (Carsten) -->
</section>
</section>
<section anchor='methods' title="Methods">
<t>
CoAP supports the basic methods of GET, POST, PUT, DELETE, which are easily mapped to HTTP. In this section each method is defined along with its behavior. A unicast request with an unknown or unsupported Method Code MUST generate a message with a "405 Method Not Allowed" Response Code.
</t>
<t>
As CoAP methods manipulate resources, they have the same properties of safe (only retrieval) and idempotent (you can invoke it multiple times with the same effects) as HTTP <xref target="RFC2616">Section 9.1</xref>. 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. Unlike PUT, POST is not idempotent because the URI in the request indicates the resource that will handle the enclosed body. This resource indicated by the POST may be used for data processing, a gateway to other protocols and it may create a new resource as a result of the POST.
</t>
<section anchor='read' title="GET">
<t>
The GET method retrieves the information of the resource identified by the request URI. Upon success a 200 (OK) response SHOULD be sent.
</t>
<t>
The response to a GET is cacheable if it meets the requirements in <xref target="caching"/>.
</t>
</section>
<section anchor='create' title="POST">
<t>
The POST method is used to request the server to create a new resource under the requested URI. If a resource has been created on the server, the response SHOULD be 201 (Created) including the URI of the new resource in a Location Option with any possible status in the message body. If the POST succeeds but does not result in a new resource being created on the server, a 200 (OK) response code SHOULD be returned.
</t>
<t>
Responses to this method are not cacheable.
</t>
</section>
<section anchor='update' title="PUT">
<t>
The PUT method requests that the resource identified by the request URI be updated or created with the enclosed message body. If a resource exists at that URI the message body SHOULD be considered a modified version of that resource, and a 200 (OK) response SHOULD be returned. If no resource exists then the server MAY create a new resource with that URI, resulting in a 201 (Created) response. If the resource could not be created or modified, then an appropriate error response code SHOULD be sent.
</t>
<t>
Responses to this method are not cacheable.
</t>
</section>
<section anchor='delete' title="DELETE">
<t>
The DELETE method requests that the resource identified by the request URI be deleted. The response 200 (OK) SHOULD be sent on success.
</t>
<t>
Responses to this method are not cacheable.
</t>
</section>
<!-- Carsten: The idempotence then requires that deleting a non-existing resource also returns a 200? -->
</section>
<section title="Response Codes">
<t>
CoAP makes use of a subset of HTTP response codes as defined in <xref target="appendix_codes"/>.
</t>
</section>
<section anchor='opt' title="Options">
<t>
CoAP makes use of compact, extensible Type-Length-Value (TLV) style options. This section explains the processing of CoAP options along with a summary of the main features implemented in options such as URIs and Content-types.
</t>
<section anchor='opt-proc' title="Option Processing">
<t>
If no options are to be included, the Option Count field is set to 0 below and the Payload (if any) immediately follows the Transaction ID. If options are to be included, the following rules apply. The number of options is placed in the Option Count field. Each option is then placed in order of Type, immediately following the Transaction ID with no padding. Upon reception, unknown options of class "elective" MUST be silently skipped. Unknown options of class "critical" in a Confirmable SHOULD cause the return of a response code "400 Bad Request" (TBD) including a copy of the critical option number in the payload of the response.
</t>
</section>
<section anchor='uri' title="URIs">
<t>
The Universal Resource Identifier (URI) <xref target="RFC3986"/> is an important feature of the web architecture, where the relative part of the URI indicates the resource being manipulated. CoAP supports URIs similarly to HTTP, e.g. coap://[2001:DB8::101]/s/temp. As this URI is used purely as a locator, CoAP only supports Universal Resource Locator features of <xref target="RFC3986"/> although throughout the document we refer to URI.
</t>
<t>
CoAP splits the URI up into its three parts with the default coap:// scheme, Uri-Authority and Uri-Path Options. The full URI can be created by concatenating those parts (or their defaults if not present). CoAP does not support "." or ".." in URIs nor does it support IRIs. A CoAP implementation SHOULD support query "?" processing, however fragment "#" processing is not supported. All URI strings in CoAP MUST use the US-ASCII encoding defined in <xref target="RFC3986"/>. When using the Uri-Path Option the leading slash MUST be omitted. Thus the above example "/s/temp" is included in the Uri-Path Option as "s/temp".
</t>
<t>
The authority part of a URI is important in determining the correct representation to return on end-points maintaining virtual servers and for intermediate components such as proxies. For this reason it is important that the full URI can be reconstructed when needed. However, at the same time, it is often advantageous for CoAP to elide the Uri-Authority when it is unknown or identical to the IPv6 destination address for efficiency. The following rules apply to processing a CoAP request:
<list style="numbers">
<t>If the Uri-Authority option is absent and the remainder of the URI uniquely identifies a resource the server MAY proceed to execute the request.</t>
<t>If an origin server is able to determine the IP destination address of the request, it MAY assume this as the authority of the URI.</t>
<t>If no authority can be determined and the server requires the authority to identify the resource it MUST reject the request with "400 Bad Request" (TBD: 400 is already overloaded, thus a new response code may be created for this purpose).</t>
</list>
</t>
<t>
Application designers are encouraged to make use of short, but descriptive URIs. For example URIs 14 or less bytes in length fit in a more compact option header. In addition, very short URIs such as "/1" can be assigned as an alternative short URI for a resource by the application. The CoRE Link Format includes an attribute to indicate if a short alternative URI of a resource is available (REF).
</t>
<t>
The CoAP protocol scheme is identified in URIs with "coap://" [IANA_TBD_SCHEME].
</t>
</section>
<section anchor='content-type' title="Content-type encoding">
<t>
In order to support heterogeneous uses, CoAP is transparent to the use of different application payloads. In order for the application process receiving a packet to properly parse a payload, its content-type should be explicitly known from the header (as e.g. with HTTP). The use of typical binary encodings for XML is discussed in <xref target="I-D.shelby-6lowapp-encoding"/>.
</t>
<t>
String names of Internet media types (MIME types) <xref target="RFC2046"/> are not optimal for use in the CoAP header. Instead, CoAP simply assigns identifiers to a subset of common media and content transfer encoding types. The content-type identifier is optionally included in the Content-type Option Header of messages to indicate the type of the message body. CoAP Content-type identifiers are defined in <xref target="appendix_content"/>. In the absence of the Content-type Option the MIME type "text/plain" MUST BE assumed.
</t>
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='messages' title="Message Formats">
<t>
CoAP makes use of asynchronous transactions using a simple binary header format. This base header may be followed by options in Type-Length-Value (TLV) format. CoAP is bound to UDP as described in <xref target="binding"/>.
</t>
<t>
Any bytes after the headers in the packet are considered the message payload, if any. The length of the message payload is implied by the datagram length. See <xref target="binding"/> for further message length requirements.
</t>
<section anchor='base' title="CoAP header">
<t>
This section defines the CoAP header, which is shared for all CoAP messages. CoAP makes use of an asynchronous transaction model. These transactions are used to carry request/response exchanges, either using a Method Code (GET/PUT/POST/DELETE) to invoke interaction with a resource, or a Response Code carried in an immediate or asynchronous response.
</t>
<figure anchor='fig-req' title="CoAP header format">
<artwork>
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 | OC | Code | Transaction ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
</figure>
<t>
<list style="hanging">
<t hangText="Header Fields:">
<list style="hanging">
<t hangText="Ver:">
Version. 2-bit unsigned integer. Indicates the version of CoAP. Implementations of this specification MUST set this field to 1. Other values are reserved for future versions.
</t>
<t hangText="T:">
2-bit unsigned integer Transaction Type field. Indicates if this message is Confirmable (0), Non-Confirmable (1), Acknowledgment (2) or Reset (3).
</t>
<t hangText="OC:">
4-bit unsigned integer Option Count field. Indicates if there are Option Headers following the base header. If set to 0 the payload (if any) immediately follows the base header. If greater than zero the field indicates the number of options to immediately follow the header.
</t>
<t hangText="Code:">
8-bit unsigned integer. This field indicates the Method or Response Code of a message. The value 0 indicates no code. The values 1-10 are used for Method Codes as defined in <xref target="tab-method"/>. The values 11-39 are reserved for future use. The values 40-255 are used for Response Codes as defined in <xref target="appendix_codes"/>.
</t>
<t hangText="Transaction ID:">
16-bit unsigned integer. A unique Transaction ID assigned by the source and used to match responses. The Transaction ID MUST be changed for each new request (regardless of the end-point) and MUST NOT be changed when retransmitting a request (see <xref target="transactionid"/>).
</t>
</list>
</t>
</list>
</t>
<texttable anchor='tab-method' title="Method Codes">
<ttcol align='left'>Method</ttcol>
<ttcol align='left'>Code</ttcol>
<c>GET</c>
<c>1</c>
<c>POST</c>
<c>2</c>
<c>PUT</c>
<c>3</c>
<c>DELETE</c>
<c>4</c>
</texttable>
</section>
<section anchor='options' title="Header options">
<t>
CoAP messages may also include one or more header options in TLV format. Options MUST appear in order of option type (see <xref target="tab-options"/>). A delta encoding is used between each option header, with the Type identifier for each Option calculated as the sum of its Option Delta field and the Type identifier of the preceding Option in the message, if any, or zero otherwise.
</t>
<t>Each option header includes a Length field which can be extended by an octet for options with values longer than 14 octets. CoAP options include the concept of Critical (odd value) and Elective (even value) options (see <xref target="opt-proc"/>).
</t>
<t>
Each option has the following format:
</t>
<figure anchor='fig-opt' title="Header option format">
<artwork>
0 1 2 3 4 5 6 7
+---+---+---+---+---+---+---+---+
| option delta | length | for 0..14
+---+---+---+---+---+---+---+---+
for 15..270:
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| option delta | 1 1 1 1 | length - 15 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
</artwork>
</figure>
<t hangText="Option Fields:">
<list style="hanging">
<t hangText="Option delta:">
4-bit unsigned integer. This field defines the difference between the option Type of this option and the previous option (or zero for the first option). In other words, the Type identifier is calculated by simply summing the Option delta fields of this and previous options before it. The Option Values 14, 28, ... are reserved for no-op options with no value (they are ignored) and are used for deltas larger than 14. Thus these can be used as "fenceposts" if deltas larger than 15 would otherwise be required.
</t>
<t hangText="Length:">
Length Field. Normally Length is a 4-bit unsigned integer allowing values of 0-14 octets. When the length is 15 or more, another byte is added as an 8-bit unsigned integer plus 15 allowing values of 15-270 octets.
</t>
<t hangText="Option Value">
The value in the format defined for that option in <xref target="tab-options"/> of Length octets. Options MAY use variable length values.
</t>
</list>
</t>
<t>
The following options are defined in this document. The Default column indicates the value to be assumed in the absence of this option (if any).
</t>
<texttable anchor='tab-options' title="Option headers">
<ttcol align='left'>Type</ttcol>
<ttcol align='left'>C/E</ttcol>
<ttcol align='left'>Name</ttcol>
<ttcol align='left'>Data type</ttcol>
<ttcol align='left'>Length</ttcol>
<ttcol align='left'>Default</ttcol>
<c>0</c>
<c>-</c>
<c>Reserved</c>
<c>-</c>
<c>-</c>
<c>-</c>
<c>1</c>
<c>C</c>
<c>Content-type</c>
<c>8-bit unsigned integer</c>
<c>1 B</c>
<c>0 (text/plain)</c>
<c>2</c>
<c>E</c>
<c>Max-age</c>
<c>Variable length unsigned integer</c>
<c>1-4 B</c>
<c>60 seconds</c>
<c>3</c>
<c>C</c>
<c>-</c>
<c>Reserved</c>
<c>-</c>
<c>-</c>
<c>4</c>
<c>E</c>
<c>Etag</c>
<c>Sequence of bytes</c>
<c>1-4 B</c>
<c>-</c>
<c>5</c>
<c>C</c>
<c>Uri-Authority</c>
<c>String</c>
<c>1-270 B</c>
<c>""</c>
<c>6</c>
<c>E</c>
<c>Location</c>
<c>String</c>
<c>1-270 B</c>
<c>-</c>
<c>7</c>
<c>-</c>
<c>Reserved</c>
<c>-</c>
<c>-</c>
<c>-</c>
<c>9</c>
<c>C</c>
<c>Uri-Path</c>
<c>String</c>
<c>1-270 B</c>
<c>""</c>
</texttable>
<section anchor='option-content' title="Content-type Option">
<t>The Content-type Identifier Option indicates the Internet media type identifier of the message-body, see <xref target="appendix_content"/> for the encoding and identifier tables. A Content-type Identifier Option SHOULD be included if there is a payload included with a CoAP message. In the absence of the Content-type Option the MIME type "text/plain" (0) MUST be assumed. This option MUST be supported by all end-points. This option MUST NOT occur more than once in a header.</t>
<!-- TODO: Consider if this can also be used as a kind of Accept, or will a special Accept option be included in the future? -->
</section>
<!--
<section anchor='option-uri-scheme' title="Uri-Scheme Option">
<t>The Uri-Scheme Option indicates the schema part of the URI without any ":" or "://" glue. This option is most often used to access a resource via a proxy. For example, to access an HTTP resource via a proxy the option value would be "http". In the absence of this option, the URI scheme is assumed to be "coap". <xref target="uri"/> specifies the rules for URIs in CoAP. This option MUST be supported by an end-point implementing proxy functionality.</t>
</section>
-->
<section anchor='option-uri-auth' title="Uri-Authority Option">
<t>The Uri-Authority Option indicates the authority (host + port) part of a URI. Examples of this option include "[2001:DB8::101]", "198.51.100.0:8000" and "sensor.example.com". This option is used by servers to determine which resource to return and by intermediate components, e.g. when accessing a resource via a proxy. <xref target="uri"/> specifies the rules for URIs in CoAP. This option SHOULD be included in a request when the authority of the URI is known. This option MUST be supported by an end-point implementing proxy functionality. This option MUST NOT occur more than once in a header.</t>
</section>
<section anchor='option-uri-path' title="Uri-Path Option">
<t>The Uri-Path Option indicates the absolute path part of a URI. One example of an absolute path in his option is "s/light". In the absence of this option, the path is assumed to be "/". <xref target="uri"/> specifies the rules for URIs in CoAP. The leading slash is assumed and MUST be omitted. This option MUST be supported by all end-points. This option MUST NOT occur more than once in a header. </t>
</section>
<section anchor='option-location' title="Location Option">
<t>The Location Option indicates the location of a resource as an absolute path URI and is similar to the Uri-Path Option. The Location Option MAY be included in a response to indicate the Location of a new resource created with POST or together with a 30x response code. The leading slash is assumed and MUST be omitted. This option MUST NOT occur more than once in a header. </t>
</section>
<section anchor='option-max-age' title="Max-age Option">
<t>The Max-age Option indicates the maximum age of the resource for use in cache control in seconds. The option value is represented as a variable length unsigned integer between 8 and 32 bits. A default value of 60 seconds is assumed in the absence of this option.
</t>
<t>
When included in a request, Max-age indicates the maximum age of a cached representation of that resource the client will accept. When included in a response, Max-age indicates the maximum time the representation may be cached before it MUST be discarded. This option MUST NOT occur more than once in a header.
</t>
</section>
<section anchor='option-etag' title="Etag Option">
<t>The Etag Option is an opaque sequence of bytes which specifies the version of a resource representation. An Etag may be generated for a resource in any number of ways including a version, checksum, hash or time. An end-point receiving an Etag MUST treat it as opaque and make no assumptions about its format. The Etag MAY be included in a response to indicate to a client if a resource has changed. The Etag SHOULD be included in a request used for a cache refresh to indicate the client's current version of the resource (see <xref target="cache-refreshing"/>). </t>
<!-- Zach: Can multiple Etags be included in a message, and what does that mean? -->
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='binding' title="UDP Binding">
<t>
The CoAP protocol operates by default over UDP. CoAP may also be used with Datagram Transport Layer Security (DTLS) as described in <xref target="security"/>. CoAP could also be used over other transports such as TCP or SCTP, the specification of which is out of this document's scope.
</t>
<t>
The goal of binding CoAP to UDP is to provide the bare minimum features for the protocol to operate over UDP, without trying to re-create the full feature set of a transport like TCP. CoAP over UDP has the following features:
</t>
<t>
<list style="symbols">
<t>Simple stop-and-wait retransmission reliability with exponential back-off as described in <xref target="retransmission"/> for Confirmable messages.</t>
<t>Transaction ID for response matching as described in <xref target="transactionid"/>.</t>
<t>Multicast support as described in <xref target="multicast"/>. </t>
</list>
</t>
<t>
The length of the Payload in a CoAP message is calculated from the datagram length. While specific link layers make it beneficial to keep CoAP messages small enough to fit into their link layer packets (see <xref target="introduction"/>), this is a matter of implementation quality. The CoAP specification itself provides only an upper bound to the message size. A CoAP message SHOULD fit within a single IP packet and MUST fit within a single IP datagram. If the Path MTU is not known for a destination, an MTU of 1280 octets SHOULD be assumed.
</t>
<section anchor='multicast' title="Multicast">
<t>
CoAP supports the use of multicast destination addresses. Multicast messages SHOULD be Non-Confirmable. If a Confirmable multicast message is sent then retransmission MUST NOT be performed. Furthermore, a destination end-point to a multicast Confirmable message MUST only send an Acknowledgment if the response code included indicates success (Code = 2XX) in order to eliminate error code response floods. Other mechanisms for avoiding congestion from multicast requests are being considered in <xref target="I-D.eggert-core-congestion-control"/>.
</t>
<!-- TODO: Dithering on CON responses also needed along with rate control. Consider in core-congestion-control... -->
</section>
<section anchor='retransmission' title="Retransmission">
<t>
A CoAP end-point keeps track of open Confirmable messages it sent that are waiting for a response. Each entry includes at least the destination IP address and port of the original message, the message itself, a retransmission counter and a timeout. When a Confirmable is sent, an entry is made for that message with a default initial timeout of RESPONSE_TIMEOUT and the retransmission counter set to 0. When a matching Acknowledgment is received for an entry, the entry is invalidated. When a timeout is triggered for an entry and the retransmission counter is less than MAX_RETRANSMIT, the original message is retransmitted to the destination without modification, the retransmission counter is incremented, and the timeout is doubled. If the retransmission counter reaches MAX_RETRANSMIT on a timeout, then the entry is removed and the application process informed of delivery failure.
</t>
<t>
For CoAP messages sent to IP multicast addresses, retransmission MUST NOT be performed. Therefore MAX_RETRANSMIT is always set to 0 when the destination address is multicast.
</t>
</section>
<section anchor='congenstion' title="Congestion Control">
<t>
In addition to the exponential back-off mechanism in <xref target="retransmission"/>, further congestion control optimizations are being considered and tested for CoAP. These congestion control mechanism under consideration are described in <xref target="I-D.eggert-core-congestion-control"/>.
</t>
</section>
<section anchor='port' title="Default Port">
<t>
The CoAP default port number [IANA_TBD_PORT] MUST be supported by a server for resource discovery (see <xref target="discovery"/>) and SHOULD be supported for providing access to other resources. In addition other end-points may be hosted in the dynamic port space.
</t>
<t>
When a CoAP server is hosted by a 6LoWPAN node, it SHOULD support a port in the 61616-61631 compressed UDP port space defined in <xref target="RFC4944"/>. The specific port number in use will be communicated in a URI and/or by some other discovery mechanism.
</t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='caching' title="Caching">
<t>
CoAP end-points are by definition constrained by bandwidth and processing power. To optimize the performance of data transfer under these constraints, we use caching features consistent with HTTP. Caching includes the following concepts:
<list style="symbols">
<t>Cache life of a resource is controlled via the Max-Age header option</t>
<t>Cache refresh and versioning of a resource is controlled via the Etag header option</t>
<t>Proxies between a client and end-point may participate in the caching process on behalf of sleeping end-points and to avoid unnecessary traffic on the constrained network</t>
</list>
</t>
<section anchor='cache-control' title="Cache control">
<t>
When an end-point responds to a GET request by sending a representation of the resource, it SHOULD specify the Max-Age header option. The Max-Age specifies the cache life of the resource in seconds. Resources which change rapidly will have a short cache life, and resources which change infrequently should specify a long cache life. If Max-Age is unspecified in a GET response, then it is assumed to be 60 seconds. If an end-point wishes to disable caching, it must explicitly specify a Max-Age of zero seconds.
</t>
<t>
When a client reads the response from a GET request, it should cache the resource representation for the cache lifetime as specified by the Max-Age header. During the cache lifetime, the client SHOULD use its cached version and avoid performing additional GETs for the resource.
</t>
<t>
In general, the origin server end-point is responsible for determining cache age. However, in some cases a client may wish to determine its own tolerance for cache staleness. In this case, a client may specify the Max-Age header during a GET request. If the client's Max-Age is of a shorter duration than the age of a cached resource, then the proxy or end-point SHOULD perform a cache refresh. If the client specifies a Max-Age of zero seconds, then the response MUST discard the cached representation and return a fresh representation.
</t>
</section>
<section anchor='cache-refreshing' title="Cache refresh">
<t>
After the expiration of the cache lifetime, clients and proxies can refresh their cached representation of a resource. Cache refresh is accomplished using a GET request which will return a representation of the resource's current state.
</t>
<t>
If the end-point has the capability to version the resource, then the end-point should include the Etag header option in the response to a GET request. The Etag is a variable length sequence of bytes which captures a version identifier of the resource. The Etag is an opaque identifier; clients MUST NOT infer any semantics from the Etag value.
</t>
<t>
If an end-point specifies the Etag header option with a response, then the client SHOULD specify a matching Etag header option in their GET request during cache refresh. If the end-point's version of the resource is unmodified, then the server SHOULD return a 304 response with no payload to avoid retransmitting the resource representation.
</t>
<!-- TODO: This does not discuss supplying multiple Etags. -->
</section>
<section anchor='proxying' title="Proxying">
<t>
A proxy is defined as a CoAP end-point which services cached requests on behalf of other CoAP end-points. Any node in a CoAP network may act as a proxy, although in general the node between the constrained network and the Internet at large SHOULD always support proxy functionality.
</t>
<t>
Proxies should be used under the following scenarios:
<list style="symbols">
<t>Clients external to the constrained network SHOULD always make requests through a proxy to limit traffic on the constrained network</t>
<t>Clients internal to the constrained network MAY use a proxy based on network topology when performance warrants</t>
<t>Clients of sleeping devices MUST use a proxy to access resources while the device is sleeping</t>
<!-- Carsten: How do they find out?
We would need a "coapsleeper" scheme or some such.
(And how do they find the right proxy? Which might change...) -->
</list>
</t>
<t>
Proxy requests are made as normal CON requests to the proxy end-point. All proxy requests MUST use the Uri-Authority header to indicate the origin server's IP address using the URI format defined by RFC 3986:
</t>
<figure>
<artwork><![CDATA[
full uri = "coap://" + authority + path
authority = host [ ":" port ]
host = IP-literal / IPv4address / reg-name
(as defined by RFC 3986)
port = *DIGIT
]]></artwork>
</figure>
<t>
The host part is case insensitive and may be an IPv4 literal, IPv6 literal in square brackets, or a registered name. The port number is optional, if omitted or zero-length it is assumed to be the default CoAP port (see <xref target="port"/>).
</t>
<t>When a request is made to a proxy, then the following steps are taken:
<list>
<t>1. If the authority (host and port) is recognized as identifying the proxy end-point, then the request MUST be treated as a local request and the path part is used as Uri-Path</t>
<t>2. If the proxy does not contain a fresh cached representation of the resource, then the proxy MUST attempt to refresh its cache according to section 5.2. The origin server's IP address and port is determined by the authority part of the full URI. The Uri-Path option for the refresh request is determined by the path part of the full URI.</t>
<t>3. If the proxy fails to obtain a fresh cached representation, then a 502 Bad Gateway error code MUST be returned</t>
<t>4. The proxy returns the cached representation on behalf of the origin server</t>
</list>
</t>
<t>
All CoAP options are considered end-to-end and MUST be stored as part of the cache entry and MUST be transmitted in the proxy's response. The Max-Age option should be adjusted by the proxy for each response using the formula: <![CDATA[proxy-max-age = original-max-age - cache-age]]>. For example if a request is made to a proxied resource that was refreshed 20sec ago and had an original Max-Age of 60sec, then that resource's proxied Max-Age is now 40sec.
</t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='discovery' title="Resource Discovery">
<t>
The discovery of resources offered by a CoAP end-point is extremely important in machine-to-machine applications where there are no humans in the loop and static interfaces result in fragility. A CoAP end-point SHOULD support the CoRE Link Format of discoverable resources as described in (REF).
</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='http' title="HTTP Mapping">
<t>
CoAP supports a limited subset of HTTP functionality, and thus a mapping to HTTP is straightforward. There might be several reasons for mapping between CoAP and HTTP, for example when designing a web interface for use over either protocol or when realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be mapped to other protocols such as XMPP or SIP, the definition of which is out of scope.
</t>
<t>
The mapping of CoAP to HTTP is a straightforward conversion of the CoAP method or response code, content-type and options to the corresponding HTTP feature. The payload is carried in an equivalent way by both protocols. The mapping of HTTP to CoAP requires checking for methods, response codes, options and content-types that are not supported by CoAP. A mapping SHOULD attempt to map options, response codes and content-types to a suitable alternative if possible. Otherwise the unsupported feature SHOULD be silently dropped if possible, or an appropriate error code generated otherwise.
</t>
<t>
The caching and proxying of CoAP is specified in <xref target="caching"/>. In a similar manner, caching and proxying MAY be performed between CoAP and HTTP by an intermediate node. A proxy SHOULD respond with a 502 (Bad Gateway) error to HTTP requests which can not be successfully mapped to CoAP. CoAP transaction messages are transparent to request/response exchanges and MUST have no affect on a proxy function.
</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='constants' title="Protocol Constants">
<t>
This section defines the relevant protocol constants defined in this document:
<list style="hanging" hangIndent="40">
<t hangText="RESPONSE_TIMEOUT">1 second</t>
<t hangText="MAX_RETRANSMIT">5</t>
</list>
</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='examples' title="Examples">
<t>
<xref target="fig-example-1"/> shows a basic request sequence. A client makes a Confirmable GET request for the resource /temperature to the server with a Transaction ID of 1234. The request includes one Uri-Path Option (delta 0 + 9 = 9) "temperature" of Len = 11. This request is a total of 16 octets long. The corresponding Acknowledgment is of Code 200 OK and includes a Payload of "22.3 C". The Transaction ID is 1234, thus the transaction is successfully completed. The response is 10 octets long and a Content-type of 0 (text/plain) is assumed as there is no Content-type Option.
</t>
<figure anchor='fig-example-1'
title="Basic request/response">
<artwork><![CDATA[
CLIENT SERVER
| |
| ----- CON + GET /temperature [TID=1234] ------> |
| |
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 | 0 | 1 | GET = 1 | TID=1234 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 9 | 11 | "temperature" (11 Octets) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
CLIENT SERVER
| |
| <-------- ACK + 200 OK [TID=1234] --------- |
| |
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 1 | 2 | 0 | Code=80 | TID=1234 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| "22.3 C" (6 Octets) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>
<xref target="fig-example-2"/> shows an example of a retransmission using the previous request. The first ACK from the server is lost, and after RESPONSE_TIMEOUT seconds the client retransmits the request.
</t>
<figure anchor='fig-example-2'
title="Basic request/response">
<artwork><![CDATA[
CLIENT SERVER
| |
| ----- CON + GET /temperature [TID=1234] ------> |
| |
| X------------------------ |
| |
RESPONSE_TIMEOUT
| |
| ----- CON + GET /temperature [TID=1234] ------> |
| |
| |
| <-------- ACK + 200 OK [TID=1234] --------- |
Payload:
22.3 C
]]></artwork>
</figure>
<t>
<xref target="fig-example-3"/> shows an example of resource discovery. Here a unicast GET request is made to the server for /.well-known/core, which returns a list of two resource descriptions. The client then decides to make a request for the short URI of /sensor/light (/l). Requesting /sensors/light would result in the same representation.
</t>
<figure anchor='fig-example-3'
title="Basic request/response">
<artwork><![CDATA[
CLIENT SERVER
| |
| ----- CON + GET /.well-known/core [TID=5068] -----> |
| |
| <----- ACK + 200 OK [TID=5068, CT=40] ------ |
Payload:
</sensor/temp>;sh="/t";ct=0,41;n="Temperature",
</sensor/light>;sh="/l";ct=41;n="Light"
| |
| ----- CON + GET /l [TID=5069] ------> |
| |
| <---- ACK + 200 OK [TID=5069, CT=41] ----- |
Payload:
<?xml?><Light unit="Lux">45</Light>
]]></artwork>
</figure>
<t>
<xref target="fig-example-4"/> shows an example of a multicast request. Here a client sends a request for /.well-known/core with a query for ?n=Light (Resource name = Light) to all-nodes link-scope multicast. There are 3 servers on the link: A, B and C. Servers A and B have a matching resource, therefore they send back a successful 200 OK response with the matching resource in the payload. C does not attempt to send a response.</t>
<figure anchor='fig-example-4'
title="Basic request/response">
<artwork><![CDATA[
CLIENT FF02::1
| |
| -- CON + GET /.well-known/core?n=Light [TID=7000] --> |
| |
| <----- ACK + 200 OK [TID=7000, CT=40] ------ SERVER A
Payload:
</sensor/light>;sh="/l";ct=41;n="Light"
| |
| <----- ACK + 200 OK [TID=7000, CT=40] ------ SERVER B
Payload:
</light>;ct=41;n="Light"
]]></artwork>
</figure>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor='security' title="Security Considerations">
<t>This section describes mechanisms that can be used to secure CoAP and analyzes the possible threats to the protocol and its limitations. Security bootstrapping (setting up keys) in constrained environments is considered in <xref target="I-D.oflynn-core-bootstrapping"/>.
</t>
<section title="Securing CoAP with IPSec">
<t>One mechanism to secure CoAP in constrained environments is the IPsec Encapsulating Security Payload (ESP) <xref target="RFC2406"/>. Using IPsec ESP with the appropriate configuration it is possible for many constrained devices to support encryption with built-in link-layer encryption hardware, for example most IEEE 802.15.4 radio chips are compatible with AES-CBC (with 128-bit keys) <xref target="RFC3602"/> as defined for use with IPsec in <xref target="RFC4835"/>. When using IPsec to secure CoAP, both authentication and confidentiality SHOULD be applied as recommended in <xref target="RFC2406"/>. The use of IPsec between CoAP end-points is transparent to the application layer and does not require special consideration for a CoAP implementation.
</t>
<t>
IPsec may not be appropriate for all environments. For example, IPsec support is not available for many embedded IP stacks and even in full PC operating systems or on backend web servers, application developers may not have sufficient access to configure or enable IPsec or to add a security gateway to the infrastructure. Problems with firewalls and NATs may furthermore limit the use of IPsec.
</t>
</section>
<section title="Securing CoAP with DTLS">
<t>Just as HTTP may be secured using Transport Layer Security (TLS) over TCP, CoAP may be secured using Datagram TLS (DTLS) <xref target="RFC4347"/> over UDP. This section describes how to secure CoAP with DTLS , along with the minimal configurations appropriate for constrained environments. DTLS is in practice TLS with added features to deal with the unreliable nature of the UDP transport. </t>
<t>
In some constrained nodes (limited flash and/or RAM) and networks (limited bandwidth or high scalability requirements) DTLS may not be applicable. The protocol is an order of magnitude more complex than CoAP and has appreciable handshake overhead needed to maintain security sessions. DTLS makes sense for applications where the session maintenance makes is compatible with application flows and sufficient resources are available on the constrained nodes and for the added network overhead.
</t>
<t>
As with IPSec, DTLS should be configured with a cypher suite compatible with any possible hardware engine on the node, for example AES-CBC in the case of IEEE 802.15.4. Implementations MUST support the mandatory to implement cipher suite TLS_RSA_WITH_AES_128_CBC_SHA as specified in <xref target="RFC5246"/>.
</t>
</section>
<section title="Threat analysis and protocol limitations">
<t>
This section is meant to inform protocol and application developers about the security limitations of CoAP as described in this document. As CoAP realizes a subset of the features in HTTP/1.1, the security considerations in Section 15 of <xref target="RFC2616"/> are also pertinent to CoAP. This section concentrates on describing limitations specific to CoAP and CoRE.
</t>
<section title="Processing URIs">
<t>TODO</t>
</section>
<section title="Proxying and Caching">
<t>TODO</t>
</section>
<section title="Attacks on TIDs">
<t>TODO</t>
</section>
<section title="Risk of amplification using multicast">
<t>TODO</t>
</section>
<section title="Asynchronous responses">
<t>TODO</t>
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="IANA Considerations">
<t>
[IANA_TBD_SCHEME] This document suggests the scheme coap:// to identify this protocol in a URI. The string "coap" should similarly be used in well-known port and service discovery registrations.
</t>
<t>
[IANA_TBD_PORT] Apply for a well-known port number in the 0-1023 space as CoAP end-points are usually executed by an operating system or root process. http://www.iana.org/assignments/port-numbers
</t>
<t>
[IANA_TBD_MIME] A new registry is required for the Internet MIME type identifier space for CoAP as described in <xref target="appendix_content"/>.
</t>
<section anchor="appendix_codes" title="Codes">
<t>
CoAP makes use of (a subset of) the HTTP status codes defined in <xref target="RFC2616"/>. The HTTP status code is encoded into an 8-bit unsigned integer code with the mapping defined in <xref target="tab-codes"/>. The use of these codes is defined throughout this document using the HTTP Name.
</t>
<texttable anchor='tab-codes' title="CoAP Codes">
<ttcol align='left'>Code</ttcol>
<ttcol align='left'>HTTP Name</ttcol>
<!-- Continue 40-79 -->
<c>40</c><c>100 Continue</c>
<!-- Success 80-119 -->
<c>80</c><c>200 OK</c>
<c>81</c><c>201 Created</c>
<!-- Redirection 120-159 -->
<c>124</c><c>304 Not Modified</c>
<!-- Error Codes 160-199 -->
<c>160</c><c>400 Bad Request</c>
<!-- <c>161</c><c>401 Unauthorized</c> -->
<!-- <c>163</c><c>403 Forbidden</c> -->
<c>164</c><c>404 Not Found</c>
<c>165</c><c>405 Method Not Allowed</c>
<!-- <c>169</c><c>409 Conflict</c> -->
<c>175</c><c>415 Unsupported Media Type</c>
<c></c><c></c>
<!-- Server Error 200-239 -->
<c>200</c><c>500 Internal Server Error</c>
<c>202</c><c>502 Bad Gateway</c>
<c>203</c><c>503 Service Unavailable</c>
<c>204</c><c>504 Gateway Timeout</c>
<!-- 240-255 for experimentation -->
</texttable>
</section>
<section anchor="appendix_content" title="Content Types">
<t>
Internet media types are identified by a string in HTTP, such as "application/xml". This string is made up of a top-level type "application" and a sub-type "xml" <xref target="RFC2046"/>. In order to minimize the overhead of using these media types to indicate the type of message payload, CoAP defines an identifier encoding scheme for a subset of Internet media types. It is expected that this table of identifiers will be extensible and maintained by IANA for values of 0-200 [IANA_TBD_MIME].
</t>
<t>
The Content-type Option is formatted as an 8-bit unsigned integer. Initial mappings from Internet media types to a suitable identifier is shown in <xref target="tab-mediatype"/>. Composite high-level types (multipart and message) are not supported. Identifier values from 201-255 are reserved for vendor specific, application specific or experimental use and are not maintained by IANA.
</t>
<texttable anchor='tab-mediatype' title="Media type identifiers">
<ttcol align='left'>Internet media type</ttcol>
<ttcol align='left'>Identifier</ttcol>
<!-- text 0-19 -->
<c>text/plain (UTF-8)</c><c>0</c>
<c>text/xml (UTF-8)</c><c>1</c>
<c>text/csv (UTF-8)</c><c>2</c>
<c>text/html (UTF-8)</c><c>3</c>
<!-- image, audio, video 20-39-->
<c>image/gif</c><c>21</c>
<c>image/jpeg</c><c>22</c>
<c>image/png</c><c>23</c>
<c>image/tiff</c><c>24</c>
<c>audio/raw</c><c>25</c>
<c>video/raw</c><c>26</c>
<!-- application 40-200 -->
<c>application/link-format [draft-shelby-core-link-format]</c><c>40</c>
<c>application/xml</c><c>41</c>
<c>application/octet-stream</c><c>42</c>
<c>application/rdf+xml</c><c>43</c>
<c>application/soap+xml</c><c>44</c>
<c>application/atom+xml</c><c>45</c>
<c>application/xmpp+xml</c><c>46</c>
<c>application/exi</c><c>47</c> <!-- http://www.w3.org/TR/2009/CR-exi-20091208/#mediaTypeRegistration -->
<c>application/x-bxml</c><c>48</c>
<c>application/fastinfoset</c><c>49</c>
<c>application/soap+fastinfoset</c><c>50</c>
<c>application/json</c><c>51</c>
</texttable>
</section>
</section>
<!------------------------------------------------------>
<!-- SECTION: ACKNOWLEDGMENTS -->
<!------------------------------------------------------>
<section title="Acknowledgments">
<t>
Special thanks to Carsten Bormann and Klaus Hartke for substantial contributions to the ideas and text in the document (<xref target="synchronous-response"/>, <xref target="asynchronous-response"/>, <xref target="transactions"/>, <xref target="options"/>), along with countless detailed reviews and discussions.
</t>
<t>Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin, Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed Beroset, Gilman Tolle, Robby Simpson, Peter Bigot, Colin O'Flynn and David Ryan for helpful comments and discussions that have shaped the document.</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Changelog">
<t>Changes from ietf-01 to ietf-02:
<list>
<t>o Sending an error on a critical option clarified (#18).</t>
<t>o Clarification on behavior of PUT and idempotent operations (#19).</t>
<t>o Use of Uri-Authority clarified along with server processing rules. Uri-Scheme option removed. (#20, #23) </t>
<t>o Resource discovery section removed to a separate CoRE Link Format draft (#21)</t>
<t>o Initial security section outline added. </t>
</list>
</t>
<t>Changes from ietf-00 to ietf-01:
<list>
<t>o New cleaner transaction message model and header (#5)</t>
<t>o Removed subscription while being designed (#1)</t>
<t>o Section 2 re-written (#3)</t>
<t>o Text added about use of short URIs (#4)</t>
<t>o Improved header option scheme (#5, #14)</t>
<t>o Date option removed whiled being designed (#6)</t>
<t>o New text for CoAP default port (#7)</t>
<t>o Completed proxying section (#8)</t>
<t>o Completed resource discovery section (#9)</t>
<t>o Completed HTTP mapping section (#10)</t>
<t>o Several new examples added (#11)</t>
<t>o URI split into 3 options (#12)</t>
<t>o MIME type defined for link-format (#13, #16)</t>
<t>o New text on maximum message size (#15)</t>
<t>o Location Option added</t>
</list>
</t>
<t>Changes from shelby-01 to ietf-00:
<list>
<t>o Removed the TCP binding section, left open for the future.</t>
<t>o Fixed a bug in the example.</t>
<t>o Marked current Sub/Notify as (Experimental) while under WG discussion.</t>
<t>o Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for CoAP-CoAP proxying to work).</t>
<t>o Temporarily removed the Magic Byte header as TCP is no longer included as a binding. </t>
<t>o Removed the Uri-code Option as different URI encoding schemes are being discussed.</t>
<t>o Changed the rel= field to desc= for resource discovery.</t>
<t>o Changed the maximum message size to 1024 bytes to allow for IP/UDP headers.</t>
<t>o Made the URI slash optimization and method impotence MUSTs </t>
<t>o Minor editing and bug fixing.</t>
</list>
</t>
<t>Changes from shelby-00 to shelby-01:
<list>
<t>o Unified the message header and added a notify message type.</t>
<t>o Renamed methods with HTTP names and removed the NOTIFY method.</t>
<t>o Added a number of options field to the header.</t>
<t>o Combines the Option Type and Length into an 8-bit field.</t>
<t>o Added the magic byte header.</t>
<t>o Added new Etag option.</t>
<t>o Added new Date option.</t>
<t>o Added new Subscription option.</t>
<t>o Completed the HTTP Code - CoAP Code mapping table appendix.</t>
<t>o Completed the Content-type Identifier appendix and tables.</t>
<t>o Added more simplifications for URI support.</t>
<t>o Initial subscription and discovery sections.</t>
<t>o A Flag requirements simplified.</t>
</list>
</t>
</section>
</middle>
<back>
<references title='Normative References'>
&RFC2046;
&RFC2406;
&RFC2616;
&RFC3602;
&RFC3986;
<!-- &RFC4288; -->
<!-- &RFC4346; -->
&RFC4347;
&RFC4835;
&RFC5246;
<!-- &RFC5234; -->
<!-- &RFC5785; -->
<!-- &I-D.nottingham-http-link-header; -->
&I-D.oflynn-core-bootstrapping;
</references>
<references title='Informative References'>
&RFC4944;
&I-D.shelby-6lowapp-encoding;
&I-D.shelby-core-coap-req;
&I-D.eggert-core-congestion-control;
<!-- &I-D.hartke-coap-observe; -->
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 03:37:53 |