One document matched: draft-ietf-core-coap-18.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 RFC0020 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0020.xml">
<!ENTITY RFC0768 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0768.xml">
<!ENTITY RFC0792 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0792.xml">
<!ENTITY RFC0793 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0793.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 RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2560 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2560.xml">
<!ENTITY RFC2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC2818 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2818.xml">
<!ENTITY RFC3023 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3023.xml">
<!ENTITY RFC3264 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3264.xml">
<!ENTITY RFC3542 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3542.xml">
<!ENTITY RFC3629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml">
<!ENTITY RFC3676 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3676.xml">
<!ENTITY RFC3828 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3828.xml">
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC4086 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4086.xml">
<!ENTITY RFC4279 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4279.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 RFC4395 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4395.xml">
<!ENTITY RFC4443 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4443.xml">
<!ENTITY RFC4492 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4492.xml">
<!ENTITY RFC4627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
<!ENTITY RFC4821 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4821.xml">
<!ENTITY RFC4944 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4944.xml">
<!ENTITY RFC5147 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5147.xml">
<!ENTITY RFC5198 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5198.xml">
<!ENTITY RFC5201 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5201.xml">
<!ENTITY RFC5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.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 RFC5280 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5280.xml">
<!ENTITY RFC5389 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5389.xml">
<!ENTITY RFC5405 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5405.xml">
<!ENTITY RFC5480 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5480.xml">
<!ENTITY RFC5489 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5489.xml">
<!ENTITY RFC5785 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5785.xml">
<!ENTITY RFC5952 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5952.xml">
<!ENTITY RFC5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
<!ENTITY RFC6066 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6066.xml">
<!ENTITY RFC6090 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6090.xml">
<!ENTITY RFC6120 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6120.xml">
<!ENTITY RFC6282 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6282.xml">
<!ENTITY RFC6335 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6335.xml">
<!ENTITY RFC6347 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6347.xml">
<!ENTITY RFC6655 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6655.xml">
<!ENTITY RFC6690 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6690.xml">
<!ENTITY RFC6920 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6920.xml">
<!ENTITY RFC6936 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6936.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.gold-6lowapp-sensei.xml">
<!ENTITY I-D.martocci-6lowapp-building-applications SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.martocci-6lowapp-building-applications.xml">
<!ENTITY I-D.sturek-6lowapp-smartenergy SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.sturek-6lowapp-smartenergy.xml">
<!ENTITY I-D.moritz-6lowapp-dpws-enhancements SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.moritz-6lowapp-dpws-enhancements.xml">
<!ENTITY I-D.shelby-core-coap-req SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.shelby-core-coap-req.xml">
<!ENTITY I-D.nottingham-http-link-header SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.nottingham-http-link-header.xml">
<!ENTITY I-D.eggert-core-congestion-control SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.eggert-core-congestion-control.xml">
<!ENTITY I-D.ietf-core-observe SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-observe.xml">
<!ENTITY I-D.ietf-core-block SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-block.xml">
<!ENTITY I-D.ietf-core-groupcomm SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-groupcomm.xml">
<!ENTITY I-D.oflynn-core-bootstrapping SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.oflynn-core-bootstrapping.xml">
<!ENTITY I-D.mcgrew-tls-aes-ccm-ecc SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.mcgrew-tls-aes-ccm-ecc.xml">
<!ENTITY I-D.ietf-lwig-terminology SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-lwig-terminology.xml">
<!ENTITY I-D.ietf-tls-oob-pubkey SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-tls-oob-pubkey.xml">
<!ENTITY I-D.ietf-tls-multiple-cert-status-extension SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-tls-multiple-cert-status-extension.xml">
<!ENTITY I-D.allman-tcpm-rto-consider SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.allman-tcpm-rto-consider.xml">
<!ENTITY I-D.castellani-core-http-mapping SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.castellani-core-http-mapping.xml">
<!ENTITY I-D.bormann-core-ipsec-for-coap SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.bormann-core-ipsec-for-coap.xml">
<!ENTITY I-D.bormann-coap-misc SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.bormann-coap-misc.xml">
<!ENTITY SELF "[RFCXXXX]">
<!ENTITY PORT "5683">
<!ENTITY PORTS "[IANA_TBD_PORT]">
<!ENTITY MULTICASTv4 "[TBD1]">
<!ENTITY MULTICASTv6 "[TBD2]">
<!-- Unfortunately, XML2RFC is broken wrt entity references in
attributes. Search for "stupid" when changing these the next time... -->
<!ENTITY pb "piggy-backed">
<!ENTITY npb "separate">
<!ENTITY Pb "Piggy-backed">
<!ENTITY Npb "Separate">
]>
<?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" docName="draft-ietf-core-coap-18" ipr="trust200902">
<?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 fullname="Zach Shelby" initials="Z." surname="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="K." surname="Hartke" fullname="Klaus Hartke">
<organization>Universitaet Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63905</phone>
<email>hartke@tzi.org</email>
</address>
</author>
<author initials="C." surname="Bormann" fullname="Carsten Bormann">
<organization>Universitaet Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63921</phone>
<email>cabo@tzi.org</email>
</address>
</author>
<date year="2013" />
<area>Applications</area>
<workgroup>CoRE Working Group</workgroup>
<keyword>CoAP</keyword>
<keyword>Constrained Application Protocol</keyword>
<keyword>REST</keyword>
<abstract>
<t>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
6LoWPAN 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.</t>
<t>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.</t>
</abstract>
</front>
<middle>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="introduction" title="Introduction">
<t>The use of web services (web APIs) on the Internet has become ubiquitous in most
applications, and depends on the fundamental Representational State
Transfer <xref target="REST"/> architecture of the web.</t>
<t>The Constrained RESTful Environments (CoRE) work 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, <xref target="RFC4944"/>). Constrained networks such as 6LoWPAN
support the fragmentation of IPv6 packets into small link-layer
frames, however incurring significant reduction in packet delivery
probability. One design goal of CoAP has been to keep message
overhead small,
thus limiting the need for fragmentation.</t>
<t>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 <xref
target="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,
it more importantly also offers
features for M2M such as built-in discovery, multicast support and
asynchronous message exchanges.</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.</t>
<section anchor="features" title="Features">
<t>CoAP has the following main features:
<list style="symbols">
<t>Constrained web protocol fulfilling M2M requirements.</t>
<t>UDP <xref target="RFC0768"/> binding with optional reliability supporting unicast and
multicast requests.</t>
<t>Asynchronous message exchanges.</t>
<t>Low header overhead and parsing complexity.</t>
<t>URI and Content-type support.</t>
<t>Simple proxy and caching capabilities.</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>Security binding to Datagram Transport Layer Security (DTLS) <xref target="RFC6347"/>.</t>
</list></t>
</section>
<section anchor="terminology" title="Terminology">
<t> 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 <xref
target="RFC2119"/> when they appear in ALL CAPS. These words may also
appear in this document in lower case as plain English words, absent
their normative meanings. </t>
<t>This specification requires readers to be familiar with all the terms
and concepts that are discussed in <xref
target="RFC2616"/>, including "resource",
"representation", "cache", and "fresh". In
addition, this specification defines the following terminology: <list
style="hanging">
<t hangText="Endpoint"><vspace/>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 (<xref
target="messages-and-endpoints"/>).</t>
<t hangText="Sender"><vspace/>The originating endpoint of a message.
When the aspect of identification of the specific sender is in focus,
also "source endpoint".</t>
<t hangText="Recipient"><vspace/>The destination endpoint of a
message. When the aspect of identification of the specific recipient
is in focus, also "destination endpoint".</t>
<t hangText="Client"><vspace/>The originating endpoint of a request;
the destination endpoint of a response.</t>
<t hangText="Server"><vspace/>The destination endpoint of a request;
the originating endpoint of a response.</t>
<t hangText="Origin Server"><vspace/> The server on which a given
resource resides or is to be created. </t>
<t hangText="Intermediary"><vspace />A CoAP endpoint that acts both as
a server and as a client towards (possibly via further intermediaries)
an origin server. A common form of an intermediary
is a proxy; several classes of such proxies are
discussed in this specification.</t>
<t hangText="Proxy"><vspace />
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.
</t>
<t hangText="Forward-Proxy"><vspace />A
"forward-proxy" is 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.</t>
<t hangText="Reverse-Proxy"><vspace />A "reverse-proxy" is 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 was the origin server for
the target resource.</t>
<t hangText="CoAP-to-CoAP Proxy"><vspace />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.
</t>
<t hangText="Cross-Proxy"><vspace />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.
</t>
<t hangText="Confirmable Message"><vspace /> 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.</t>
<t hangText="Non-confirmable Message"><vspace/> 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.</t>
<t hangText="Acknowledgement Message"><vspace/> 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
Piggy-Backed Response (q.v.).</t>
<t hangText="Reset Message"><vspace/> 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").</t>
<t hangText="Piggy-backed Response"><vspace />
A &Pb; Response is included right in a CoAP Acknowledgement
(ACK) message that is sent to acknowledge receipt of the Request for
this Response (<xref target="pb"/>).</t>
<t hangText="Separate Response"><vspace />
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 &Npb; Response is sent in a separate message exchange (<xref
target="npb"/>). </t>
<t hangText="Empty Message"><vspace />
A message with a Code of 0.00; neither a
request nor a response. An Empty message only
contains the four-byte header.</t>
<t hangText="Critical Option"><vspace /> An option that would need to
be understood by the endpoint ultimately receiving the message in order to
properly process the message (<xref target="critical-elective"/>).
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. </t>
<t hangText="Elective Option"><vspace /> 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 (<xref
target="critical-elective"/>). </t>
<t hangText="Unsafe Option"><vspace /> An option that would need to
be understood by a proxy receiving the message in order to
safely forward the message (<xref target="unsafe"/>).
Not every critical option is an unsafe option.
</t>
<t hangText="Safe-to-Forward Option"><vspace /> 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 (<xref target="unsafe"/>). </t>
<t hangText="Resource Discovery"><vspace /> The process where a CoAP
client queries a server for its list of hosted resources (i.e., links,
<xref target="discovery"/>). </t>
<t hangText="Content-Format"><vspace /> 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-Format 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".</t>
</list></t>
<t>
Additional terminology for constrained nodes and constrained
node networks can be found in <xref target="I-D.ietf-lwig-terminology"/>.
</t>
<t>In this specification, the term "byte" is used in its now customary
sense as a synonym for "octet".</t>
<t>
All multi-byte integers in this protocol are interpreted in
network byte order.
</t>
<t>Where arithmetic is used, this specification uses the
notation familiar from the programming language C, except that
the operator "**" stands for exponentiation.</t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="protocol" title="Constrained Application Protocol">
<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. 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.</t>
<t>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 piggy-backed in
Acknowledgement messages.</t>
<t>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 <xref target="fig-layers"/>). CoAP is however a
single protocol, with messaging and request/response just features of
the CoAP header.</t>
<figure anchor="fig-layers" title="Abstract layering of CoAP">
<artwork align="center"><![CDATA[
+----------------------+
| Application |
+----------------------+
+----------------------+ \
| Requests/Responses | |
|----------------------| | CoAP
| Messages | |
+----------------------+ /
+----------------------+
| UDP |
+----------------------+
]]></artwork>
</figure>
<section title="Messaging Model">
<t>The CoAP messaging model is based on the exchange of messages over
UDP between endpoints.</t>
<t>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 <xref target="syntax"/>. 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.) </t>
<t>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 <xref
target="fig-reliable"/>. 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). </t>
<figure anchor="fig-reliable" title="Reliable message transmission">
<artwork align="center"><![CDATA[
Client Server
| |
| CON [0x7d34] |
+----------------->|
| |
| ACK [0x7d34] |
|<-----------------+
| |
]]></artwork>
</figure>
<t>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 <xref
target="fig-unreliable"/>. When a recipient is not able to process a
Non-confirmable message, it may reply with a Reset message (RST).</t>
<figure anchor="fig-unreliable" title="Unreliable message transmission">
<artwork align="center"><![CDATA[
Client Server
| |
| NON [0x01a0] |
+----------------->|
| |
]]></artwork>
</figure>
<t>See <xref target="messages"/> for details of CoAP messages.</t>
<t> As CoAP runs over UDP, it also supports the use of multicast IP
destination addresses, enabling multicast CoAP requests. <xref
target="multicast"/> discusses the proper use of CoAP messages with
multicast addresses and precautions for avoiding response
congestion.</t>
<t>Several security modes are defined for CoAP in <xref
target="securing-coap"/> 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 <xref target="I-D.bormann-core-ipsec-for-coap"/>.</t>
</section>
<section title="Request/Response Model">
<t>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 (<xref target="response-matching"/>). (Note that the
Token is a concept separate from the Message ID.)</t>
<t>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 &pb; response, detailed in <xref
target="pb"/>. (There is no need for separately acknowledging
a &pb; response, as the client will retransmit the request if
the Acknowledgement message carrying the &pb; response is lost.)
Two examples for a basic GET request with &pb; response
are shown in <xref target="example-pb"/>, one successful, one resulting
in a 4.04 (Not Found) response.</t>
<figure anchor="example-pb"
title="Two GET requests with piggy-backed responses"> <!--XML2RFC is stupid-->
<artwork align="center"><![CDATA[
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" |
|<-----------------+ |<-----------------+
| | | |
]]></artwork>
</figure>
<t>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 &npb; response, as illustrated in <xref
target="example-npb"/> and described in more detail in <xref
target="npb"/>.</t>
<figure anchor="example-npb" title="A GET request with a separate response">
<artwork align="center"><![CDATA[
Client Server
| |
| CON [0x7a10] |
| GET /temperature |
| (Token 0x73) |
+----------------->|
| |
| ACK [0x7a10] |
|<-----------------+
| |
... Time Passes ...
| |
| CON [0x23bb] |
| 2.05 Content |
| (Token 0x73) |
| "22.5 C" |
|<-----------------+
| |
| ACK [0x23bb] |
+----------------->|
| |
]]></artwork>
</figure>
<t>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 <xref target="example-non"/>. </t>
<figure anchor="example-non" title="A NON request and response">
<artwork align="center"><![CDATA[
Client Server
| |
| NON [0x7a11] |
| GET /temperature |
| (Token 0x74) |
+----------------->|
| |
| NON [0x23bc] |
| 2.05 Content |
| (Token 0x74) |
| "22.5 C" |
|<-----------------+
| |
]]></artwork>
</figure>
<t>CoAP makes use of GET, PUT, POST and DELETE methods in a similar
manner to HTTP, with the semantics specified in <xref
target="methods"/>. (Note that the detailed semantics of CoAP methods
are "almost, but not entirely unlike" <xref target="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.)</t>
<t>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 (<xref target="multicast"/>) or
with the Observe option <xref
target="I-D.ietf-core-observe"/>.</t>
<t>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 response codes with a few
CoAP specific codes added, as defined in <xref
target="response-codes"/>.</t>
</section>
<section title="Intermediaries and Caching">
<t>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 <xref target="caching"/>.</t>
<t>Proxying is useful in constrained networks for several reasons,
including network traffic limiting, to improve performance, to access
resources of sleeping devices or 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 <xref target="proxying"/> for more information
on proxy functionality. </t>
<t>As CoAP was designed according to the REST architecture <xref target="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 for
converting 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. <xref target="http"/>
provides more detail about HTTP mapping. </t>
</section>
<section title="Resource Discovery">
<t>Resource discovery is important for machine-to-machine interactions,
and is supported using the <xref target="RFC6690">CoRE Link
Format</xref> as discussed in <xref target="discovery"/>.</t>
<t><vspace blankLines="10"/></t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="syntax" title="Message Format">
<t>CoAP is based on the exchange of compact messages which, 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 <xref target="dtls"/>). 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 <xref target="RFC3828"/> and UDP zero checksum
<xref target="RFC6936"/> are not supported by CoAP.)
</t>
<t>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. Following the Token value comes a sequence of zero or more
CoAP Options in Type-Length-Value (TLV) format, optionally followed
by a payload which takes up the rest of the datagram.</t>
<figure anchor="fig-message-format" title="Message Format">
<artwork type="drawing"><![CDATA[
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) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>
The fields in the header are defined as follows:
<list style="hanging">
<t hangText="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.
</t>
<t hangText="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 <xref target="messages"/>.</t>
<t hangText="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.</t>
<t hangText="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 <xref
target="coap-code-registry">CoAP Code Registries</xref>. The semantics of requests and
responses are defined in <xref
target="requests-responses"/>.</t>
<t hangText="Message ID:">16-bit unsigned integer in network byte
order. Used for the detection of 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 <xref target="messages"/>.</t>
</list>
</t>
<t>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 <xref target="token"/>.</t>
<t>Header and Token are followed by zero or more Options (<xref target="option-format"/>).
An Option can be followed by the end of the message, by another
Option, or by the Payload Marker and the payload.</t>
<t>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.</t>
<t><list style="hanging">
<t hangText="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.
</t>
</list></t>
<section anchor="option-format" title="Option Format">
<t>CoAP defines a number of options which 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.</t>
<t>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.</t>
<t>Option Numbers are maintained in the CoAP Option Number Registry
(<xref target="option-number-registry"/>).
See <xref target="option-semantics"/> for the semantics of the options
defined in this document.</t>
<figure title="Option Format" anchor="fig-option-format"><artwork><![CDATA[
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
\ \
/ /
\ \
+-------------------------------+
]]></artwork></figure>
<t>The fields in an option are defined as follows:</t>
<t><list style='hanging'>
<t hangText='Option Delta:'>
4-bit unsigned integer. A value between 0 and 12 indicates the
Option Delta. Three values are reserved for
special constructs:
<list style='hanging'>
<t hangText='13:'>
An 8-bit unsigned integer follows the initial byte and indicates
the Option Delta minus 13.</t>
<t hangText='14:'>
A 16-bit unsigned integer in network byte order follows the initial byte and indicates
the Option Delta minus 269.</t>
<t hangText='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.</t>
</list>
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.
</t>
<t hangText='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:
<list style='hanging'>
<t hangText='13:'>
An 8-bit unsigned integer precedes the Option Value and indicates
the Option Length minus 13.</t>
<t hangText='14:'>
A 16-bit unsigned integer in network byte order precedes the Option Value and indicates
the Option Length minus 269.</t>
<t hangText='15:'>
Reserved for future use. If the field is set to this value, it
MUST be processed as a message format error.</t>
</list>
</t>
<t hangText='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
<xref target="option-value-formats"/> for the formats used in this document;
options defined in other documents MAY make use of other option value
formats.</t>
</list></t>
</section>
<section title="Option Value Formats" anchor="option-value-formats">
<t>The options defined in this document make use of the following
option value formats.<list style="hanging" hangIndent="10">
<t hangText="empty:">A zero-length sequence of bytes.</t>
<t hangText="opaque:">An opaque sequence of bytes.</t>
<t hangText="uint:">A non-negative integer which is represented in
network byte order using the number of bytes given by the Option
Length field.<vspace blankLines="1"/>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.<list
style="hanging">
<t hangText="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.</t>
</list>
</t>
<t hangText="string:">A Unicode string which is encoded using <xref
target="RFC3629">UTF-8</xref> in <xref target="RFC5198"
>Net-Unicode form</xref>.<vspace blankLines="1"/>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. </t>
</list></t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="messages" title="Message Transmission">
<t>CoAP messages are exchanged asynchronously between CoAP endpoints. They
are used to transport CoAP requests and responses, the semantics of which
are defined in <xref target="requests-responses"/>.</t>
<t>As CoAP is bound to non-reliable 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:
<list style="symbols">
<t>Simple stop-and-wait retransmission reliability with exponential
back-off for Confirmable messages.</t>
<t>Duplicate detection for both Confirmable and Non-confirmable
messages.</t>
</list>
</t>
<section anchor="messages-and-endpoints" title="Messages and Endpoints">
<t>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 <xref
target="securing-coap"/>): 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.</t>
<t>There are different types of messages. The type of a message is
specified by the Type field of the CoAP Header.</t>
<t>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 <xref
target="coap-code-registry">CoAP Code Registries</xref>.</t>
<t>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.</t>
</section>
<section anchor="reliable" title="Messages Transmitted Reliably">
<t>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 acknowledge a Confirmable message with an Acknowledgement
message or, 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), MUST
reject it; 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 <xref target="pb"/> and <xref target="npb"/>). 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.
</t>
<t>The sender retransmits the Confirmable message at exponentially
increasing intervals, until it receives an acknowledgement (or Reset
message), or runs out of attempts.</t>
<t>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 <xref
target="constants"/>), and the retransmission counter is set to 0. When
the timeout is triggered and the retransmission counter is less than
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.</t>
<t>This specification makes no strong requirements on the
accuracy of the clocks used to implement the above binary
exponential backoff algorithm. In particular, an endpoint may
be late for a specific retransmission due to its sleep
schedule, and maybe 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 <xref
target="derived-values"/>), even if that means a sender may
miss an opportunity to transmit.</t>
<t>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: E.g., 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.</t>
<t>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 <xref target="RFC4443"/>
("fragmentation needed and DF set" for IPv4 <xref target="RFC0792"/>)
cannot properly occur and SHOULD be ignored if the implementation note
in <xref target="message-size"/> is followed; otherwise, they SHOULD
feed into a path MTU discovery algorithm <xref
target="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.</t>
</section>
<section anchor="unreliable"
title="Messages Transmitted Without Reliability">
<t>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.</t>
<t>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. If a recipient 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),
it MUST reject the message; 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.</t>
<t>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 <xref target="congestion"/>, 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.) </t>
<!-- ... as we only have one type of RST. -->
<t>Summarizing <xref target="reliable"/> and <xref
target="unreliable"/>, the four message types can be used as in <xref
target="typesummary"/>. "*" means that the combination is not used in
normal operation, but only to elicit a Reset message ("CoAP
ping").</t>
<texttable title="Usage of message types" anchor="typesummary">
<ttcol align='left'> </ttcol>
<ttcol align='left'>CON</ttcol>
<ttcol align='left'>NON</ttcol>
<ttcol align='left'>ACK</ttcol>
<ttcol align='left'>RST</ttcol>
<c>Request</c> <c>X</c> <c>X</c> <c>-</c> <c>-</c>
<c>Response</c> <c>X</c> <c>X</c> <c>X</c> <c>-</c>
<c>Empty</c> <c>*</c> <c>-</c> <c>X</c> <c>X</c>
</texttable>
</section>
<section title="Message Correlation" anchor="message-correlation">
<t>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.</t>
<t>The same Message ID MUST NOT be re-used (in communicating
with the same endpoint)
within the EXCHANGE_LIFETIME (<xref target="derived-values"/>).</t>
<t>
<list style="hanging">
<t hangText="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.
</t>
</list>
</t>
<t>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.</t>
</section>
<section title="Message Deduplication" anchor="message-deduplication">
<t>A recipient might receive the same Confirmable message
(as indicated by the Message ID and source endpoint) multiple times
within the EXCHANGE_LIFETIME (<xref target="derived-values"/>), 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 <xref
target="request-semantics"/>) or can be handled in an idempotent
fashion. Examples for relaxed message deduplication:
<list style='symbols'>
<t>A server might relax the requirement to answer all retransmissions of
an idempotent request with the same response (<xref target="reliable"
/>), 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.</t> <t>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.</t>
</list>
</t>
<t>A recipient might receive the same Non-confirmable
message (as indicated by the Message ID and source endpoint) multiple
times within NON_LIFETIME (<xref target="derived-values"/>). 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.</t>
</section>
<section title="Message Size" anchor="message-size">
<t>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. 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. </t>
<t><list style="hanging">
<t hangText="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; worse, 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 form of path MTU
discovery <xref target="RFC4821"/>;
this should generally be unnecessary in most 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 <xref target="I-D.ietf-core-block"/> when
approaching three-digit message sizes. </t>
<t>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, if not all of
the payload, at least the CoAP header and options 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 <xref target="request-entity-too-large"/>) 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 <xref
target="I-D.ietf-core-block"/>. </t>
</list></t>
</section>
<section anchor="congestion" title="Congestion Control">
<t>Basic congestion control for CoAP is provided by the exponential
back-off mechanism in <xref target="reliable"/>. </t>
<t> 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.</t>
<t>Further congestion control optimizations and considerations are
expected in the future, which may for example provide automatic
initialization of the CoAP transmission parameters defined in <xref
target="constants"/>, and thus may allow a value for NSTART greater than
one.</t>
<t>A client stops expecting a response to a Confirmable
request for which no acknowledgment message was received,
after EXCHANGE_LIFETIME. 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.</t>
<t><list style="hanging">
<t hangText="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
(<xref target="amplification"/>).
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.
</t>
</list></t>
</section>
<section anchor="constants" title="Transmission Parameters">
<t>Message transmission is controlled by the following parameters:</t>
<texttable title="CoAP Protocol Parameters" anchor="constants-table">
<ttcol align='left'>name</ttcol>
<ttcol align='left'>default value</ttcol>
<c>ACK_TIMEOUT</c>
<c>2 seconds</c>
<c>ACK_RANDOM_FACTOR</c>
<c>1.5</c>
<c>MAX_RETRANSMIT</c>
<c>4</c>
<c>NSTART</c>
<c>1</c>
<c>DEFAULT_LEISURE</c>
<c>5 seconds</c>
<c>PROBING_RATE</c>
<c>1 Byte/second</c>
</texttable>
<section anchor="constant_changes" title="Changing The Parameters">
<t>The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT,
NSTART, DEFAULT_LEISURE (<xref target="multicast-request-response"/>), 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.</t>
<t>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
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 <xref target="RFC5405"/>. (<xref
target="I-D.allman-tcpm-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.</t>
<t>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.</t>
<t>MAX_RETRANSMIT can be freely adjusted, but a too small value 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 <xref target="derived-values"/>).</t>
<t>If the choice of transmission parameters leads to an
increase of derived time values (see <xref target="derived-values"/>), the configuration
mechanism MUST ensure the adjusted value is also available to
all the endpoints that these adjusted
values are to be used to communicate with.
</t>
</section>
<section anchor="derived-values"
title="Time Values derived from Transmission Parameters">
<t>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:</t>
<t><list style='symbols'>
<t>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:
<list style='empty'>
<t>ACK_TIMEOUT * ((2 ** MAX_RETRANSMIT) - 1) * ACK_RANDOM_FACTOR</t>
</list></t>
<t>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:
<list style='empty'>
<t>ACK_TIMEOUT * ((2 ** (MAX_RETRANSMIT + 1)) - 1) *
ACK_RANDOM_FACTOR</t>
</list></t>
</list></t>
<t>In addition, some assumptions need to be made on the characteristics
of the network and the nodes.</t>
<t><list style='symbols'>
<t>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 <xref target="RFC0793"/>, which is "arbitrarily defined
to be 2 minutes" (<xref target="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), just 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.</t>
<t>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.</t>
<t>MAX_RTT is the maximum round-trip time, or: <list style='empty'>
<t>(2 * MAX_LATENCY) + PROCESSING_DELAY</t> </list></t> </list></t>
<t>From these values, we can derive the following values relevant to the
protocol operation:</t>
<t><list style='symbols'>
<t>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 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: <list
style='empty'> <t>MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY</t> </list>
or 247 seconds with the default transmission parameters.</t>
<t>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 re-use is not bounded by the specification, an expectation
of reliable detection of duplication at the receiver is in the
timescales of MAX_TRANSMIT_SPAN. Therefore, for this purpose, it is
safer to use the value:
<list style='empty'>
<t>MAX_TRANSMIT_SPAN + MAX_LATENCY</t>
</list>
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.</t>
</list></t>
<t><xref target="derived-constants"/> summarizes the derived parameters introduced in
this subsection with their default values.</t>
<texttable title="Derived Protocol Parameters" anchor="derived-constants">
<ttcol align='left'>name</ttcol>
<ttcol align='right'>default value</ttcol>
<c>MAX_TRANSMIT_SPAN</c>
<c>45 s</c>
<c>MAX_TRANSMIT_WAIT</c>
<c>93 s</c>
<c>MAX_LATENCY</c>
<c>100 s</c>
<c>PROCESSING_DELAY</c>
<c>2 s</c>
<c>MAX_RTT</c>
<c>202 s</c>
<c>EXCHANGE_LIFETIME</c>
<c>247 s</c>
<c>NON_LIFETIME</c>
<c>145 s</c>
</texttable>
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="requests-responses" title="Request/Response Semantics">
<t>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 exchanged asynchronously over CoAP
messages.</t>
<section anchor="request-semantics" title="Requests">
<t>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 meta-data about the request.</t>
<t>CoAP supports the basic methods of GET, POST, PUT, 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 <xref target="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.</t>
<t>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.</t>
<t>The methods used in requests are described in detail in
<xref target="methods"/>.</t>
</section>
<section anchor="response-semantics" title="Responses">
<t>After receiving and interpreting a request, a server responds with a
CoAP response, which is matched to the request by means of a
client-generated token (<xref target="response-matching"/>,
note that this is different from the Message ID that matches a
Confirmable message to its Acknowledgement).</t>
<t>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 <xref
target="response-codes"/>. The Response Code numbers to be set in the
Code field of the CoAP header are maintained in the <xref
target="coap-code-registry-responses">CoAP Response Code
Registry</xref>.</t>
<figure title="Structure of a Response Code" anchor="response-code">
<artwork type="drawing" align="center"><![CDATA[
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|class| detail |
+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>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 (<xref
target="response-code"/>). </t>
<t>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).</t>
<t>There are 3 classes of response codes:
<list style="hanging">
<t hangText="2 - Success:">The request was successfully received,
understood, and accepted.</t>
<t hangText="4 - Client Error:">The request contains bad syntax or
cannot be fulfilled.</t>
<t hangText="5 - Server Error:">The server failed to fulfill an
apparently valid request.</t>
</list>
The response codes are designed to be extensible: Response Codes in the
Client Error and 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.</t>
<t>The possible response codes are described in detail in <xref
target="response-codes"/>.</t>
<t>Responses can be sent in multiple ways, which are defined
in the following subsections.</t>
<section anchor="pb" title="Piggy-backed">
<t>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 "&Pb;" Response.</t>
<t>The response is returned in the Acknowledgement message independent
of whether the response indicates success or failure. In effect, the
response is piggy-backed on the Acknowledgement message, and no
separate message is required to return the response.</t>
<t><list style="hanging">
<t hangText="Implementation Note:"> The protocol leaves the decision whether to
piggy-back 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 piggy-back whenever possible -- saving
resources in the network and both at the client and at the server.</t>
</list></t>
</section>
<section anchor="npb" title="Separate">
<t>It may not be possible to return a &pb; response in all cases. For
example, a server might need longer to obtain the representation of
the resource requested than it can wait sending back the
Acknowledgement message, without risking the client to repeatedly
retransmit the request message (see also the discussion of
PROCESSING_DELAY in <xref target="derived-values"/>). The Response to a request carried in a
Non-confirmable message is always sent separately (as there is no
Acknowledgement message).</t>
<t>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 knowing in advance that there
will be no &pb; response.
In both cases,
the acknowledgement effectively is a promise
that the request will be acted upon later.</t>
<t>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 <xref target="non-confirmable-responses"/>.)</t>
<t> When the server chooses to use a &npb; 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 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.
</t>
<t>
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.
</t>
<t>
</t>
<t><list style="hanging">
<t hangText="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.)</t>
</list></t>
</section>
<section anchor="non-confirmable-responses" title="Non-confirmable">
<t>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.</t>
</section>
</section>
<section anchor="response-matching" title="Request/Response Matching">
<t>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. </t>
<section anchor="token" title="Token">
<t>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, which
the server MUST echo in any resulting response without
modification.
</t>
<t>A token is intended for use as a client-local identifier
for differentiating between concurrent requests (see <xref
target="response-matching"/>); it could have been called a "request
ID". </t>
<t>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 piggy-backed responses. There are however
multiple possible implementation strategies to fulfill this. </t>
<t>A client sending a request without using transport layer
security (<xref target="securing-coap"/>) SHOULD use a
non-trivial, randomized token to guard against
spoofing of responses (<xref target="address-spoofing-attacks"/>).
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.
<xref target="RFC4086"/> discusses
randomness requirements for security.
</t>
<t>An endpoint receiving a token it did not generate MUST
treat it as opaque and make no
assumptions about its content or structure.</t>
</section>
<section anchor="requestresponse-matching-rules" title="Request/Response Matching Rules">
<t>The exact rules for matching a response to a request are as
follows:
<list style="numbers">
<t>The source endpoint of the response MUST be the same as the
destination endpoint of the original request.</t>
<t>In a &pb; response, both the Message ID of the Confirmable request
and the Acknowledgement, and the token of the response and original
request MUST match. In a &npb; response, just the token of the
response and original request MUST match.</t>
</list>
</t>
<t>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 (<xref target="reliable"/>, <xref
target="unreliable"/>).</t>
<t><list style="hanging">
<t hangText="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 correlate this response to,
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
<xref target="I-D.ietf-core-observe"/>
will have to keep state in any case.)
</t></list></t>
</section>
</section>
<section anchor="option-semantics" title="Options">
<t>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 meta-data that would be carried in an HTTP header in
HTTP is supplied as options as well.</t>
<t>CoAP defines a single set of options that are used in both requests
and responses:
<list style="symbols">
<t>Content-Format</t>
<t>ETag</t>
<t>Location-Path</t>
<t>Location-Query</t>
<t>Max-Age</t>
<t>Proxy-Uri</t>
<t>Proxy-Scheme</t>
<t>Uri-Host</t>
<t>Uri-Path</t>
<t>Uri-Port</t>
<t>Uri-Query</t>
<t>Accept</t>
<t>If-Match</t>
<t>If-None-Match</t>
<t>Size1</t>
</list>
The semantics of these options along with their properties are defined
in detail in <xref target="options"/>.</t>
<t>Not all options are defined for use with all methods and response
codes. The possible options for methods and response codes are defined
in <xref target="methods"/> and <xref target="response-codes"/>
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.</t>
<section anchor="critical-elective" title="Critical/Elective">
<t>Options fall into one of two classes: "critical" or "elective".
The difference between these is how an option unrecognized by an
endpoint is handled:
<list style="symbols">
<t>Upon reception, unrecognized options of class "elective" MUST
be silently ignored.</t>
<t>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 <xref target="diagnostic-message-payload"/>).</t>
<t>Unrecognized options of class "critical" that occur in
a Confirmable response, or piggy-backed in an
Acknowledgement, MUST cause the response to be rejected
(<xref target="reliable"/>).</t>
<t>Unrecognized options of class "critical" that occur in a
Non-confirmable message MUST cause the message to be
rejected (<xref target="unreliable"/>).</t>
</list>
</t>
<t>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.</t>
<t>Critical/Elective rules apply to non-proxying endpoints. A proxy
processes options based on Unsafe/Safe-to-Forward classes as defined in
<xref target="proxying"/>.</t>
</section>
<section anchor="unsafe" title="Proxy Unsafe/Safe-to-Forward and NoCacheKey">
<t>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). </t>
<t>In addition, for an option that is
marked Safe-to-Forward, the option number indicates whether it is intended to
be part of the Cache-Key (<xref target="caching"/>) in a
request or not; if some of the
NoCacheKey bits are 0, it is, if all NoCacheKey
bits are 1, it is not (see <xref target="option-numbers"/>).
<list style="hanging">
<t hangText="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. E.g., 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.
</t>
<t>
NoCacheKey is indicated in three bits so that only
one out of eight codepoints is qualified as
NoCacheKey, assuming this is the less likely case.
</t>
</list>
</t>
<t>Proxy behavior with regard to these classes is defined in
<xref target="proxying"/>.</t>
</section>
<section anchor="option-length" title="Length">
<t>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 <xref
target="critical-elective"/>).</t>
</section>
<section anchor="option-defaults" title="Default Values">
<t>Options may be defined to have a default value. If the value of
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.</t>
<t>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. </t>
</section>
<section anchor="repeatable-options" title="Repeatable Options">
<t>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.</t>
<t>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 <xref
target="critical-elective"/>).</t>
</section>
<section anchor="option-numbers" title="Option Numbers">
<t>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. </t>
<t>More generally speaking, an Option number is constructed
with a bit mask to indicate if an
option is Critical/Elective, Unsafe/Safe-to-Forward and in the case of Safe-to-Forward, also 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. </t>
<figure title="Option Number Mask (Least Significant Byte)" anchor="option-mask"><artwork type="drawing" align="center"><![CDATA[
0 1 2 3 4 5 6 7
+---+---+---+---+---+---+---+---+
| | NoCacheKey| U | C |
+---+---+---+---+---+---+---+---+
]]></artwork></figure>
<t>An endpoint may use an equivalent of the C code in
<xref target="option-class-masks"/> to derive
the characteristics of an option number
<spanx style='verb'>onum</spanx>.</t>
<figure title="Determining Characteristics from an Option Number" anchor="option-class-masks"><artwork><![CDATA[
Critical = (onum & 1);
UnSafe = (onum & 2);
NoCacheKey = ((onum & 0x1e) == 0x1c);
]]></artwork></figure>
<t>The option numbers for the options defined in this document are
listed in the <xref target="option-number-registry">CoAP Option Number
Registry</xref>.</t>
</section>
</section>
<section anchor="payload-semantics" title="Payloads and Representations">
<t>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.</t>
<section title="Representation" anchor="representation-payload">
<t>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.</t>
<t>
<list style="hanging">
<t hangText="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.
</t>
</list>
</t>
<t>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 (<xref target="diagnostic-message-payload"/>).</t>
</section>
<section title="Diagnostic Payload" anchor="diagnostic-message-payload">
<t>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 <xref
target="RFC3629">UTF-8</xref>, more specifically using <xref
target="RFC5198">Net-Unicode form</xref>.</t>
<t>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.
</t>
</section>
<section anchor="selected-representation" title="Selected Representation">
<t>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.</t>
<t>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 (<xref target="conditional-request"/>).
<!-- define conditional request option --></t>
<t>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 (<xref target="etag"/>) is defined as selected representation metadata.</t>
</section>
<section anchor="content-negotiation" title="Content Negotiation">
<t>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.</t>
<t>By using the Accept Option (<xref
target="accept"/>) in a request, the client can indicate which
content-format it prefers to receive.</t>
</section>
</section>
<section anchor="caching" title="Caching">
<t>CoAP endpoints MAY cache responses in order to reduce the response
time and network bandwidth consumption on future, equivalent
requests.</t>
<t>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 <xref target="freshness-model"/>). 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 <xref
target="validation-model"/>).</t>
<!-- Response Cacheability --> <t>Unlike HTTP, the cacheability of CoAP
responses does not depend on the request method, but the Response Code.
The cacheability of each Response Code is defined along the Response
Code definitions in <xref target="response-codes"/>. Response Codes that
indicate success and are unrecognized by an endpoint MUST NOT be
cached.</t>
<!-- Constructing Responses from Caches --> <t>For a presented request,
a CoAP endpoint MUST NOT use a stored response, unless:
<list style="symbols">
<t>the presented request method and that used to obtain the stored
response match,</t>
<t>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 (<xref target="option-semantics"/>) or
recognized by the Cache and fully interpreted with respect to its
specified cache behavior (such as the ETag request option,
<xref target="etag"/>, see also <xref target="unsafe"/>), and</t>
<t>the stored response is either fresh or successfully validated as
defined below.</t>
</list></t>
<t>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.
</t>
<section anchor="freshness-model" title="Freshness Model">
<t>When a response is "fresh" in the cache, it can be used to satisfy
subsequent requests without contacting the origin server, thereby
improving efficiency.</t>
<t>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 <xref target="max-age"/>). 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.</t>
<t>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.</t>
<t>
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.
</t>
</section>
<section anchor="validation-model" title="Validation Model">
<t>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 (<xref target="etag"/>) in the GET
request to give the origin server an opportunity to both select a
stored response to be used, and to update its freshness. This process
is known as "validating" or "revalidating" the stored response.</t>
<t>When sending such a request, the endpoint SHOULD add an ETag Option
specifying the entity-tag of each stored response that is
applicable.</t>
<t>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 <xref target="valid"/>.</t>
<t>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.</t>
</section>
</section>
<section anchor="proxying" title="Proxying">
<t>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.</t>
<t>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 <xref target="terminology"/>.</t>
<t>
<list style="hanging">
<t hangText="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").
</t>
<t>
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 <xref target="http-coap-connect"/> for the
cross-proxy case.
</t>
</list>
</t>
<t>
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 security except where equivalent lower layer
security is used for the leg between the client and the proxy.
</t>
<section anchor="proxy-ops" title="Proxy Operation">
<t>A proxy generally needs a way to determine potential
request parameters for a request to a destination based on
the request it received.
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, necessitating some
form of namespace translation in the reverse-proxy.
However, some aspects of the operation of proxies are common
to all its forms.
</t>
<t>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 <xref target="caching"/>.
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. E.g., 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. <!--XXXtoken-->
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.)
</t>
<t>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, message format errors), then a 5.02
(Bad Gateway) response MUST be returned. Otherwise, the proxy returns
the response to the client.</t>
<t>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. E.g., the Max-Age Option could be adjusted by the proxy for each
response using the formula:
<list style='empty'>
<t>
proxy-max-age = original-max-age - cache-age
</t>
</list>
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.
</t>
<t>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, 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.</t>
<t>Additional considerations for cross-protocol proxying
between CoAP and HTTP are discussed in <xref target="http"/>.</t>
</section>
<section anchor="forward-proxy" title="Forward-Proxies">
<t>CoAP distinguishes between requests made (as if) to an origin server and a request
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 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 <xref target="proxy-uri"/>),
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 <xref
target="uri-options"/>); alternatively the URI in a proxy
request can be assembled from a Proxy-Scheme option and the
split options mentioned.</t>
<t>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 <xref target="proxy-uri"/>), then the request
MUST be treated as a local (non-proxied) request.</t>
<t>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.
</t>
</section>
<section anchor="reverse-proxy" title="Reverse-Proxies">
<t>
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.
E.g., a reverse-proxy might offer various resources
the existence of which it has learned through resource
discovery as if they were its own resources. 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
control over where the request goes, e.g. by embedding
host identifiers and port numbers into the URI path of
the resources offered.
</t>
<t>
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.
</t>
</section>
</section>
<section anchor="methods" title="Method Definitions">
<t>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) &pb; response.</t>
<section anchor="get" title="GET">
<t>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.</t>
<t>The GET method is safe and idempotent.</t>
</section>
<section anchor="post" title="POST">
<t>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.</t>
<t>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 (<xref
target="location-options"/>). 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.</t>
<t>POST is neither safe nor idempotent.</t>
</section>
<section anchor="put" title="PUT">
<t>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.</t>
<t>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.</t>
<t>Further restrictions to a PUT can be made by including the If-Match
(see <xref target="if-match"/>) or If-None-Match (see <xref
target="if-none-match"/>) options in the request.</t>
<t>PUT is not safe, but is idempotent.</t>
</section>
<section anchor="delete" title="DELETE">
<t>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.</t> <!-- this is different from HTTP! -->
<t>DELETE is not safe, but is idempotent.</t>
</section>
</section>
<section anchor="response-codes" title="Response Code Definitions">
<t>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 <xref target="RFC2616"/>;
this does not mean that any such relationship modifies the HTTP mapping
specified in <xref target="http"/>.</t>
<section anchor="success" title="Success 2.xx">
<t>This class of status code indicates that the clients request
was successfully received, understood, and accepted.</t>
<section anchor="created" title="2.01 Created">
<t>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.</t>
<t>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.</t>
<t>This response is not cacheable.</t>
</section>
<section anchor="deleted" title="2.02 Deleted">
<t>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.</t>
<t>This response is not cacheable. However, a cache MUST mark any
stored response for the deleted resource as not fresh.</t>
</section>
<section anchor="valid" title="2.03 Valid">
<t>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.</t>
<t>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 <xref target="validation-model"/>).
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.)
</t>
</section>
<section anchor="changed" title="2.04 Changed">
<t>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.</t>
<t>This response is not cacheable. However, a cache MUST mark any
stored response for the changed resource as not fresh.</t>
</section>
<section anchor="content" title="2.05 Content">
<t>Like HTTP 200 "OK", but only used in response to GET
requests.</t>
<t>The payload returned with the response is a representation of the
target resource.</t>
<t>This response is cacheable: Caches can use the Max-Age Option to
determine freshness (see <xref target="freshness-model"/>) and (if
present) the ETag Option for validation (see <xref
target="validation-model"/>).</t>
</section>
</section>
<section anchor="client-error" title="Client Error 4.xx">
<t>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.</t>
<t>The server SHOULD include a diagnostic payload under the
conditions detailed in <xref
target="diagnostic-message-payload"/>.</t>
<t>Responses of this class are cacheable: Caches can use the Max-Age
Option to determine freshness (see <xref target="freshness-model"/>).
They cannot be validated.</t>
<section anchor="bad-request" title="4.00 Bad Request">
<t>Like HTTP 400 "Bad Request".</t>
</section>
<section anchor="unauthorized" title="4.01 Unauthorized">
<t>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
<xref target="securing-coap"/>.</t>
</section>
<section anchor="bad-option" title="4.02 Bad Option">
<t>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.</t>
</section>
<section anchor="forbidden" title="4.03 Forbidden">
<t>Like HTTP 403 "Forbidden".</t>
</section>
<section anchor="not-found" title="4.04 Not Found">
<t>Like HTTP 404 "Not Found".</t>
</section>
<section anchor="method-not-allowed" title="4.05 Method Not Allowed">
<t>Like HTTP 405 "Method Not Allowed", but with no parallel to the
"Allow" header field.</t>
</section>
<section anchor="not-acceptable" title="4.06 Not Acceptable">
<t>Like HTTP 406 "Not Acceptable", but with no response entity.</t>
</section>
<section anchor="precondition-failed" title="4.12 Precondition Failed">
<t>Like HTTP 412 "Precondition Failed".</t>
</section>
<section anchor="request-entity-too-large" title="4.13 Request Entity Too Large">
<t>Like HTTP 413 "Request Entity Too Large".</t>
<t>The response SHOULD include a Size1 Option (<xref
target="size1"/>) 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.
</t>
</section>
<section anchor="unsupported-media-type" title="4.15 Unsupported Content-Format">
<t>Like HTTP 415 "Unsupported Media Type".</t>
</section>
</section>
<section anchor="server-error" title="Server Error 5.xx">
<t>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.</t>
<t>The server SHOULD include a diagnostic payload under the
conditions detailed in <xref
target="diagnostic-message-payload"/>.</t>
<t>Responses of this class are cacheable: Caches can use the Max-Age
Option to determine freshness (see <xref target="freshness-model"/>).
They cannot be validated.</t>
<section anchor="internal-server-error" title="5.00 Internal Server Error">
<t>Like HTTP 500 "Internal Server Error".</t>
</section>
<section anchor="not-implemented" title="5.01 Not Implemented">
<t>Like HTTP 501 "Not Implemented".</t>
</section>
<section anchor="bad-gateway" title="5.02 Bad Gateway">
<t>Like HTTP 502 "Bad Gateway".</t>
</section>
<section anchor="service-unavailable" title="5.03 Service Unavailable">
<t>Like HTTP 503 "Service Unavailable", but using the Max-Age Option
in place of the "Retry-After" header field to indicate the number of
seconds after which to retry.</t>
</section>
<section anchor="gateway-timeout" title="5.04 Gateway Timeout">
<t>Like HTTP 504 "Gateway Timeout".</t>
</section>
<section anchor="proxying-not-supported" title="5.05 Proxying Not Supported">
<t>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 <xref
target="proxy-uri"/>).</t>
</section>
</section>
</section>
<section anchor="options" title="Option Definitions">
<t>The individual CoAP options are summarized in <xref
target="tab-options"/> and explained in the subsections of
this section.</t>
<t>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. (The present specification does not define any NoCacheKey
options, but the format of the table is intended to be useful
for additional specifications.)
</t>
<texttable anchor="tab-options" title="Options">
<ttcol align="right">No.</ttcol>
<ttcol align="left">C</ttcol>
<ttcol align="left">U</ttcol>
<ttcol align="left">N</ttcol>
<ttcol align="left">R</ttcol>
<ttcol align="left">Name</ttcol>
<ttcol align="left">Format</ttcol>
<ttcol align="left">Length</ttcol>
<ttcol align="left">Default</ttcol>
<c> 1</c><c>x</c><c> </c><c> </c><c>x</c><c>If-Match </c><c>opaque</c><c>0-8</c><c>(none) </c>
<c> 3</c><c>x</c><c>x</c><c>-</c><c> </c><c>Uri-Host </c><c>string</c><c>1-255</c><c>(see below)</c>
<c> 4</c><c> </c><c> </c><c> </c><c>x</c><c>ETag </c><c>opaque</c><c>1-8</c><c>(none) </c>
<c> 5</c><c>x</c><c> </c><c> </c><c> </c><c>If-None-Match </c><c>empty </c><c>0</c><c>(none) </c>
<c> 7</c><c>x</c><c>x</c><c>-</c><c> </c><c>Uri-Port </c><c>uint </c><c>0-2</c><c>(see below)</c>
<c> 8</c><c> </c><c> </c><c> </c><c>x</c><c>Location-Path </c><c>string</c><c>0-255</c><c>(none) </c>
<c>11</c><c>x</c><c>x</c><c>-</c><c>x</c><c>Uri-Path </c><c>string</c><c>0-255</c><c>(none) </c>
<c>12</c><c> </c><c> </c><c> </c><c> </c><c>Content-Format </c><c>uint </c><c>0-2 </c><c>(none) </c>
<c>14</c><c> </c><c>x</c><c>-</c><c> </c><c>Max-Age </c><c>uint </c><c>0-4 </c><c>60 </c>
<c>15</c><c>x</c><c>x</c><c>-</c><c>x</c><c>Uri-Query </c><c>string</c><c>0-255</c><c>(none) </c>
<c>17</c><c>x</c><c> </c><c> </c><c> </c><c>Accept </c><c>uint </c><c>0-2</c><c>(none) </c>
<c>20</c><c> </c><c> </c><c> </c><c>x</c><c>Location-Query</c><c>string</c><c>0-255</c><c>(none) </c>
<c>35</c><c>x</c><c>x</c><c>-</c><c> </c><c>Proxy-Uri </c><c>string</c><c>1-1034</c><c>(none) </c>
<c>39</c><c>x</c><c>x</c><c>-</c><c> </c><c>Proxy-Scheme </c><c>string</c><c>1-255</c><c>(none) </c>
<c>60</c><c></c><c></c><c>x</c><c></c><c>Size1</c><c>uint</c><c>0-4</c><c>(none)</c>
<postamble>C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable</postamble>
</texttable>
<section anchor="uri-options"
title="Uri-Host, Uri-Port, Uri-Path and Uri-Query">
<t>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 <xref target="uri"/>.</t>
<t>The steps for parsing URIs into options is defined in <xref
target="uri-parsing"/>. 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:
<list style="symbols">
<t>the Uri-Host Option specifies the Internet host of the resource
being requested,</t>
<t>the Uri-Port Option specifies the transport layer port number of
the resource,</t>
<t>each Uri-Path Option specifies one segment of the absolute path
to the resource, and</t>
<t>each Uri-Query Option specifies one argument parameterizing the
resource.</t>
</list>
Note: Fragments (<xref target="RFC3986"/>, Section 3.5) are not part
of the request URI and thus will not be transmitted in a CoAP
request.</t>
<t>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. </t>
<t>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).</t>
<t>The steps for constructing the request URI from the options are
defined in <xref target="uri-constructing"/>. Note that an
implementation does not necessarily have to construct the URI; it can
simply look up the target resource by looking at the individual
options.</t>
<t>Examples can be found in <xref target="uri-examples"/>.</t>
</section>
<section anchor="proxy-uri" title="Proxy-Uri and Proxy-Scheme">
<t>The Proxy-Uri Option is used to make a request to a forward-proxy (see
<xref target="proxying"/>). The forward-proxy is requested to forward the
request or service it from a valid cache, and return the response.</t>
<t>The option value is an absolute-URI (<xref target="RFC3986"/>,
Section 4.3). </t>
<t>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.</t>
<t>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.</t>
<t>The Proxy-Uri Option MUST take precedence over any of the Uri-Host,
Uri-Port, Uri-Path or Uri-Query options (which MUST NOT be included at
the same time in a request containing the Proxy-Uri Option).</t>
<t>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 <xref target="uri-constructing"/>. 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; e.g., to
represent a URI with a userinfo component in the authority, only
Proxy-Uri can be used.</t>
</section>
<section anchor="content-type" title="Content-Format">
<t>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 <xref
target="media-type-registry">CoAP Content Format
Registry</xref>.
In the absence of the option, no default value is assumed,
i.e. the representation format of any representation message
payload is indeterminate (<xref target="payload-semantics"/>).</t>
</section>
<section anchor="accept" title="Accept">
<t> 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 <xref
target="media-type-registry">CoAP Content-Format Registry</xref>. 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.</t>
</section>
<section anchor="max-age" title="Max-Age">
<t>The Max-Age Option indicates the maximum time a response may be
cached before it is considered not fresh (see <xref
target="freshness-model"/>).</t>
<t>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.</t>
<t>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 <xref target="proxy-ops"/>.)</t>
</section>
<section anchor="etag" title="ETag">
<t>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.)</t>
<section anchor="etag-as-a-response-option" title="ETag as a Response Option">
<t>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 (<xref target="selected-representation"/>) of the target resource.
If one or more Location-* options are present and thus a location URI
is indicated (<xref target="location-options"/>), the tagged representation is the
representation that would be retrieved by a GET request to the location URI.
</t>
<t>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.</t>
<t>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.</t>
</section>
<section anchor="etag-as-a-request-option" title="ETag as a Request Option">
<t>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.</t>
<t>A server can issue a 2.03 Valid response (<xref target="valid"/>) 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.</t>
<t>In effect, a client can determine if any of the stored representations
is current (see <xref target="validation-model" />) without needing to
transfer them again.</t>
<t>The ETag Option MAY occur zero, one or more times in a request.</t>
</section>
</section>
<section anchor="location-options"
title="Location-Path and Location-Query">
<t>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 <xref target="post"/>). The
location is resolved relative to the request URI.</t>
<t>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. </t>
<t>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 "..".</t>
<t>The steps for constructing the location URI from the options are
analogous to <xref target="uri-constructing"/>, except that the first
five <!-- BRITTLE - - need to recheck --> 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 "/").</t>
<!-- XXX fix this so it is clear relative to what -->
<t>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.</t>
</section>
<section anchor="conditional-request" title="Conditional Request Options">
<t>Conditional request options enable a client to ask the server to
perform the request only if certain conditions specified by the option
are fulfilled.</t>
<t>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.</t>
<t>If the condition is fulfilled, the server performs the request
method as if the conditional request options were not present.</t>
<t>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.</t>
<section anchor="if-match" title="If-Match">
<t>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).</t>
<t>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).</t>
<t>The If-Match Option can occur multiple times. If
any of the options match, then the condition is
fulfilled.</t>
<t>If there is one or more If-Match Option, but none
of the options match, then the condition is not fulfilled.</t>
</section>
<section anchor="if-none-match" title="If-None-Match">
<t>The If-None-Match Option MAY be used to make a request conditional
on the non-existence 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.</t>
<t>If the target resource does exist, then the
condition is not fulfilled.</t>
<t>(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.)</t>
</section>
</section>
<section anchor="size1" title="Size1 Option">
<t>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 <xref target="I-D.ietf-core-block"/>. In the
present specification, it is used in 4.13 responses (<xref
target="request-entity-too-large"/>) to indicate the maximum
size of request entity that the server is able and willing
to handle.</t>
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="uri" title="CoAP URIs">
<t>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 which 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.</t>
<t>The syntax of the "coap" and "coaps" URI schemes is specified
in this section in
Augmented Backus-Naur Form (ABNF) <xref target="RFC5234"/>. The
definitions of "host", "port", "path-abempty", "query", "segment",
"IP-literal", "IPv4address" and "reg-name" are adopted from <xref
target="RFC3986"/>.
<list style="hanging">
<t hangText="Implementation Note:">
Unfortunately, over time the URI format has acquired
significant complexity. Implementers are encouraged to
examine <xref target="RFC3986"/> closely. E.g., the ABNF
for IPv6 addresses is more complicated than maybe
expected. Also, implementers should take care to perform
the processing of percent decoding/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 in a path component.
</t>
</list>
</t>
<section anchor="uri-coap" title="coap URI Scheme">
<!-- FIXME: any valid "coap" URI matches this grammar, but not all
URIs matching this grammar are valid "coap" URIs
-->
<figure>
<artwork type="abnf"><![CDATA[
coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ]
]]></artwork>
</figure>
<!-- TODO: check this with an ABNF compiler -->
<t>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 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 &PORT; is
assumed.</t>
<t>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 "/").</t>
<t>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.</t>
<t>The "coap" URI scheme supports the path prefix "/.well-known/"
defined by <xref target="RFC5785"/> for "well-known locations" in the
name-space of a host. This enables discovery of policy or other
information about a host ("site-wide metadata"), such as hosted
resources (see <xref target="discovery"/>).</t>
<t>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.</t>
</section>
<section anchor="uri-coaps" title="coaps URI Scheme">
<!-- FIXME: any valid "coaps" URI matches this grammar, but not all
URIs matching this grammar are valid "coaps" URIs
-->
<figure>
<artwork type="abnf"><![CDATA[
coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty
[ "?" query ]
]]></artwork>
</figure>
<!-- TODO: check this with an ABNF compiler -->
<t>All of the requirements listed above for the "coap" scheme are also
requirements for the "coaps" scheme, except that a default UDP port
of &PORTS; 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 <xref target="dtls"/>.</t>
<t>Considerations for caching of responses to "coaps"
identified requests are discussed in <xref target="sec-cache"/>.
</t>
<t>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 name spaces and are considered to be distinct
origin servers.</t>
</section>
<section anchor="uri-normalization"
title="Normalization and Comparison Rules">
<t>Since the "coap" and "coaps" schemes conform to the URI generic
syntax, such URIs are normalized and compared according to the algorithm
defined in <xref target="RFC3986"/>, Section 6, using the defaults
described above for each scheme.</t>
<t>If the port is equal to the default port for a scheme, the normal
form is to elide the port subcomponent. Likewise, an empty path
component is equivalent to an absolute path of "/", so the normal form
is to provide a path of "/" instead. The scheme and host are
case-insensitive and normally provided in lowercase; IP-literals are in
recommended form <xref target="RFC5952"/>; all other components are
compared in a case-sensitive manner. Characters other than those in the
"reserved" set are equivalent to their percent-encoded bytes (see <xref
target="RFC3986"/>, Section 2.1): the normal form is to not encode
them.</t>
<t>For example, the following three URIs are equivalent, and cause the
same options and option values to appear in the CoAP messages:</t>
<figure>
<artwork type="example"><![CDATA[
coap://example.com:5683/~sensors/temp.xml
coap://EXAMPLE.com/%7Esensors/temp.xml
coap://EXAMPLE.com:/%7esensors/temp.xml
]]></artwork>
</figure>
</section>
<section anchor="uri-parsing" title="Decomposing URIs into Options">
<t>The steps to parse a request's options from a string |url| are as
follows. These steps either result in zero or more of the Uri-Host,
Uri-Port, Uri-Path and Uri-Query Options being included in the
request, or they fail.
<list style="numbers">
<t>If the |url| string is not an absolute URI (<xref
target="RFC3986"/>), then fail this algorithm.</t>
<t>Resolve the |url| string using the process of reference resolution
defined by <xref target="RFC3986"/>. At this stage the URL
is in ASCII encoding <xref target="RFC0020"/>, even though
the decoded components will be interpreted in <xref
target="RFC3629">UTF-8</xref> after step 5, 8 and 9. <vspace blankLines="1"/>
NOTE: It doesn't matter what it is resolved relative to, since we
already know it is an absolute URL at this point.</t>
<t>If |url| does not have a <scheme> component whose value, when
converted to ASCII lowercase, is "coap" or "coaps", then fail this
algorithm.</t>
<t>If |url| has a <fragment> component, then fail this
algorithm.</t>
<t>If the <host> component of |url| does not represent the
request's destination IP address as an IP-literal or IPv4address,
include a Uri-Host Option and let that option's value be the value of
the <host> component of |url|, converted to ASCII lowercase, and
then converting all percent-encodings ("%" followed by two hexadecimal
digits) to the corresponding characters. <vspace blankLines="1"/>
NOTE: In the usual case where the request's destination IP address is
derived from the host part, this ensures that a Uri-Host Option is
only used for a <host> component of the form reg-name.</t>
<t>If |url| has a <port> component, then let |port| be that
component's value interpreted as a decimal integer; otherwise, let
|port| be the default port for the scheme.</t>
<t>If |port| does not equal the request's destination UDP port,
include a Uri-Port Option and let that option's value be |port|.</t>
<t>If the value of the <path> component of |url| is empty or
consists of a single slash character (U+002F SOLIDUS "/"), then move
to the next step.<vspace blankLines="1"/> Otherwise, for each segment
in the <path> component, include a Uri-Path Option and let that
option's value be the segment (not including the delimiting slash
characters) after converting each percent-encoding ("%" followed by
two hexadecimal digits) to the corresponding byte.</t>
<t>If |url| has a <query> component, then, for each argument in
the <query> component, include a Uri-Query Option and let that
option's value be the argument (not including the question mark and
the delimiting ampersand characters) after converting each
percent-encoding to the corresponding byte.</t>
</list></t>
<t>Note that these rules completely resolve any percent-encoding.
</t>
</section>
<section anchor="uri-constructing" title="Composing URIs from Options">
<t>The steps to construct a URI from a request's options are as follows.
These steps either result in a URI, or they fail. In these steps,
percent-encoding a character means replacing each of its (UTF-8 encoded)
bytes by a "%" character followed by two hexadecimal digits representing
the byte, where the digits A-F are in upper case (as defined in <xref
target="RFC3986"/> Section 2.1; to reduce variability, the hexadecimal
notation for percent-encoding in CoAP URIs MUST use uppercase letters).
The definitions of "unreserved" and "sub-delims" are adopted from <xref
target="RFC3986"/>.
<list style="numbers">
<t>If the request is secured using DTLS, let |url| be the string
"coaps://". Otherwise, let |url| be the string "coap://".</t>
<t>If the request includes a Uri-Host Option, let |host| be that
option's value, where any non-ASCII characters are replaced by their
corresponding percent-encoding. If |host| is not a valid reg-name or
IP-literal or IPv4address, fail the algorithm. If the request does not include a Uri-Host Option, let |host|
be the IP-literal (making use of the conventions of <xref
target="RFC5952"/>) or IPv4address representing the request's
destination IP address.</t>
<t>Append |host| to |url|.</t>
<t>If the request includes a Uri-Port Option, let |port| be that
option's value. Otherwise, let |port| be the request's destination UDP
port.</t>
<t>If |port| is not the default port for the scheme, then append a
single U+003A COLON character (:) followed by the decimal
representation of |port| to |url|.</t>
<!-- BRITTLE: location-options refers to "first five steps" -->
<t>Let |resource name| be the empty string. For each Uri-Path Option
in the request, append a single character U+002F SOLIDUS (/) followed
by the option's value to |resource name|, after converting any
character that is not either in the "unreserved" set, "sub-delims"
set, a U+003A COLON (:) or U+0040 COMMERCIAL AT (@) character, to its
percent-encoded form.</t>
<t>If |resource name| is the empty string, set it to a single
character U+002F SOLIDUS (/).</t>
<t>For each Uri-Query Option in the request, append a single character
U+003F QUESTION MARK (?) (first option) or U+0026 AMPERSAND (&)
(subsequent options) followed by the option's value to |resource
name|, after converting any character that is not either in the
"unreserved" set, "sub-delims" set (except U+0026 AMPERSAND (&)),
a U+003A COLON (:), U+0040 COMMERCIAL AT (@), U+002F SOLIDUS (/) or
U+003F QUESTION MARK (?) character, to its percent-encoded form.</t>
<t>Append |resource name| to |url|.</t>
<t>Return |url|.</t>
</list></t>
<t>Note that these steps have been designed to lead to a URI
in normal form (see <xref target="uri-normalization"/>).
</t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="discovery" title="Discovery">
<section title="Service Discovery" anchor="service-discovery">
<t>As a part of discovering the services offered by a CoAP
server, a client has to learn about the endpoint used by a server.</t>
<t>A server is discovered by a client by the client (knowing or) learning
a URI that references a resource in the namespace of the server.
Alternatively, clients can use Multicast CoAP (see <xref
target="multicast"/>) and the "All CoAP Nodes" multicast address to find
CoAP servers.</t>
<t>Unless the port subcomponent in a "coap" or "coaps" URI indicates the
UDP port at which the CoAP server is located, the server is assumed to
be reachable at the default port.</t>
<t>The CoAP default port number &PORT; MUST be supported by a
server that offers resources for
resource discovery (see <xref target="resource-discovery"/> below) and
SHOULD be supported for providing access to other resources. The default
port number &PORTS; for DTLS-secured CoAP MAY be supported by a server
for resource discovery and for providing access to other resources. In
addition other endpoints may be hosted at other ports, e.g. in
the dynamic port space.</t>
<t>
<list style="hanging">
<t hangText="Implementation Note:">
When a CoAP server is hosted by a 6LoWPAN node, header
compression efficiency is improved when it also supports
a port number in the 61616-61631 compressed UDP port space defined in
<xref target="RFC4944"/> (note that, as its UDP port differs from the
default port, it is a different endpoint from the server at the
default port).</t>
</list>
</t>
</section>
<section anchor="resource-discovery" title="Resource Discovery">
<t>The discovery of resources offered by a CoAP endpoint is extremely
important in machine-to-machine applications where there are no humans in
the loop and static interfaces result in fragility. To maximize
interoperability in a CoRE environment, a CoAP endpoint SHOULD
support the CoRE Link Format of discoverable resources as described in
<xref target="RFC6690"/>, except where fully manual
configuration is desired. It is up to the server which resources
are made discoverable (if any). </t>
<section title="'ct' Attribute">
<t> This section defines a new Web Linking <xref target="RFC5988"/>
attribute for use with <xref target="RFC6690"/>. The Content-Format code
"ct" attribute provides a hint about the
Content-Formats this
resource returns. Note that this is only a hint, and does not override
the Content-Format Option of a CoAP response obtained
by actually requesting the representation of the
resource.
The value is in the CoAP identifier code format as
a decimal ASCII integer and MUST be in the range of 0-65535 (16-bit
unsigned integer). For example application/xml would be indicated as
"ct=41". If no Content-Format code attribute is present then nothing
about the type can be assumed. The Content-Format code attribute MAY
include a space-separated sequence of Content-Format
codes, indicating that multiple content-formats
are available. The syntax of the attribute value is
summarized in the production ct-value in <xref
target="fig-ct-value"/>, where cardinal, SP and
DQUOTE are defined as in <xref target="RFC6690"/>.
</t>
<figure anchor="fig-ct-value">
<artwork><![CDATA[
ct-value = cardinal
/ DQUOTE cardinal *( 1*SP cardinal ) DQUOTE
]]></artwork>
</figure>
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="multicast" title="Multicast CoAP">
<t>CoAP supports making requests to a IP multicast group. This is defined
by a series of deltas to Unicast CoAP.
A more general discussion of group communication with CoAP is
in <xref target="I-D.ietf-core-groupcomm"/>.
</t>
<t>CoAP endpoints that offer services that they want other
endpoints to be able to find using multicast service discovery,
join one or more of the appropriate
all-CoAP-nodes multicast addresses (<xref target="multicast-addresses"/>)
and listen on the default CoAP port. Note that an endpoint might
receive multicast requests on other multicast addresses,
including the all-nodes IPv6 address (or via broadcast on IPv4);
an endpoint MUST therefore be prepared to receive such
messages but MAY ignore them if multicast service discovery is
not desired.
</t>
<section title="Messaging Layer">
<t>A multicast request is characterized by being transported in a CoAP
message that is addressed to an IP multicast address instead of a CoAP
endpoint. Such multicast requests MUST be Non-confirmable.</t>
<!-- <t>Some mechanisms for avoiding congestion from multicast requests have
been considered in <xref
target="I-D.eggert-core-congestion-control"/>.</t>
-->
<t><!--To reduce response congestion, -->A server SHOULD be aware that a
request arrived via multicast, e.g. by making use of modern APIs such as
IPV6_RECVPKTINFO <xref target="RFC3542"/>, if available.</t>
<t>To avoid an implosion of error responses, when a server is
aware that a request arrived via multicast, it MUST
NOT return a RST in reply to NON. If it is not aware, it MAY return a
RST in reply to NON as usual. Because such a Reset message will look
identical to an RST for a unicast message from the sender, the
sender MUST avoid using a Message ID that is also still active
from this endpoint with any unicast endpoint that might
receive the multicast message. </t>
<t>At the time of writing, multicast messages can only be
carried in UDP, not in DTLS. This means that the security
modes defined for CoAP in this document are not applicable to
multicast.
</t>
</section>
<section anchor="multicast-request-response" title="Request/Response Layer">
<t>When a server is aware that a request arrived via multicast, the
server MAY always ignore the request, in particular
if it doesn't have anything useful to respond (e.g., if it only has an
empty payload or an error response). The decision for this may depend
on the application. (For example, in <xref target="RFC6690"/> query
filtering, a server should not respond to a multicast request if the
filter does not match. More examples are in <xref target="I-D.ietf-core-groupcomm"/>.) </t>
<t>If a server does decide to respond to a multicast request, it should
not respond immediately. Instead, it should pick a duration for the
period of time during which it intends to respond. For purposes of this
exposition, we call the length of this period the Leisure. The specific
value of this Leisure may depend on the application, or MAY be derived
as described below. The server SHOULD then pick a random point of time
within the chosen Leisure period to send back the unicast response to
the multicast request. If further responses need to be sent
based on the same multicast address membership, a new leisure
period starts at the earliest after the previous one finishes.
</t>
<t>To compute a value for Leisure, the server should have a group size
estimate G, a target data transfer rate R (which both should be chosen conservatively)
and an estimated response size S; a rough lower bound for Leisure can
then be computed as</t>
<figure><artwork align="center"><![CDATA[lb_Leisure = S * G / R]]></artwork></figure>
<t>E.g., for a multicast request with link-local scope on an 2.4 GHz
IEEE 802.15.4 (6LoWPAN) network, G could be (relatively conservatively)
set to 100, S to 100 bytes, and the target rate to 8 kbit/s =
1 kB/s. The resulting lower bound for the Leisure is 10
seconds.</t>
<t>If a CoAP endpoint does not have suitable data to compute a
value for Leisure, it MAY resort to DEFAULT_LEISURE. </t>
<t>When matching a response to a multicast request, only the token MUST
match; the source endpoint of the response does not need to (and will
not) be the same as the destination endpoint of the original
request.</t>
<t>For the purposes of interpreting the Location-* options and
any links embedded in the representation and, the request URI
(base URI) relative to which the response is interpreted, is
formed by replacing the multicast address in the Host
component of the original request URI by the literal IP
address of the endpoint actually responding.</t>
<section title="Caching">
<t>When a client makes a multicast request, it always makes a new
request to the multicast group (since there may be new group members
that joined meanwhile or ones that did not get the previous request).
It MAY update a cache with the received responses. Then it uses both
cached-still-fresh and 'new' responses as the result of the
request.</t>
<t>A response received in reply to a GET request to a multicast group
MAY be used to satisfy a subsequent request on the related unicast
request URI. The unicast request URI is obtained by replacing the
authority part of the request URI with the transport layer source
address of the response message.</t>
<t>A cache MAY revalidate a response by making a GET request on the
related unicast request URI.</t>
<t>A GET request to a multicast group MUST NOT contain an ETag option.
A mechanism to suppress responses the client already has is left for
further study.</t>
</section>
<section title="Proxying">
<t>When a forward-proxy receives a request with a Proxy-Uri
or URI constructed from Proxy-Scheme that
indicates a multicast address, the proxy obtains a set of responses as
described above and sends all responses (both cached-still-fresh and
new) back to the original client.
</t>
<t>
This specification does not provide a way to indicate the
unicast-modified request URI (base URI) in responses thus
forwarded. Proxying multicast requests is discussed in
more detail in <xref target="I-D.ietf-core-groupcomm"/>; one
proposal to address the base URI issue can be found in
section 3 of <xref target="I-D.bormann-coap-misc"/>.
</t>
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="securing-coap" title="Securing CoAP">
<t>This section defines the DTLS binding for CoAP.</t>
<t>During the provisioning phase, a CoAP device is provided with the
security information that it needs, including keying materials and access
control lists. This specification defines provisioning for the
RawPublicKey mode in <xref target="rawpublickey-provisioning"/>. At the
end of the provisioning phase, the device will be in one of four security
modes with the following information for the given mode. The NoSec and
RawPublicKey modes are mandatory to implement for this specification. </t>
<t><list style="hanging">
<t hangText="NoSec:">There is no protocol level security (DTLS is
disabled). Alternative techniques to provide lower layer security
SHOULD be used when appropriate. The use of IPsec is discussed in
<xref target="I-D.bormann-core-ipsec-for-coap"/>. Certain link
layers in use with constrained nodes also provide link layer
security, which may be appropriate with proper key management.</t>
<t hangText="PreSharedKey:">DTLS is enabled and there is a list of
pre-shared keys <xref target="RFC4279"/> and each key includes a list
of which nodes it can be used to communicate with as described in
<xref target="presharedkey"/>. At the extreme there may be one key for
each node this CoAP node needs to communicate with (1:1 node/key
ratio). Conversely, if more than two entities share a
specific pre-shared key, this key only enables the entities to
authenticate as a member of that group and not as a specific peer.
</t>
<t hangText="RawPublicKey:">DTLS is enabled and the device has an
asymmetric key pair without a certificate (a raw public key) that is
validated using an out-of-band mechanism <xref
target="I-D.ietf-tls-oob-pubkey"/> as described in <xref
target="rawpublickey"/>. The device also has an identity calculated
from the public key and a list of identities of the nodes it can
communicate with. </t>
<t hangText="Certificate:">DTLS is enabled and the device has an
asymmetric key pair with an X.509 certificate <xref target="RFC5280"/>
that binds it to its Authority Name and is signed by some common trust
root as described in <xref target="certificate"/>. The device also has
a list of root trust anchors that can be used for validating a
certificate. </t>
</list>
</t>
<t>In the "NoSec" mode, the system simply sends the packets over normal
UDP over IP and is indicated by the "coap" scheme and the CoAP default
port. The system is secured only by keeping attackers from being able to
send or receive packets from the network with the CoAP nodes; see <xref
target="cross-protocol-attacks"/> for an additional complication with this
approach.</t>
<t> The other three security modes are achieved using DTLS
and are indicated by the "coaps" scheme and DTLS-secured CoAP default
port. The result is a security association that can be used to
authenticate (within the limits of the security model) and, based on this
authentication, authorize the communication partner. CoAP itself does not
provide protocol primitives for authentication or authorization; where
this is required, it can either be provided by communication security
(i.e., IPsec or DTLS) or by object security (within the payload). Devices
that require authorization for certain operations are expected to require
one of these two forms of security. Necessarily, where an intermediary is
involved, communication security only works when that intermediary is part
of the trust relationships; CoAP does not provide a way to forward
different levels of authorization that clients may have with an
intermediary to further intermediaries or origin servers -- it therefore
may be required to perform all authorization at the first
intermediary.</t>
<section anchor="dtls" title="DTLS-secured CoAP">
<t>Just as HTTP is secured using Transport Layer Security (TLS) over
TCP, CoAP is secured using Datagram TLS (DTLS) <xref target="RFC6347"/>
over UDP (see <xref target="fig-layers-secured"/>). This section defines
the CoAP binding to DTLS, along with the minimal mandatory-to-implement
configurations appropriate for constrained environments. The binding is
defined by a series of deltas to Unicast CoAP. DTLS is in practice TLS
with added features to deal with the unreliable nature of the UDP
transport.</t>
<figure anchor="fig-layers-secured"
title="Abstract layering of DTLS-secured CoAP">
<artwork align="center"><![CDATA[
+----------------------+
| Application |
+----------------------+
+----------------------+
| Requests/Responses |
|----------------------| CoAP
| Messages |
+----------------------+
+----------------------+
| DTLS |
+----------------------+
+----------------------+
| UDP |
+----------------------+
]]></artwork>
</figure>
<t>In some constrained nodes (limited flash and/or RAM) and networks
(limited bandwidth or high scalability requirements), and depending on
the specific cipher suites in use, all modes of DTLS may not be
applicable. Some DTLS cipher suites can add significant implementation
complexity as well as some initial handshake overhead needed when
setting up the security association. Once the initial handshake is
completed, DTLS adds a limited per-datagram overhead of approximately 13
bytes, not including any initialization vectors/nonces (e.g., 8 bytes
with TLS_PSK_WITH_AES_128_CCM_8 <xref target="RFC6655"/>), integrity
check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 <xref
target="RFC6655"/>) and padding required by the cipher suite. Whether
and which mode of using DTLS is applicable for a CoAP-based application
should be carefully weighed considering the specific cipher suites that
may be applicable, and whether the session maintenance makes it
compatible with application flows and sufficient resources are available
on the constrained nodes and for the added network overhead.
(For some modes of using DTLS, this specification
identifies a mandatory to implement cipher suite.
This is an implementation requirement to maximize
interoperability in those cases where these cipher
suites are indeed appropriate. The specific security
policies of an application may determine the actual
(set of) cipher suites that can be used.)
DTLS is not
applicable to group keying (multicast communication); however, it may be
a component in a future group key management protocol.</t>
<section title="Messaging Layer">
<!-- borrowed from rfc2818 -->
<t>The endpoint acting as the CoAP client should also act as the DTLS
client. It should initiate a session to the server on the appropriate
port. When the DTLS handshake has finished, the client may initiate the
first CoAP request. All CoAP messages MUST be sent as DTLS "application
data".</t>
<t>The following rules are added for matching an ACK or RST to a CON
message or a RST to a NON message: The DTLS session MUST
be the same and the epoch MUST be the same. </t>
<t>A message is the same when it is sent within the same DTLS session
and same epoch and has the same Message ID.</t>
<t>Note: When a Confirmable message is retransmitted, a new DTLS
sequence_number is used for each attempt, even though the CoAP Message
ID stays the same. So a recipient still has to perform deduplication as
described in <xref target="message-deduplication" />. Retransmissions
MUST NOT be performed across epochs.</t>
<t>DTLS connections in RawPublicKey and Certificate mode are set up
using mutual authentication so they can remain up and be reused for
future message exchanges in either direction. Devices can close a DTLS
connection when they need to recover resources but in general they
should keep the connection up for as long as possible. Closing the DTLS
connection after every CoAP message exchange is very inefficient.</t>
</section>
<section title="Request/Response Layer">
<t>The following rules are added for matching a response to a request:
The DTLS session MUST be the same and the epoch MUST be the same.</t>
<t>This means the response to a DTLS secured request
MUST always be DTLS secured using the same security session
and epoch. Any attempt to supply a NoSec response to a DTLS
request simply does not match the request and (unless it
does match an unrelated NoSec request) therefore MUST be
rejected.</t>
</section>
<section title="Endpoint Identity">
<t>Devices SHOULD support the Server Name Indication (SNI) to indicate
their Authority Name in the SNI HostName field as defined in Section 3
of <xref target="RFC6066"/>. This is needed so that when a host that
acts as a virtual server for multiple Authorities receives a new DTLS
connection, it knows which keys to use for the DTLS session.</t>
<section anchor="presharedkey" title="Pre-Shared Keys">
<t>When forming a connection to a new node, the system selects an
appropriate key based on which nodes it is trying to reach and then
forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS.
Implementations in these modes MUST support the mandatory to implement
cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in <xref
target="RFC6655"/>. </t>
<t>Depending on the commissioning model, applications may need
to define an application profile for identity hints as
required and detailed in <xref target="RFC4279"/> (Section
5.2) to enable the use of PSK identity hints. </t>
<t>The security considerations of <xref target="RFC4279"/>
(Section 7) apply. In particular, applications should
carefully weigh whether they need Perfect Forward Secrecy
(PFS) or not and select an appropriate cipher suite (7.1).
The entropy of the PSK must be sufficient to mitigate against
brute-force and (where the PSK is not chosen randomly but by a
human) dictionary attacks (7.2). The cleartext communication
of client identities may leak data or compromise privacy (7.3).
</t>
</section>
<section anchor="rawpublickey" title="Raw Public Key Certificates">
<t>In this mode the device has an asymmetric key pair but without an
X.509 certificate (called a raw public key); e.g., the
asymmetric key pair is generated by the manufacturer
and installed on the device (see also <xref
target="constrained-node-considerations"/>).
A device MAY be
configured with multiple raw public keys. The type and length of the
raw public key depends on the cipher suite used.
Implementations in RawPublicKey mode
MUST support the mandatory to implement cipher suite
TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in <xref
target="I-D.mcgrew-tls-aes-ccm-ecc"/>, <xref target="RFC5246"/>, <xref
target="RFC4492"/>.
The key used MUST be ECDSA-capable. The curve secp256r1 MUST be
supported <xref target="RFC4492"/>; this curve is equivalent to the NIST P-256
curve. The hash algorithm is SHA-256. Implementations MUST use the
Supported Elliptic Curves Extension and Supported Point Format
extensions <xref target="RFC4492"/>; the uncompressed point format MUST be supported;
<xref target="RFC6090"/> can be used as an implementation method.
Some guidance relevant to
the implementation of this cipher suite can be found
in <xref target="W3CXMLSEC"/>.
The mechanism for using raw public keys with TLS
is specified in <xref
target="I-D.ietf-tls-oob-pubkey"/>.
</t>
<t><list style="hanging">
<t hangText="Implementation Note:">
Specifically, this means the extensions listed in <xref
target="rpkextensions"/> with at least the values listed will be present in the DTLS handshake.
</t>
</list></t>
<figure title="DTLS extensions present for TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8"
anchor="rpkextensions"><artwork><![CDATA[
Extension: elliptic_curves
Type: elliptic_curves (0x000a)
Length: 4
Elliptic Curves Length: 2
Elliptic curves (1 curve)
Elliptic curve: secp256r1 (0x0017)
Extension: ec_point_formats
Type: ec_point_formats (0x000b)
Length: 2
EC point formats Length: 1
Elliptic curves point formats (1)
EC point format: uncompressed (0)
Extension: signature_algorithms
Type: signature_algorithms (0x000d)
Length: 4
Data (4 bytes): 00 02 04 03
HashAlgorithm: sha256 (4)
SignatureAlgorithm: ecdsa (3)
]]></artwork></figure>
<section anchor="rawpublickey-provisioning" title="Provisioning">
<t>The RawPublicKey mode was designed to be easily provisioned in M2M
deployments. It is assumed that each device has an appropriate
asymmetric public key pair installed. An identifier is
calculated by the endpoint
from
the public key as described in Section 2 of <xref
target="RFC6920"/>. All implementations that support
checking RawPublicKey identities MUST support at least the sha-256-120
mode (SHA-256 truncated to 120 bits). Implementations SHOULD support
also longer length identifiers and MAY support shorter lengths. Note
that the shorter lengths provide less security against attacks and
their use is NOT RECOMMENDED.</t>
<t>Depending on how identifiers are given to the system that verifies
them, support for URI, binary, and/or human-speakable format <xref
target="RFC6920"/> needs to be implemented. All
implementations SHOULD support the binary mode and implementations that
have a user interface SHOULD also support the human-speakable
format.</t>
<t>During provisioning, the identifier of each node is collected, for
example by reading a barcode on the outside of the device or by
obtaining a pre-compiled list of the identifiers. These identifiers
are then installed in the corresponding endpoint, for example an M2M
data collection server. The identifier is used for two purposes, to
associate the endpoint with further device information and to perform
access control. During (initial and ongoing)
provisioning, an access control list of
identifiers the device may start DTLS sessions with SHOULD also be
installed and maintained.</t>
</section>
</section>
<section anchor="certificate" title="X.509 Certificates">
<t>Implementations in Certificate Mode
MUST support the mandatory to implement cipher suite
TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in <xref
target="I-D.mcgrew-tls-aes-ccm-ecc"/>, <xref target="RFC5246"/>, <xref
target="RFC4492"/>.
Namely, the certificate includes a
SubjectPublicKeyInfo that indicates an algorithm of
id-ecPublicKey with namedCurves secp256r1 <xref target="RFC5480"/>; the
public key format is uncompressed <xref target="RFC5480"/>; the hash
algorithm is SHA-256; if included the key usage extension
indicates digitalSignature.
Certificates MUST be signed with ECDSA using
secp256r1, and the signature MUST use SHA-256.
The key used MUST be ECDSA-capable. The curve secp256r1 MUST be
supported <xref target="RFC4492"/>; this curve is equivalent to the NIST P-256
curve. The hash algorithm is SHA-256. Implementations MUST use the
Supported Elliptic Curves Extension and Supported Point Format
extensions <xref target="RFC4492"/>; the uncompressed point format MUST be supported;
<xref target="RFC6090"/> can be used as an implementation method.
</t>
<t>The Authority Name in the certificate would be built out of a long
term unique identifier for the device such as the EUI-64 <xref target="EUI64"/>.
The Authority Name could also be based on the FQDN that was used as the Host
part of the CoAP URI. However, the device's IP address should not typically
be used as the Authority name as it would change over time. The discovery
process used in the system would build
up the mapping between IP addresses of the given devices and the
Authority Name for each device. Some devices could have more than one
Authority and would need more than a single certificate.</t>
<t>When a new connection is formed, the certificate from the remote
device needs to be verified. If the CoAP node has a source of absolute
time, then the node SHOULD check that the validity dates of the
certificate are within range.
The certificate MUST be validated as appropriate for the
security requirements, using functionality equivalent to the
algorithm specified in <xref target="RFC5280"/> section 6.
If the certificate contains a
SubjectAltName, then the Authority Name MUST match at least one of the
authority names of any CoAP URI found in a field of URI type in the
SubjectAltName set. If there is no SubjectAltName in the certificate,
then the Authoritative Name MUST match the CN found in the certificate
using the matching rules defined in <xref target="RFC2818"/> with the
exception that certificates with wildcards are not allowed. </t>
<t>
CoRE support for certificate status checking requires
further study. As a mapping of OCSP <xref target="RFC2560"/>
onto CoAP is not currently defined and OCSP may also not be
easily applicable in all environments, an alternative
approach may be using the TLS Certificate Status Request
extension (<xref target="RFC6066"/> section 8, also known as
"OCSP stapling") or preferably the Multiple Certificate
Status Extension (<xref
target="I-D.ietf-tls-multiple-cert-status-extension"/>), if available.
</t>
<t>If the system has a shared key in addition to the certificate, then a
cipher suite that includes the shared key such as
TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA <xref target="RFC5489"/> SHOULD be
used. </t>
</section>
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="http"
title="Cross-Protocol Proxying between CoAP and HTTP">
<t>CoAP supports a limited subset of HTTP functionality, and thus
cross-protocol proxying to HTTP is straightforward. There might be several
reasons for proxying 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 proxied to other protocols such as
XMPP <xref target="RFC6120"/> or SIP <xref target="RFC3264"/>; the
definition of these mechanisms is out of scope of this specification.</t>
<t>There are two possible directions to access a resource via a forward-proxy:
<list style="hanging">
<t hangText="CoAP-HTTP Proxying:">Enables CoAP clients to access
resources on HTTP servers through an intermediary. This is initiated
by including the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI in a
CoAP request to a CoAP-HTTP proxy.</t>
<t hangText="HTTP-CoAP Proxying:">Enables HTTP clients to access
resources on CoAP servers through an intermediary. This is initiated
by specifying a "coap" or "coaps" URI in the Request-Line of an HTTP
request to an HTTP-CoAP proxy.</t>
</list>
</t>
<t>Either way, only the Request/Response model of CoAP is mapped to HTTP.
The underlying model of Confirmable or Non-confirmable messages, etc., is
invisible and MUST have no effect on a proxy function. The following
sections describe the handling of requests to a forward-proxy. Reverse
proxies are not specified as the proxy function is transparent to the
client with the proxy acting as if it was the origin server.
However, similar considerations apply to reverse-proxies as to
forward-proxies, and there generally will be an expectation that
reverse-proxies operate in a similar way forward-proxies would.
As an implementation note, HTTP client libraries may make it
hard to operate an HTTP-CoAP forward proxy by not providing a
way to put a CoAP URI on the HTTP Request-Line; reverse-proxying
may therefore lead to wider applicability of a proxy.
A separate specification may define a convention for URIs
operating such a HTTP-CoAP reverse proxy
<xref target="I-D.castellani-core-http-mapping"/>.
</t>
<section anchor="coap-http" title="CoAP-HTTP Proxying">
<t>If a request contains a Proxy-Uri or Proxy-Scheme Option with an 'http' or 'https'
URI <xref target="RFC2616"/>, then the receiving CoAP endpoint (called
"the proxy" henceforth) is requested to perform the operation specified
by the request method on the indicated HTTP resource and return the
result to the client. (See also <xref
target="proxying"/> for how the request to the proxy is
formulated, including security requirements.)</t>
<t>This section specifies for any CoAP request the CoAP response that
the proxy should return to the client. How the proxy actually satisfies
the request is an implementation detail, although the typical case is
expected to be the proxy translating and forwarding the request to an
HTTP origin server.</t>
<t>Since HTTP and CoAP share the basic set of request methods,
performing a CoAP request on an HTTP resource is not so different from
performing it on a CoAP resource. The meanings of the individual CoAP
methods when performed on HTTP resources are explained in the
subsections of this section.</t>
<t>If the proxy is unable or unwilling to service a request
with an HTTP URI, a 5.05 (Proxying Not Supported) response is
returned to the client. If the proxy services the request by
interacting with a third party (such as the HTTP origin
server) and is unable to obtain a result within a reasonable
time frame, a 5.04 (Gateway Timeout) response is returned; if
a result can be obtained but is not understood, a 5.02 (Bad
Gateway) response is returned.</t>
<section anchor="coap-http-get" title="GET">
<t>The GET method requests the proxy to return a representation of the
HTTP resource identified by the request URI.</t>
<t>Upon success, a 2.05 (Content) response code SHOULD be returned. The
payload of the response MUST be a representation of the target HTTP
resource, and the Content-Format Option be set accordingly. The response
MUST indicate a Max-Age value that is no greater than the remaining
time the representation can be considered fresh. If the HTTP entity
has an entity tag, the proxy SHOULD include an ETag Option in the
response and process ETag Options in requests as described below.</t>
<t>A client can influence the processing of a GET request by including
the following option:
<list style="hanging">
<t hangText="Accept:"> The request MAY include an Accept
Option, identifying the preferred response content-format. </t>
<t hangText="ETag:">The request MAY include one or more ETag
Options, identifying responses that the client has stored. This
requests the proxy to send a 2.03 (Valid) response whenever it
would send a 2.05 (Content) response with an entity tag in the
requested set otherwise. Note that CoAP ETags are
always strong ETags in the HTTP sense; CoAP does not
have the equivalent of HTTP weak ETags, and there is no good
way to make use of these in a cross-proxy.
</t>
</list>
</t>
</section>
<section anchor="coap-http-put" title="PUT">
<t>The PUT method requests the proxy to update or create the HTTP
resource identified by the request URI with the enclosed
representation.</t>
<t>If a new resource is created at the request URI, a 2.01 (Created)
response MUST be returned to the client. If an existing resource is
modified, a 2.04 (Changed) response MUST be returned to indicate
successful completion of the request.</t>
</section>
<section anchor="coap-http-delete" title="DELETE">
<t>The DELETE method requests the proxy to delete the HTTP resource
identified by the request URI at the HTTP origin server.</t>
<t>A 2.02 (Deleted) response MUST be returned to client upon success
or if the resource does not exist at the time of the request.</t>
</section>
<section anchor="coap-http-post" title="POST">
<t>The POST method requests the proxy to have the representation
enclosed in the request be processed by the HTTP origin server. The
actual function performed by the POST method is determined by the
origin server and dependent on the resource identified by the request
URI.</t>
<t>If the action performed by the POST method does not result in a
resource that can be identified by a URI, a 2.04 (Changed) response
MUST be returned to the client. If a resource has been created on the
origin server, a 2.01 (Created) response MUST be returned.</t>
</section>
</section>
<section anchor="http-coap" title="HTTP-CoAP Proxying">
<t>If an HTTP request contains a Request-URI with a 'coap' or 'coaps'
URI, then the receiving HTTP endpoint (called "the proxy" henceforth) is
requested to perform the operation specified by the request method on
the indicated CoAP resource and return the result to the client.</t>
<t>This section specifies for any HTTP request the HTTP response that
the proxy should return to the client.
Unless otherwise specified all the statements made are RECOMMENDED
behavior; some highly constrained implementations may need to
resort to shortcuts.
How the proxy actually satisfies
the request is an implementation detail, although the typical case is
expected to be the proxy translating and forwarding the request to a
CoAP origin server. The meanings of the individual HTTP methods when
performed on CoAP resources are explained in the subsections
of this section.</t>
<t>If the proxy is unable or unwilling to service a request with a CoAP
URI, a 501 (Not Implemented) response is returned to the client.
If the proxy services the request by interacting with a third party
(such as the CoAP origin server) and is unable to obtain a result within
a reasonable time frame, a 504 (Gateway Timeout) response is
returned; if a result can be obtained but is not understood, a 502 (Bad
Gateway) response is returned.</t>
<section anchor="http-coap-options-trace" title="OPTIONS and TRACE">
<t> As the OPTIONS and TRACE methods are not supported in CoAP a 501
(Not Implemented) error MUST be returned to the client. </t>
</section>
<section anchor="http-coap-get" title="GET">
<t>The GET method requests the proxy to return a representation of the
CoAP resource identified by the Request-URI.</t>
<t>Upon success, a 200 (OK) response is returned. The payload
of the response MUST be a representation of the target CoAP resource,
and the Content-Type and Content-Encoding header fields be
set accordingly. The response MUST
indicate a max-age directive that indicates a value no greater than the remaining time
the representation can be considered fresh. If the CoAP response has an
ETag option, the proxy should include an ETag header field in the
response.</t>
<t>A client can influence the processing of a GET request by including
the following options:
<list style="hanging">
<t hangText="Accept:"> The most preferred Media-type of the HTTP
Accept header field in a request is mapped to a CoAP Accept option. HTTP
Accept Media-type ranges, parameters and extensions are not
supported by the CoAP Accept option. If the proxy cannot send a
response which is acceptable according to the combined Accept
field value, then the proxy sends a 406 (not acceptable)
response. The proxy MAY then retry the request with further
Media-types from the HTTP Accept header field. </t>
<t hangText="Conditional GETs:"> Conditional HTTP GET requests
that include an "If-Match" or "If-None-Match" request-header field
can be mapped to a corresponding CoAP request. The
"If-Modified-Since" and "If-Unmodified-Since" request-header
fields are not directly supported by CoAP, but are
implemented locally by a caching proxy. </t>
</list>
</t>
</section>
<section anchor="http-coap-head" title="HEAD">
<t> The HEAD method is identical to GET except that the server MUST
NOT return a message-body in the response. </t> <t> Although there is
no direct equivalent of HTTP's HEAD method in CoAP, an HTTP-CoAP proxy
responds to HEAD requests for CoAP resources, and the HTTP headers are
returned without a message-body. </t>
<t>
<list style="hanging">
<t hangText="Implementation Note:">An HTTP-CoAP proxy may
want to try using a block-wise transfer <xref
target="I-D.ietf-core-block"/> option to minimize the
amount of data actually transferred, but needs to be
prepared for the case that the origin server does not
support block-wise transfers.</t>
</list>
</t>
</section>
<section anchor="http-coap-post" title="POST">
<t>The POST method requests the proxy to have the representation
enclosed in the request be processed by the CoAP origin server. The
actual function performed by the POST method is determined by the
origin server and dependent on the resource identified by the request
URI.</t>
<t>If the action performed by the POST method does not result in a
resource that can be identified by a URI, a 200 (OK) or 204 (No
Content) response MUST be returned to the client. If a resource has
been created on the origin server, a 201 (Created) response MUST be
returned.</t>
<t>
If any of the Location-* Options are present in the CoAP response,
a Location header field constructed from the values of these
options is returned.
</t>
</section>
<section anchor="http-coap-put" title="PUT">
<t>The PUT method requests the proxy to update or create the CoAP
resource identified by the Request-URI with the enclosed
representation.</t>
<t>If a new resource is created at the Request-URI, a 201 (Created)
response is returned to the client. If an existing resource is
modified, either the 200 (OK) or 204 (No Content) response codes
is sent to indicate successful completion of the request.</t>
</section>
<section anchor="http-coap-delete" title="DELETE">
<t>The DELETE method requests the proxy to delete the CoAP resource
identified by the Request-URI at the CoAP origin server.</t>
<t>A successful response is 200 (OK) if the response includes
an entity describing the status or 204 (No Content) if the action has
been enacted but the response does not include an entity. </t>
</section>
<section anchor="http-coap-connect" title="CONNECT">
<t> This method can not currently be satisfied by an HTTP-CoAP proxy
function as TLS to DTLS tunneling has not yet been specified.
For now, a 501 (Not Implemented) error is returned to the
client. </t>
</section>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="security" title="Security Considerations">
<t>This section analyzes the possible threats to the protocol. It 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.</t>
<section anchor="protocol-parsing-processing-uris"
title="Protocol Parsing, Processing URIs">
<t>A network-facing application can exhibit vulnerabilities in its
processing logic for incoming packets. Complex parsers are well-known
as a likely source of such vulnerabilities, such as the ability to
remotely crash a node, or even remotely execute arbitrary code on it.
CoAP attempts to narrow the opportunities for introducing such
vulnerabilities by reducing parser complexity, by giving the entire
range of encodable values a meaning where possible, and by
aggressively reducing complexity that is often caused by unnecessary
choice between multiple representations that mean the same thing. Much
of the URI processing has been moved to the clients, further reducing
the opportunities for introducing vulnerabilities into the servers.
Even so, the URI processing code in CoAP implementations is likely to
be a large source of remaining vulnerabilities and should be
implemented with special care. CoAP access control
implementations need to ensure they don't introduce
vulnerabilities through discrepancies between the code
deriving access control decisions from a URI and the code
finally serving up the resource addressed by the URI.
The most complex parser remaining could
be the one for the CoRE Link Format, although this also has been
designed with a goal of reduced implementation complexity <xref
target="RFC6690"/>. (See also section 15.2 of <xref
target="RFC2616"/>.)</t>
</section>
<section anchor="sec-cache" title="Proxying and Caching">
<t> As mentioned in 15.7 of <xref target="RFC2616"/>, proxies are by
their very nature men-in-the-middle, breaking any IPsec or DTLS
protection that a direct CoAP message exchange might have. They are
therefore interesting targets for breaking confidentiality or
integrity of CoAP message exchanges. As noted in <xref
target="RFC2616"/>, they are also interesting targets for breaking
availability. </t>
<t> The threat to confidentiality and integrity of
request/response data is amplified where proxies also cache. Note
that CoAP does not define any of the cache-suppressing Cache-Control
options that HTTP/1.1 provides to better protect sensitive data. </t>
<t>For a caching implementation, any access control
considerations that would apply to making the request that
generated the cache entry also need to be applied to the
value in the cache. This is relevant for clients that
implement multiple security domains, as well as for proxies
that may serve multiple clients. Also, a caching proxy MUST
NOT make cached values available to requests that have
lesser transport security properties than to which it would
make available the process of forwarding the request in the
first place.
</t>
<t>Unlike the "coap" scheme, responses to "coaps" identified requests
are never "public" and thus MUST NOT be reused for shared
caching unless the cache is able to make equivalent access
control decisions to the ones that led to the cached entry.
They can, however, be reused in a private cache if the message
is cacheable by default in CoAP.</t>
<t> Finally, a proxy that fans out &Npb; Responses (as opposed to &Pb;
Responses) to multiple original requesters may provide additional
amplification (see <xref target="amplification"/>). </t>
</section>
<!--
<section title="Attacks on Message IDs">
<t>TODO. CoAP implementations should be tested against the
reception of unexpected Message IDs.</t>
</section>
-->
<section anchor="amplification" title="Risk of amplification">
<t> CoAP servers generally reply to a request packet with a response
packet. This response packet may be significantly larger than the
request packet. An attacker might use CoAP nodes to turn a small
attack packet into a larger attack packet, an approach known as
amplification. There is therefore a danger that CoAP nodes could
become implicated in denial of service (DoS) attacks by using the
amplifying properties of the protocol: An attacker that is attempting
to overload a victim but is limited in the amount of traffic it can
generate, can use amplification to generate a larger amount of
traffic. </t>
<t> This is particularly a problem in nodes that enable NoSec access,
that are accessible from an attacker and can access potential victims
(e.g. on the general Internet), as the UDP protocol provides no way to
verify the source address given in the request packet. An attacker
need only place the IP address of the victim in the source address of
a suitable request packet to generate a larger packet directed at the
victim. </t>
<t> As a mitigating factor, many constrained networks will only be
able to generate a small amount of traffic, which may make CoAP nodes
less attractive for this attack. However, the limited capacity of the
constrained network makes the network itself a likely victim of an
amplification attack. </t>
<t> Therefore, large amplification factors SHOULD NOT be provided
in the response if the request is not authenticated.
A CoAP server can reduce the amount of amplification it provides
to an attacker by using slicing/blocking modes of CoAP <xref
target="I-D.ietf-core-block"/> and offering large resource
representations only in relatively small slices. E.g., for a 1000
byte resource, a 10-byte request might result in an 80-byte response
(with a 64-byte block) instead of a 1016-byte response, considerably
reducing the amplification provided. </t>
<t> CoAP also supports the use of multicast IP addresses in requests,
an important requirement for M2M. Multicast CoAP requests may be the
source of accidental or deliberate denial of service attacks,
especially over constrained networks. This specification attempts to
reduce the amplification effects of multicast requests by limiting
when a response is returned. To limit the possibility of malicious
use, CoAP servers SHOULD NOT accept multicast requests that can not be
authenticated in some way, cryptographically or by some
multicast boundary limiting the potential sources. If
possible a CoAP server SHOULD limit the support for
multicast requests to the specific resources where the feature is
required. </t>
<t> On some general purpose operating systems providing a Posix-style
API, it is not straightforward to find out whether a packet received
was addressed to a multicast address. While many implementations will
know whether they have joined a multicast group, this creates a
problem for packets addressed to multicast addresses of the form
FF0x::1, which are received by every IPv6 node. Implementations SHOULD
make use of modern APIs such as IPV6_RECVPKTINFO <xref
target="RFC3542"/>, if available, to make this determination. </t>
</section>
<section anchor="address-spoofing-attacks"
title="IP Address Spoofing Attacks">
<t>Due to the lack of a handshake in UDP, a rogue endpoint which is
free to read and write messages carried by the constrained network
(i.e. NoSec or PreSharedKey deployments with nodes/key ratio > 1:1),
may easily attack a single endpoint, a group of endpoints, as well as
the whole network e.g. by:
<list style="numbers">
<t>spoofing RST in response to a CON or NON message, thus making
an endpoint "deaf"; or</t>
<t>spoofing an ACK in response to a CON
message, thus potentially preventing the
sender of the CON message from retransmitting,
and drowning out the actual response; or</t>
<t>spoofing the entire response with forged payload/options (this
has different levels of impact: from single response disruption,
to much bolder attacks on the supporting infrastructure, e.g.
poisoning proxy caches, or tricking validation / lookup interfaces
in resource directories and, more generally, any component that
stores global network state and uses CoAP as the messaging
facility to handle state set/update's is a potential target.);
or</t>
<t>spoofing a multicast request for a target node which may result
in both network congestion/collapse and victim DoS'ing / forced
wakeup from sleeping; or</t>
<t>spoofing observe messages, etc.</t>
</list></t>
<t>Response spoofing by off-path attackers can be
detected and mitigated even without
transport layer security by choosing a non-trivial,
randomized token in the request (<xref
target="token"/>). <xref target="RFC4086"/> discusses
randomness requirements for security. </t>
<t>In principle, other kinds of spoofing can be
detected by CoAP only in case CON
semantics is used, because of unexpected ACK/RSTs coming from the
deceived endpoint. But this imposes keeping track of the used Message
IDs which is not always possible, and moreover detection becomes
available usually after the damage is already done. This kind of attack
can be prevented using security modes other than NoSec.</t>
<t>
With or without source address spoofing, a client can
attempt to overload a server by sending requests,
preferably complex ones, to a server; address
spoofing makes tracing back, and blocking, this
attack harder. Given that the cost of a CON request
is small, this attack can easily be executed.
Under this attack, a constrained node with limited
total energy available may exhaust that energy much
more quickly than planned (battery depletion attack).
Also, if the client uses a Confirmable message and
the server responds with a Confirmable separate
response to a (possibly spoofed) address that does
not respond, the server will have to allocate buffer
and retransmission logic for each response up to the
exhaustion of MAX_TRANSMIT_SPAN, making it more
likely that it runs out of resources for processing
legitimate traffic. The latter problem can be
mitigated somewhat by limiting the rate of responses
as discussed in <xref target="congestion"/>.
An attacker could also spoof the address of a
legitimate client, which, if the server uses
separate responses, might block legitimate responses
to that client because of NSTART=1.
All these attacks
can be prevented using a security mode other than
NoSec, leaving only attacks on the security protocol.
</t>
</section>
<section anchor="cross-protocol-attacks" title="Cross-Protocol Attacks">
<t>The ability to incite a CoAP endpoint to send packets to a fake
source address can be used not only for amplification, but also for
cross-protocol attacks against a victim listening to UDP
packets at a given address (IP address and port):</t>
<t><list style='symbols'>
<t>the attacker sends a message to a CoAP endpoint with
the given address as the fake source address,</t>
<t>the CoAP endpoint replies with a message to the given source
address,</t>
<t>the victim at the given address receives a UDP packet that
it interprets according to the rules of a different protocol.</t>
</list></t>
<t>This may be used to circumvent firewall rules that prevent direct
communication from the attacker to the victim, but happen to allow
communication from the CoAP endpoint (which may also host a valid role
in the other protocol) to the victim.</t>
<t>Also, CoAP endpoints may be the victim of a cross-protocol attack
generated through an endpoint of another UDP-based protocol such as
DNS. In both cases, attacks are possible if the security properties
of the endpoints rely on checking IP addresses (and firewalling off
direct attacks sent from outside using fake IP addresses). In
general, because of their lack of context, UDP-based protocols are
relatively easy targets for cross-protocol attacks.</t>
<t>Finally, CoAP URIs transported by other means could be used to
incite clients to send messages to endpoints of other protocols.</t>
<t>One mitigation against cross-protocol attacks is strict checking of
the syntax of packets received, combined with sufficient difference in
syntax. As an example, it might help if it were difficult to incite a
DNS server to send a DNS response that would pass the checks of a CoAP
endpoint. Unfortunately, the first two bytes of a DNS reply are an ID
that can be chosen by the attacker, which map into the interesting
part of the CoAP header, and the next two bytes are then interpreted
as CoAP's Message ID (i.e., any value is acceptable). The DNS count
words may be interpreted as multiple instances of a (non-existent, but
elective) CoAP option 0, or possibly as a Token. The echoed
query finally may be manufactured
by the attacker to achieve a desired effect on the CoAP endpoint; the
response added by the server (if any) might then just be interpreted
as added payload.</t>
<figure title="DNS Header vs. CoAP Message" anchor="dns-header">
<artwork type="drawing"><![CDATA[
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| ID | T, TKL, code
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|QR| Opcode |AA|TC|RD|RA| Z | RCODE | Message ID
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| QDCOUNT | (options 0)
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| ANCOUNT | (options 0)
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| NSCOUNT | (options 0)
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| ARCOUNT | (options 0)
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
]]></artwork>
</figure>
<t>In general, for any pair of protocols, one of the protocols can
very well have been designed in a way that enables an attacker to
cause the generation of replies that look like messages of the other
protocol. It is often much harder to ensure or prove the absence of
viable attacks than to generate examples that may not yet completely
enable an attack but might be further developed by more creative
minds. Cross-protocol attacks can therefore only be completely
mitigated if endpoints don't authorize actions desired by an attacker
just based on trusting the source IP address of a packet. Conversely,
a NoSec environment that completely relies on a firewall for CoAP
security not only needs to firewall off the CoAP endpoints but also
all other endpoints that might be incited to send UDP messages to CoAP
endpoints using some other UDP-based protocol.</t>
<t>In addition to the considerations above, the security
considerations for DTLS with respect to cross-protocol attacks apply.
E.g., if the same DTLS security association ("connection") is used to
carry data of multiple protocols, DTLS no longer provides protection
against cross-protocol attacks between these protocols.</t>
</section>
<section anchor="constrained-node-considerations"
title="Constrained node considerations">
<t>Implementers on constrained nodes often find themselves
without a good source of entropy <xref
target="RFC4086"/>. If that is the case, the node MUST NOT
be used for processes that require good entropy, such as key
generation. Instead, keys should be generated externally and
added to the device during manufacturing or
commissioning.</t>
<t>Due to their low processing power, constrained nodes are
particularly susceptible to timing attacks. Special care
must be taken in implementation of cryptographic
primitives.</t>
<t>Large numbers of constrained nodes will be installed in
exposed environments and will have little resistance to
tampering, including recovery of keying materials. This
needs to be considered when defining the scope of
credentials assigned to them. In particular, assigning a
shared key to a group of nodes may make any single
constrained node a target for subverting the entire
group.</t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="iana-considerations" title="IANA Considerations">
<!-- Based on RFC5226, RFC4395 and I-D.ietf-tsvwg-iana-ports-10. -->
<section anchor="coap-code-registry" title="CoAP Code Registries">
<t>This document defines two sub-registries for the values of
the Code field in the CoAP header within the Constrained
RESTful Environments (CoRE) Parameters ("CoRE Parameters")
registry.</t>
<t>Values in the two sub-registries are eight-bit
values notated as three decimal digits c.dd separated by a
period between the first and the second digit; the first digit
c is between 0 and 7 and denotes the code class; the second
and third digit dd denote a decimal number between 00 and 31
for the detail.</t>
<t>All Code values are assigned by sub-registries according to the following
ranges:
<list style="hanging" hangIndent="10">
<t hangText="0.00">Indicates an Empty message (see <xref
target="messages-and-endpoints"/>).</t>
<t hangText="0.01-0.31">Indicates a request. Values in this range are
assigned by the "CoAP Method Codes" sub-registry
(see <xref target="coap-code-registry-methods"/>).</t>
<t hangText="1.00-1.31">Reserved</t>
<t hangText="2.00-5.31">Indicates a response. Values in this range are
assigned by the "CoAP Response Codes" sub-registry
(see <xref target="coap-code-registry-responses"/>).</t>
<t hangText="6.00-7.31">Reserved</t>
</list>
</t>
<section anchor="coap-code-registry-methods" title="Method Codes">
<!-- Name of the sub-registry -->
<t>The name of the sub-registry is "CoAP Method Codes".</t>
<!-- Size, format and syntax of registry entries -->
<t>Each entry in the sub-registry must include the Method Code
in the range 0.01-0.31, the name of the method, and a reference to
the method's documentation.</t>
<!-- Initial assignments and reservations -->
<t>Initial entries in this sub-registry are as follows:</t>
<texttable anchor="tab-method-code-registry"
title="CoAP Method Codes">
<ttcol align="right">Code</ttcol>
<ttcol align="left">Name</ttcol>
<ttcol align="left">Reference</ttcol>
<c> 0.01</c><c>GET </c><c>&SELF;</c>
<c> 0.02</c><c>POST </c><c>&SELF;</c>
<c> 0.03</c><c>PUT </c><c>&SELF;</c>
<c> 0.04</c><c>DELETE</c><c>&SELF;</c>
</texttable>
<t>All other Method Codes are Unassigned.</t>
<!-- Review process -->
<t>The IANA policy for future additions to this sub-registry is
"IETF Review or IESG approval" as described in <xref target="RFC5226"/>.</t>
<!-- Review guidelines -->
<t>The documentation of a method code should specify the semantics
of a request with that code, including the following properties:
<list style="symbols">
<t>The response codes the method returns in the success case.</t>
<t>Whether the method is idempotent, safe, or both.</t>
</list>
</t>
</section>
<section anchor="coap-code-registry-responses" title="Response Codes">
<!-- Name of the sub-registry -->
<t>The name of the sub-registry is "CoAP Response Codes".</t>
<!-- Size, format and syntax of registry entries -->
<t>Each entry in the sub-registry must include the Response Code
in the range 2.00-5.31, a description of the Response Code, and a
reference to the Response Code's documentation.</t>
<!-- Initial assignments and reservations -->
<t>Initial entries in this sub-registry are as follows:</t>
<texttable anchor="tab-response-code-registry"
title="CoAP Response Codes">
<ttcol align="right">Code</ttcol>
<ttcol align="left">Description</ttcol>
<ttcol align="left">Reference</ttcol>
<!-- Success 64-95 -->
<c>2.01</c><c>Created </c><c>&SELF;</c>
<c>2.02</c><c>Deleted </c><c>&SELF;</c>
<c>2.03</c><c>Valid </c><c>&SELF;</c>
<c>2.04</c><c>Changed </c><c>&SELF;</c>
<c>2.05</c><c>Content </c><c>&SELF;</c>
<!-- Client Error 128-159 -->
<c>4.00</c><c>Bad Request </c><c>&SELF;</c>
<c>4.01</c><c>Unauthorized </c><c>&SELF;</c>
<c>4.02</c><c>Bad Option </c><c>&SELF;</c>
<c>4.03</c><c>Forbidden </c><c>&SELF;</c>
<c>4.04</c><c>Not Found </c><c>&SELF;</c>
<c>4.05</c><c>Method Not Allowed </c><c>&SELF;</c>
<c>4.06</c><c>Not Acceptable </c><c>&SELF;</c>
<c>4.12</c><c>Precondition Failed </c><c>&SELF;</c>
<c>4.13</c><c>Request Entity Too Large</c><c>&SELF;</c>
<c>4.15</c><c>Unsupported Content-Format </c><c>&SELF;</c>
<!-- Server Error 160-191 -->
<c>5.00</c><c>Internal Server Error </c><c>&SELF;</c>
<c>5.01</c><c>Not Implemented </c><c>&SELF;</c>
<c>5.02</c><c>Bad Gateway </c><c>&SELF;</c>
<c>5.03</c><c>Service Unavailable </c><c>&SELF;</c>
<c>5.04</c><c>Gateway Timeout </c><c>&SELF;</c>
<c>5.05</c><c>Proxying Not Supported </c><c>&SELF;</c>
</texttable>
<t>The Response Codes 3.00-3.31 are Reserved for future use. All other
Response Codes are Unassigned.</t>
<!-- Review process -->
<t>The IANA policy for future additions to this sub-registry is
"IETF Review or IESG approval" as described in <xref target="RFC5226"/>.</t>
<!-- Review guidelines -->
<t>The documentation of a response code should specify the semantics
of a response with that code, including the following properties:
<list style="symbols">
<t>The methods the response code applies to.</t>
<t>Whether payload is required, optional or not allowed.</t>
<t>The semantics of the payload. For example, the payload of a 2.05
(Content) response is a representation of the target resource; the
payload in an error response is a human-readable diagnostic
payload.</t>
<t>The format of the payload. For example, the format in a
2.05 (Content) response is indicated by the Content-Format Option;
the format of the payload in an error response is always
Net-Unicode text.</t>
<t>Whether the response is cacheable according to the freshness
model.</t>
<t>Whether the response is validatable according to the validation
model.</t>
<t>Whether the response causes a cache to mark responses stored
for the request URI as not fresh.</t>
</list>
</t>
</section>
</section>
<section anchor="option-number-registry"
title="Option Number Registry">
<!-- Name of the registry -->
<t>This document defines a sub-registry for the Option Numbers
used in CoAP options within the "CoRE Parameters" registry. The name
of the sub-registry is "CoAP Option Numbers".</t>
<!-- Size, format and syntax of registry entries -->
<t>Each entry in the sub-registry must include the Option Number, the name
of the option and a reference to the option's documentation.</t>
<!-- Initial assignments and reservations -->
<t>Initial entries in this sub-registry are as follows:</t>
<texttable anchor="tab-option-registry"
title="CoAP Option Numbers">
<ttcol align="right">Number</ttcol>
<ttcol align="left">Name</ttcol>
<ttcol align="left">Reference</ttcol>
<c> 0</c><c>(Reserved) </c><c>&SELF;</c>
<c> 1</c><c>If-Match </c><c>&SELF;</c>
<c> 3</c><c>Uri-Host </c><c>&SELF;</c>
<c> 4</c><c>ETag </c><c>&SELF;</c>
<c> 5</c><c>If-None-Match </c><c>&SELF;</c>
<c> 7</c><c>Uri-Port </c><c>&SELF;</c>
<c> 8</c><c>Location-Path </c><c>&SELF;</c>
<c>11</c><c>Uri-Path </c><c>&SELF;</c>
<c>12</c><c>Content-Format </c><c>&SELF;</c>
<c>14</c><c>Max-Age </c><c>&SELF;</c>
<c>15</c><c>Uri-Query </c><c>&SELF;</c>
<c>17</c><c>Accept </c><c>&SELF;</c>
<c>20</c><c>Location-Query </c><c>&SELF;</c>
<c>35</c><c>Proxy-Uri </c><c>&SELF;</c>
<c>39</c><c>Proxy-Scheme </c><c>&SELF;</c>
<c>60</c><c>Size1 </c><c>&SELF;</c>
<c>128</c><c>(Reserved) </c><c>&SELF;</c>
<c>132</c><c>(Reserved) </c><c>&SELF;</c>
<c>136</c><c>(Reserved) </c><c>&SELF;</c>
<c>140</c><c>(Reserved) </c><c>&SELF;</c>
</texttable>
<!-- Review process -->
<t>The IANA policy for future additions to this sub-registry is split into
three tiers as follows. The range of 0..255 is reserved for options
defined by the IETF (IETF Review or IESG approval). The range of 256..2047 is reserved
for commonly used options with public specifications (Specification
Required). The range of 2048..64999 is for all other options including
private or vendor specific ones, which undergo a Designated Expert
review to help ensure that the option semantics are defined correctly.
The option numbers between 65000 and 65535 inclusive are reserved
for experiments. They are not meant for vendor specific use
of any kind and MUST NOT be used in operational deployments.
</t>
<texttable anchor="tab-option-registry-policy"
title="CoAP Option Number Registry Policy">
<ttcol align='right'>Option Number</ttcol>
<ttcol align='left'>Policy [RFC5226]</ttcol>
<c>0..255</c>
<c>IETF Review or IESG approval</c>
<c>256..2047</c>
<c>Specification Required</c>
<c>2048..64999</c>
<c>Designated Expert</c>
<c>65000..65535</c>
<c>Reserved for experiments</c>
</texttable>
<!-- Review guidelines -->
<t>The documentation of an Option Number should specify the semantics
of an option with that number, including the following properties:
<list style="symbols">
<t>The meaning of the option in a request.</t>
<t>The meaning of the option in a response.</t>
<t>Whether the option is critical or elective, as determined by the
Option Number.</t>
<t>Whether the option is Safe-to-Forward, and, if yes, whether it is part of the
Cache-Key, as determined by the Option Number (see <xref
target="unsafe"/>).</t>
<t>The format and length of the option's value.</t>
<t>Whether the option must occur at most once or whether it can occur
multiple times.</t>
<t>The default value, if any. For a critical option with a default
value, a discussion on how the default value enables processing by
implementations not implementing the critical option (<xref
target="option-defaults"/>).</t>
</list>
</t>
</section>
<section anchor="media-type-registry" title="Content-Format Registry">
<!-- Name of the registry -->
<t>Internet media types are identified by a string, such as "application/xml"
<xref target="RFC2046"/>. In order to minimize the overhead of using
these media types to indicate the format of payloads, this document
defines a sub-registry for a subset of Internet media types to be used in
CoAP and assigns each, in combination with a content-coding, a
numeric identifier. The name of the sub-registry is
"CoAP Content-Formats", within the "CoRE Parameters" registry.</t>
<!-- Size, format and syntax of registry entries --> <t>Each entry in
the sub-registry must include the media type registered with IANA, the
numeric identifier in the range 0-65535 to be used for that media type
in CoAP, the content-coding associated with this identifier, and a
reference to a document describing what a payload with that media type
means semantically.</t>
<t>CoAP does not include a separate way to convey content-encoding information
with a request or response, and for that reason the content-encoding is
also specified for each identifier (if any). If multiple
content-encodings will be used with a media type, then a separate
Content-Format identifier for each is to be registered. Similarly, other parameters
related to an Internet media type, such as level, can be defined for a CoAP
Content-Format entry. </t>
<!-- Initial assignments and reservations -->
<t>Initial entries in this sub-registry are as follows:</t>
<texttable anchor="tab-mediatype" title="CoAP Content-Formats">
<ttcol align="left">Media type</ttcol>
<ttcol align="left">Encoding</ttcol>
<ttcol align="right">Id.</ttcol>
<ttcol align="left">Reference</ttcol>
<c>text/plain; charset=utf-8</c> <c>-</c> <c> 0</c><c><xref target="RFC2046"/><xref target="RFC3676"/><xref target="RFC5147"/></c>
<c>application/ link-format</c> <c>-</c> <c>40</c><c><xref target="RFC6690"/></c>
<c>application/xml</c> <c>-</c> <c>41</c><c><xref target="RFC3023"/></c>
<c>application/ octet-stream</c> <c>-</c> <c>42</c><c><xref target="RFC2045"/><xref target="RFC2046"/></c>
<c>application/exi</c> <c>-</c> <c>47</c><c><xref target="EXIMIME"/></c>
<c>application/json</c> <c>-</c> <c>50</c><c><xref target="RFC4627"/></c>
</texttable>
<t>The identifiers between 65000 and 65535 inclusive are reserved
for experiments. They are not meant for vendor specific use
of any kind and MUST NOT be used in operational deployments.
The identifiers between 256 and 9999 are reserved for
future use in IETF specifications (IETF review or IESG approval).
All other identifiers are Unassigned.</t>
<!-- Review process -->
<t>Because the name space of single-byte identifiers is so small, the
IANA policy for future additions in the range 0-255 inclusive to the
sub-registry is "Expert Review" as described in <xref target="RFC5226"/>.
The IANA policy for additions in the range 10000-64999 inclusive is "First
Come First Served" as described in <xref target="RFC5226"/>.</t>
<!-- Review guidelines -->
<t> In machine to machine applications, it is not expected that generic
Internet media types such as text/plain, application/xml or
application/octet-stream are useful for real applications in the long
term. It is recommended that M2M applications making use of CoAP will
request new Internet media types from IANA indicating semantic
information about how to create or parse a payload. For example, a Smart
Energy application payload carried as XML might request a more specific
type like application/se+xml or application/se-exi. </t>
</section>
<section anchor="uri-scheme-registration" title="URI Scheme Registration">
<t>This document requests the registration of the Uniform Resource
Identifier (URI) scheme "coap". The registration request complies with
<xref target="RFC4395"/>.
<list style="hanging">
<t hangText="URI scheme name."><vspace/>
coap</t>
<t hangText="Status."><vspace/>
Permanent.</t>
<t hangText="URI scheme syntax."><vspace/>
Defined in <xref target="uri-coap"/> of &SELF;.</t>
<t hangText="URI scheme semantics."><vspace/>
The "coap" URI scheme provides a way to identify resources that are
potentially accessible over the Constrained Application Protocol
(CoAP). The resources can be located by contacting the governing
CoAP server and operated on by sending CoAP requests to the server.
This scheme can thus be compared to the "http" URI scheme
<xref target="RFC2616"/>. See <xref target="uri"/> of &SELF; for the
details of operation.</t>
<t hangText="Encoding considerations."><vspace/>
The scheme encoding conforms to the encoding rules established for
URIs in <xref target="RFC3986"/>, i.e. internationalized and reserved
characters are expressed using UTF-8-based percent-encoding.</t>
<t hangText="Applications/protocols that use this URI scheme name.">
<vspace/>
The scheme is used by CoAP endpoints to access CoAP resources.</t>
<t hangText="Interoperability considerations."><vspace/>
None.</t>
<t hangText="Security considerations."><vspace/>
See <xref target="protocol-parsing-processing-uris"/> of &SELF;.</t>
<t hangText="Contact."><vspace/>
IETF Chair <chair@ietf.org></t>
<t hangText="Author/Change controller."><vspace/>
IESG <iesg@ietf.org></t>
<t hangText="References."><vspace/>
&SELF;</t>
</list>
</t>
</section>
<section anchor="coaps-uri-scheme-registration"
title="Secure URI Scheme Registration">
<t>This document requests the registration of the Uniform Resource
Identifier (URI) scheme "coaps". The registration request complies with
<xref target="RFC4395"/>.
<list style="hanging">
<t hangText="URI scheme name."><vspace/>
coaps</t>
<t hangText="Status."><vspace/>
Permanent.</t>
<t hangText="URI scheme syntax."><vspace/>
Defined in <xref target="uri-coaps"/> of &SELF;.</t>
<t hangText="URI scheme semantics."><vspace/> The "coaps" URI scheme
provides a way to identify resources that are potentially accessible
over the Constrained Application Protocol (CoAP) using Datagram
Transport Layer Security (DTLS) for transport security. The resources
can be located by contacting the governing CoAP server and operated on
by sending CoAP requests to the server. This scheme can thus be
compared to the "https" URI scheme <xref target="RFC2616"/>. See <xref
target="uri"/> of &SELF; for the details of operation.</t>
<t hangText="Encoding considerations."><vspace/>
The scheme encoding conforms to the encoding rules established for
URIs in <xref target="RFC3986"/>, i.e. internationalized and reserved
characters are expressed using UTF-8-based percent-encoding.</t>
<t hangText="Applications/protocols that use this URI scheme name.">
<vspace/>
The scheme is used by CoAP endpoints to access CoAP resources using
DTLS.</t>
<t hangText="Interoperability considerations."><vspace/>
None.</t>
<t hangText="Security considerations."><vspace/>
See <xref target="protocol-parsing-processing-uris"/> of &SELF;.</t>
<t hangText="Contact."><vspace/>
IETF Chair <chair@ietf.org></t>
<t hangText="Author/Change controller."><vspace/>
IESG <iesg@ietf.org></t>
<t hangText="References."><vspace/>
&SELF;</t>
</list>
</t>
</section>
<section anchor="port-registration"
title="Service Name and Port Number Registration">
<t>One of the functions of CoAP is resource discovery: a CoAP
client can ask a CoAP server about the resources offered by it
(see <xref target="discovery"/>). To enable resource discovery
just based on the knowledge of an IP address, the CoAP port for
resource discovery needs to be standardized.</t>
<t>IANA has assigned the port number &PORT;
and the service name "coap", in accordance with
<xref target="RFC6335"/>.</t>
<t>Besides unicast, CoAP can be used with both multicast and anycast.
<list style="hanging">
<t hangText="Service Name."><vspace/>
coap</t>
<t hangText="Transport Protocol."><vspace/>
UDP</t>
<t hangText="Assignee."><vspace/>
IESG <iesg@ietf.org></t>
<t hangText="Contact."><vspace/>
IETF Chair <chair@ietf.org></t>
<t hangText="Description."><vspace/>
Constrained Application Protocol (CoAP)</t>
<t hangText="Reference."><vspace/>
&SELF;</t>
<t hangText="Port Number."><vspace/>
&PORT;</t>
</list>
</t>
</section>
<section anchor="secure-port-registration"
title="Secure Service Name and Port Number Registration">
<t>CoAP resource discovery may also be provided using the DTLS-secured
CoAP "coaps" scheme. Thus the CoAP port for
secure resource discovery needs to be standardized.</t>
<t>This document requests the assignment of the port number &PORTS;
and the service name "coaps", in accordance with
<xref target="RFC6335"/>.</t>
<t>Besides unicast, DTLS-secured CoAP can be used with anycast.
<list style="hanging">
<t hangText="Service Name."><vspace/>
coaps</t>
<t hangText="Transport Protocol."><vspace/>
UDP</t>
<t hangText="Assignee."><vspace/>
IESG <iesg@ietf.org></t>
<t hangText="Contact."><vspace/>
IETF Chair <chair@ietf.org></t>
<t hangText="Description."><vspace/>
DTLS-secured CoAP</t>
<t hangText="Reference."><vspace/>
&SELF;</t>
<t hangText="Port Number."><vspace/>
&PORTS;</t>
</list>
</t>
</section>
<section anchor="multicast-addresses"
title="Multicast Address Registration">
<t><xref target="multicast"/>, "Multicast CoAP", defines the use of
multicast. This document requests the assignment of the following
multicast addresses for use by CoAP nodes:<list style="hanging">
<t hangText="IPv4">-- "All CoAP Nodes" address
&MULTICASTv4;, from the IPv4 Multicast Address Space
Registry.
As the address is used for discovery that may span beyond
a single network, it should come from the Internetwork
Control Block (224.0.1.x, RFC 5771).</t>
<t hangText="IPv6">-- "All CoAP Nodes" address
&MULTICASTv6;, from the IPv6 Multicast Address Space
Registry, in the Variable Scope Multicast Addresses
space (RFC3307). Note that there is a distinct multicast address
for each scope that interested CoAP nodes should listen
to; CoAP needs the Link-Local and Site-Local scopes only.
The address should be of the form FF0x::nn, where nn is a
single byte, to ensure good compression of the local-scope
address with <xref target="RFC6282"/>.</t>
</list></t>
<t>[The explanatory text to be removed upon allocation of the
addresses, except for the note about the distinct multicast
addresses.]</t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Acknowledgements">
<t>Brian Frank was a contributor to and co-author of previous drafts of this
specification.
</t>
<t>Special thanks to Peter Bigot, Esko Dijk and Cullen Jennings
for substantial contributions to the ideas and text in the document, along
with countless detailed reviews and discussions.</t>
<t>Thanks to Ed Beroset, Angelo P. Castellani, Gilbert Clark,
Robert Cragie, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas
Fossati, Tom Herbst, Richard Kelsey, Ari Keranen, Matthias
Kovatsch, Salvatore Loreto, Kerry Lynn, Alexey Melnikov, Guido
Moritz, Petri Mutka, Colin O'Flynn, Charles Palmer, Adriano
Pezzuto, Robert Quattlebaum, Akbar Rahman, Eric Rescorla, Dan
Romascanu, David Ryan, Szymon Sasin, Michael Scharf, Dale Seed,
Robby Simpson, Peter van der Stok, Michael Stuber, Linyi Tian,
Gilman Tolle, Matthieu Vial and Alper Yegin for helpful comments
and discussions that have shaped the document. Special thanks
also to the IESG reviewers, Adrian Farrel, Martin Stiemerling,
Pete Resnick, Richard Barnes, Sean Turner, Spencer Dawkins,
Stephen Farrell, and Ted Lemon,
who contributed in-depth reviews.</t>
<t>Some of the text has been
borrowed from the working documents of the IETF httpbis working group.</t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC0768;
&RFC2045;
&RFC2046;
&RFC2616;
&RFC2119;
&RFC4279;
&RFC3023;
&RFC3676;
&RFC3629;
&RFC3986;
&RFC6347;
&RFC4395;
&RFC5147;
&RFC5198;
&RFC5226;
&RFC5234;
&RFC5246;
&RFC5480;
&RFC5280;
&RFC5785;
&RFC5952;
&RFC5988;
&RFC6066;
&RFC6690;
&I-D.ietf-tls-oob-pubkey;
&RFC6920;
&I-D.mcgrew-tls-aes-ccm-ecc;
</references>
<references title="Informative References">
&RFC0020;
&RFC2560;
&RFC2818;
&RFC4086;
&RFC4492;
&RFC4627;
<reference anchor="REST" target="http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf">
<front>
<title>Architectural Styles and the Design of Network-based Software Architectures</title>
<author initials="R." surname="Fielding" fullname="Roy Fielding">
<organization>University of California, Irvine</organization>
</author>
<date year="2000"/>
</front>
<seriesInfo name="Ph.D." value="Dissertation, University of California, Irvine"/>
<format type="PDF" target="http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf"/>
</reference>
&RFC3264;
&RFC3542;
&RFC6120;
&RFC4944;
&RFC4821;
&I-D.ietf-core-block;
&I-D.ietf-core-observe;
&I-D.ietf-core-groupcomm;
<reference anchor="EUI64" target="http://standards.ieee.org/regauth/oui/tutorials/EUI64.html">
<front>
<title>GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER (EUI-64) REGISTRATION AUTHORITY</title>
<author><organization/></author><date month='April' day='23' year='2010' />
</front>
</reference>
<reference anchor="EXIMIME" target="http://www.w3.org/TR/2009/CR-exi-20091208/#mediaTypeRegistration">
<front>
<title>Efficient XML Interchange (EXI) Format 1.0</title>
<author><organization/></author><date month='December' day='08' year='2009' />
</front>
</reference>
<reference anchor="W3CXMLSEC" target="http://www.w3.org/2011/xmlsec-pag/pagreport.html">
<front>
<title>Report of the XML Security PAG</title>
<author initials="R." surname="Wenning" fullname="Rigo Wenning">
<organization>PAG Chair</organization>
</author>
<date year="2012" month="October" day="15"/>
</front>
</reference>
&RFC6090;
&RFC6655;
&RFC6282;
&RFC6335;
&RFC5489;
&I-D.ietf-tls-multiple-cert-status-extension;
&RFC0793;
&RFC0792;
&RFC4443;
&RFC5405;
&RFC3828;
&RFC6936;
&I-D.ietf-lwig-terminology;
&I-D.allman-tcpm-rto-consider;
&I-D.castellani-core-http-mapping;
&I-D.bormann-core-ipsec-for-coap;
&I-D.bormann-coap-misc;
<reference anchor="HHGTTG">
<front>
<title>The Hitchhiker's Guide to the Galaxy</title>
<author initials="D." surname="Adams" fullname="Douglas Adams">
<organization></organization>
</author>
<date year="1979" month="October" day="12"/>
</front>
</reference>
</references>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="examples" title="Examples">
<t>This section gives a number of short examples with message flows
for GET requests. These examples demonstrate the basic operation, the
operation in the presence of retransmissions, and multicast.</t>
<t><xref target="fig-example-1"/> shows a basic GET
request causing a &pb; response: The client sends a Confirmable
GET request for the resource coap://server/temperature to the server
with a Message ID of 0x7d34. The request includes one Uri-Path Option
(Delta 0 + 11 = 11, Length 11, Value "temperature"); the Token is
left empty. This request is a total of 16
bytes long. A 2.05 (Content) response is returned in the Acknowledgement
message that acknowledges the Confirmable request, echoing both the
Message ID 0x7d34 and the empty Token value. The response
includes a Payload of "22.3 C" and is 11 bytes long.</t>
<figure anchor="fig-example-1"
title="Confirmable request; piggy-backed response"> <!--XML2RFC is stupid-->
<artwork type="example"><![CDATA[
Client Server
| |
| |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d34)
| GET | Uri-Path: "temperature"
| |
| |
|<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34)
| 2.05 | Payload: "22.3 C"
| |
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 | 0 | GET=1 | MID=0x7d34 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 11 | 11 | "temperature" (11 B) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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 | 2.05=69 | MID=0x7d34 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| "22.3 C" (6 B) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>
<xref target="fig-example-1a"/> shows a similar example, but with the
inclusion of an non-empty Token (Value 0x20) in the request and the response,
increasing the sizes to 17 and 12 bytes, respectively.
</t>
<figure anchor="fig-example-1a"
title="Confirmable request; piggy-backed response"> <!--XML2RFC is stupid-->
<artwork type="example"><![CDATA[
Client Server
| |
| |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d35)
| GET | Token: 0x20
| | Uri-Path: "temperature"
| |
| |
|<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d35)
| 2.05 | Token: 0x20
| | Payload: "22.3 C"
| |
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 | MID=0x7d35 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x20 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 11 | 11 | "temperature" (11 B) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
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 | 1 | 2.05=69 | MID=0x7d35 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0x20 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| "22.3 C" (6 B) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>In <xref target="fig-example-2"/>, the
Confirmable GET request is lost. After ACK_TIMEOUT seconds,
the client retransmits the request, resulting in a &pb; response
as in the previous example.</t>
<figure anchor="fig-example-2"
title="Confirmable request (retransmitted); piggy-backed response"> <!--XML2RFC is stupid-->
<artwork type="example"><![CDATA[
Client Server
| |
| |
+----X | Header: GET (T=CON, Code=0.01, MID=0x7d36)
| GET | Token: 0x31
| | Uri-Path: "temperature"
TIMEOUT |
| |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d36)
| GET | Token: 0x31
| | Uri-Path: "temperature"
| |
| |
|<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d36)
| 2.05 | Token: 0x31
| | Payload: "22.3 C"
| |
]]></artwork>
</figure>
<t>In <xref target="fig-example-3"/>, the first
Acknowledgement message from the server to the client is lost. After
ACK_TIMEOUT seconds, the client retransmits the request.</t>
<figure anchor="fig-example-3"
title="Confirmable request; piggy-backed response (retransmitted)"> <!--XML2RFC is stupid-->
<artwork type="example"><![CDATA[
Client Server
| |
| |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d37)
| GET | Token: 0x42
| | Uri-Path: "temperature"
| |
| |
| X----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37)
| 2.05 | Token: 0x42
| | Payload: "22.3 C"
TIMEOUT |
| |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d37)
| GET | Token: 0x42
| | Uri-Path: "temperature"
| |
| |
|<-----+ Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37)
| 2.05 | Token: 0x42
| | Payload: "22.3 C"
| |
]]></artwork>
</figure>
<t>In <xref target="fig-example-4"/>, the server
acknowledges the Confirmable request and sends a 2.05 (Content) response
separately in a Confirmable message. Note that the Acknowledgement
message and the Confirmable response do not necessarily arrive in the same
order as they were sent. The client acknowledges the Confirmable
response.</t>
<figure anchor="fig-example-4"
title="Confirmable request; separate response"> <!--XML2RFC is stupid-->
<artwork type="example"><![CDATA[
Client Server
| |
| |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d38)
| GET | Token: 0x53
| | Uri-Path: "temperature"
| |
| |
|<- - -+ Header: (T=ACK, Code=0.00, MID=0x7d38)
| |
| |
|<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7b)
| 2.05 | Token: 0x53
| | Payload: "22.3 C"
| |
| |
+- - ->| Header: (T=ACK, Code=0.00, MID=0xad7b)
| |
]]></artwork>
</figure>
<t><xref target="fig-example-5"/> shows an example
where the client loses its state (e.g., crashes and is rebooted) right after
sending a Confirmable request,
so the &npb; response arriving some time later comes unexpected. In
this case, the client rejects the Confirmable response with a Reset
message. Note that the unexpected ACK is silently ignored.</t>
<figure anchor="fig-example-5"
title="Confirmable request; separate response (unexpected)"> <!--XML2RFC is stupid-->
<artwork type="example"><![CDATA[
Client Server
| |
| |
+----->| Header: GET (T=CON, Code=0.01, MID=0x7d39)
| GET | Token: 0x64
| | Uri-Path: "temperature"
CRASH |
| |
|<- - -+ Header: (T=ACK, Code=0.00, MID=0x7d39)
| |
| |
|<-----+ Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7c)
| 2.05 | Token: 0x64
| | Payload: "22.3 C"
| |
| |
+- - ->| Header: (T=RST, Code=0.00, MID=0xad7c)
| |
]]></artwork>
</figure>
<t><xref target="fig-example-6"/> shows a basic GET
request where the request and the response are Non-confirmable, so both may
be lost without notice.</t>
<figure anchor="fig-example-6"
title="Non-confirmable request; Non-confirmable response">
<artwork type="example"><![CDATA[
Client Server
| |
| |
+----->| Header: GET (T=NON, Code=0.01, MID=0x7d40)
| GET | Token: 0x75
| | Uri-Path: "temperature"
| |
| |
|<-----+ Header: 2.05 Content (T=NON, Code=2.05, MID=0xad7d)
| 2.05 | Token: 0x75
| | Payload: "22.3 C"
| |
]]></artwork>
</figure>
<t>In <xref target="fig-example-7"/>, the client
sends a Non-confirmable GET request to a multicast address: all nodes
in link-local scope. There are 3 servers on the link: A, B and C.
Servers A and B have a matching resource, therefore they send back a
Non-confirmable 2.05 (Content) response. The response sent by B is lost.
C does not have matching response, therefore it sends a Non-confirmable
4.04 (Not Found) response.</t>
<figure anchor="fig-example-7"
title="Non-confirmable request (multicast); Non-confirmable response">
<artwork type="example"><![CDATA[
Client ff02::1 A B C
| | | | |
| | | | |
+------>| | | | Header: GET (T=NON, Code=0.01, MID=0x7d41)
| GET | | | | Token: 0x86
| | | | Uri-Path: "temperature"
| | | |
| | | |
|<------------+ | | Header: 2.05 (T=NON, Code=2.05, MID=0x60b1)
| 2.05 | | | Token: 0x86
| | | | Payload: "22.3 C"
| | | |
| | | |
| X------------+ | Header: 2.05 (T=NON, Code=2.05, MID=0x01a0)
| 2.05 | | | Token: 0x86
| | | | Payload: "20.9 C"
| | | |
| | | |
|<------------------+ Header: 4.04 (T=NON, Code=4.04, MID=0x952a)
| 4.04 | | | Token: 0x86
| | | |
]]></artwork>
</figure>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section anchor="uri-examples" title="URI Examples">
<t>The following examples demonstrate different sets of Uri options, and
the result after constructing an URI from them. In addition to the
options, <xref target="uri-constructing"/> refers to the destination IP
address and port, but not all paths of the algorithm cause the
destination IP address and port to be included in the URI.<list
style="symbols">
<t>Input:<list style="empty">
<t>Destination IP Address = [2001:db8::2:1]<vspace/> Destination
UDP Port = &PORT;</t>
</list>Output:<list style="empty">
<t>coap://[2001:db8::2:1]/</t>
</list></t>
<t>Input:<list style="empty">
<t>Destination IP Address = [2001:db8::2:1]<vspace/>Destination
UDP Port = &PORT;<vspace/>Uri-Host = "example.net"</t>
</list>Output:<list style="empty">
<t>coap://example.net/</t>
</list></t>
<t>Input:<list style="empty">
<t>Destination IP Address = [2001:db8::2:1]<vspace/>Destination
UDP Port = &PORT;<vspace/>Uri-Host =
"example.net"<vspace/>Uri-Path = ".well-known"<vspace/>Uri-Path
= "core"</t>
</list>Output:<list style="empty">
<t>coap://example.net/.well-known/core</t>
</list></t>
<t>Input:<list style="empty">
<t>Destination IP Address = [2001:db8::2:1]<vspace/>Destination
UDP Port = &PORT;<vspace/>Uri-Host =
"xn--18j4d.example"<vspace/>Uri-Path = the string composed of
the Unicode characters U+3053 U+3093 U+306b U+3061 U+306f,
usually represented in UTF-8 as E38193E38293E381ABE381A1E381AF
hexadecimal</t>
</list>Output:<list style="empty">
<t>coap://xn--18j4d.example/%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF</t>
<t>(The line break has been inserted for readability; it is not
part of the URI.)</t>
</list></t>
<t>Input:<list style="empty">
<t>Destination IP Address = 198.51.100.1<vspace/>Destination UDP
Port = 61616<vspace/>Uri-Path = ""<vspace/>Uri-Path =
"/"<vspace/>Uri-Path = ""<vspace/>Uri-Path =
""<vspace/>Uri-Query = "//"<vspace/>Uri-Query = "?&"</t>
</list>Output:<list style="empty">
<t>coap://198.51.100.1:61616//%2F//?%2F%2F&?%26</t>
</list></t>
</list>
</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Changelog">
<t>
(To be removed by RFC editor before publication.)
</t>
<t>Changes from ietf-17 to ietf-18: Address comments from the IESG reviews.
<list style="symbols">
<t>Accept is now critical.</t>
<t>Add Size1 option for 4.13 responses.</t>
</list>
</t>
<t>Changes from ietf-15 to ietf-16: Address comments from the IESG reviews.
These should not impact interoperability.
<list style="symbols">
<t>Clarify that once there has been an empty ACK, all
further ACKs to the same message also must be empty (#301).</t>
<t>Define Cache-key properly (#302).</t>
<t>Clarify that ACKs don't get retransmitted, the CONs do (#303).</t>
<t>Clarify: NON is like separate for CON (#304).</t>
<t>Don't use decimal response codes, keep the 3+5 structure
throughout (#305).</t>
<t>RFC 2119 usage in 4.5 (#306) and 8.2 (#307).</t>
<t>Ensure all protocol reactions to reserved or
prohibited values are defined (#308).</t>
<t>URI matching rules may be scheme specific (#309).</t>
<t>Don't dally beyond MAX_TRANSMIT_SPAN during
retransmission (#310).</t>
<t>More about selecting a token length for anti-spoofing (#311).</t>
<t>Discuss spoofing ACKs (#312).</t>
<t>Qualify partial discard strategy implementation note as UDP
only (#313).</t>
<t>Explicitly point out that UDP and DTLS don't mix (#314).</t>
<t>Point out security consideration re URIs and access
control (#315).</t>
<t>Point to RFC5280 section 6 (#316).</t>
<t>Add a paragraph about cert status checking (#317).</t>
<t>RSA is out, ECDHE is in for cert-with-PSK, too (#318).</t>
<t>Point out that requests and responses don't always come
in pairs (#319).</t>
<t>Clarify when there is a need for Unicode normalization (#320).</t>
<t>Point out that Uri-Host doesn't handle user-part (#321).</t>
<t>Clarify the use of non-FQDN Authority Names in certificates.</t>
<t>Numerous editorial improvements and clarifications. </t>
</list>
</t>
<t>Changes from ietf-14 to ietf-15: Address comments from IETF
last-call, mostly implementation notes and editorial improvements.
These should not impact interoperability.
<list style="symbols">
<t>Clarify bytes/characters and UTF-8/ASCII in
"Decomposing URIs into Options" (#282).</t>
<t>Make reference to ECC/CCM DTLS ciphersuite
normative (#286).</t>
<t>Add a quick warning that bytewise scanning for a
payload marker is not a good idea (#287).</t>
<t>Make reference to PROBING_RATE explicit for
saturation discussion (#288).</t>
<t>Mention PROCESSING_DELAY when discussion
piggy-backing (#290).</t>
<t>Various editorial nits: Clarify use of noun
"service" (#283), Reference terminology from
lwig-terminology (#284), make reference to HTTP terms
more explicit (#285), add a forward reference to
5.9.2.9 (#289), 8 kbit/s is not "conservative"
(#291).</t>
<t>Add description of resource depletion attack (#292).</t>
<t>Add description of DoS attack on congestion control
(#293).</t>
<t>Add discussion of using non-trivial token for
protecting against hijacking (#294).</t>
<t>Clarify implementation note about per-destination Message ID generation.</t>
</list>
</t>
<t>Changed from ietf-13 to ietf-14:
<list style="symbols">
<t>Made Accept option non-repeatable.</t>
<t>Clarified that Safe options in a 2.03 Valid
response update the cache.</t>
<t>Clarified that payload sniffing is acceptable only if
no Content-Format was supplied.</t>
<t>Clarified URI examples (<xref target="uri-examples"/>).</t>
<t>Numerous editorial improvements and clarifications. </t>
</list>
</t>
<t>Changed from ietf-12 to ietf-13:
<list style="symbols">
<t>Simplified message format.<list style="symbols">
<t>Removed the OC (Option Count) field in the CoAP Header.</t>
<t>Changed the End-of-Options Marker into the Payload Marker.</t>
<t>Changed the format of Options: use 4 bits for option length
and delta; insert one or two additional bytes after the option
header if necessary.</t>
<t>Promoted the Token Option to a field following the CoAP Header.</t>
</list></t>
<t>Clarified when a payload is a diagnostic payload (#264).</t>
<t>Moved IPsec discussion to separate draft (#262).</t>
<t>Added a reference to a separate draft on reverse-proxy
URI embedding (#259).</t>
<t>Clarified the use of ETags and of 2.03 responses (#265,
#254, #256).</t>
<t>Added reserved Location-* numbers and clarified Location-*.</t>
<t>Added Proxy-Scheme proposal.</t>
<t>Clarified terms such as content negotiation, selected
representation, representation-format, message format error.</t>
<t>Numerous clarifications and a few bugfixes.</t>
</list>
</t>
<t>Changed from ietf-11 to ietf-12:
<list style="symbols">
<t>Extended options to support lengths of up to 1034 bytes (#202).</t>
<t>Added new Jump mechanism for options and removed Fenceposting (#214).</t>
<t>Added new IANA option number registration policy (#214).</t>
<t>Added Proxy Unsafe/Safe and Cache-Key masking to option numbers (#241).</t>
<t>Re-numbered option numbers to use Unsafe/Safe and Cache-Key compliant numbers (#241).</t>
<t>Defined NSTART and restricted the value to 1 with a MUST (#215).</t>
<t>Defined PROBING_RATE and set it to 1 Byte/second (#215).</t>
<t>Defined DEFAULT_LEISURE (#246).</t>
<t>Renamed Content-Type into Content-Format, and Media Type registry into Content-Format registry.</t>
<t>A large number of small editorial changes, clarifications and improvements have been made.</t>
</list>
</t>
<t>Changed from ietf-10 to ietf-11:
<list style="symbols">
<t>Expanded section 4.8 on Transmission Parameters, and used the
derived values defined there (#201). Changed parameter names to
be shorter and more to the point.</t>
<t>Several more small editorial changes, clarifications and improvements have been made.</t>
</list>
</t>
<t>Changed from ietf-09 to ietf-10:
<list style="symbols">
<t>Option deltas are restricted to 0 to 14; the option delta 15 is used exclusively for the end-of-options marker (#239).</t>
<t>Option numbers that are a multiple of 14 are not reserved, but are required to have an empty default value (#212).</t>
<t>Fixed misleading language that was introduced in 5.10.2 in coap-07 re Uri-Host and Uri-Port (#208).</t>
<t>Segments and arguments can have a length of zero characters (#213).</t>
<t>The Location-* options describe together describe one location. The location is a relative URI, not an "absolute path URI" (#218).</t>
<t>The value of the Location-Path Option must not be '.' or '..' (#218).</t>
<t>Added a sentence on constructing URIs from Location-* options (#231).</t>
<t>Reserved option numbers for future Location-* options (#230).</t>
<t>Fixed response codes with payload inconsistency (#233).</t>
<t>Added advice on default values for critical options (#207).</t>
<t>Clarified use of identifiers in RawPublicKey Mode Provisioning (#222).</t>
<t>Moved "Securing CoAP" out of the "Security Considerations" (#229).</t>
<t>Added "All CoAP Nodes" multicast addresses to "IANA Considerations" (#216).</t>
<t>Over 100 small editorial changes, clarifications and improvements have been made.</t>
</list>
</t>
<t>Changed from ietf-08 to ietf-09:
<list style="symbols">
<t>Improved consistency of statements about RST on NON: RST is a valid response to a NON message (#183).</t>
<t>Clarified that the protocol constants can be configured for specific application environments.</t>
<t>Added implementation note recommending piggy-backing whenever possible (#182). </t>
<t>Added a content-encoding column to the media type registry (#181).</t>
<t>Minor improvements to Appendix D.</t>
<t>Added text about multicast response suppression (#177).</t>
<t>Included the new End-of-options Marker (#176).</t>
<t>Added a reference to draft-ietf-tls-oob-pubkey and updated the RPK text accordingly.</t>
</list>
</t>
<t>Changed from ietf-07 to ietf-08:
<list style="symbols">
<t>Clarified matching rules for messages (#175)</t>
<t>Fixed a bug in Section 8.2.2 on Etags (#168)</t>
<t>Added an IP address spoofing threat analysis contribution (#167)</t>
<t>Re-focused the security section on raw public keys (#166)</t>
<t>Added an 4.06 error to Accept (#165)</t>
</list>
</t>
<t>Changed from ietf-06 to ietf-07:
<list style="symbols">
<t>application/link-format added to Media types registration (#160)</t>
<t>Moved content-type attribute to the document from link-format.</t>
<t>Added coaps scheme and DTLS-secured CoAP default port (#154)</t>
<t>Allowed 0-length Content-type options (#150)</t>
<t>Added congestion control recommendations (#153)</t>
<t>Improved text on PUT/POST response payloads (#149)</t>
<t>Added an Accept option for content-negotiation (#163)</t>
<t>Added If-Match and If-None-Match options (#155)</t>
<t>Improved Token Option explanation (#147)</t>
<t>Clarified mandatory to implement security (#156)</t>
<t>Added first come first server policy for 2-byte Media type codes (#161)</t>
<t>Clarify matching rules for messages and tokens (#151)</t>
<t>Changed OPTIONS and TRACE to always return 501 in HTTP-CoAP mapping (#164)</t>
</list>
</t>
<t>Changed from ietf-05 to ietf-06:
<list style="symbols">
<t>HTTP mapping section improved with the minimal protocol standard text for CoAP-HTTP
and HTTP-CoAP forward proxying (#137).</t>
<t>Eradicated percent-encoding by including one Uri-Query Option per &-delimited argument in a query.</t>
<t>Allowed RST message in reply to a NON message with unexpected token (#135).</t>
<t>Cache Invalidation only happens upon successful responses (#134).</t>
<t>50% jitter added to the initial retransmit timer (#142).</t>
<t>DTLS cipher suites aligned with ZigBee IP, DTLS clarified as default CoAP security mechanism (#138, #139)</t>
<t>Added a minimal reference to draft-kivinen-ipsecme-ikev2-minimal (#140).</t>
<t>Clarified the comparison of UTF-8s (#136).</t>
<t>Minimized the initial media type registry (#101).</t>
</list>
</t>
<t>Changed from ietf-04 to ietf-05:
<list style="symbols">
<t>Renamed Immediate into &Pb; and Deferred into &Npb; --
should finally end the confusion on what this is about.</t>
<t>GET requests now return a 2.05 (Content) response instead of 2.00 (OK) response (#104).</t>
<t>Added text to allow 2.02 (Deleted) responses in reply to POST requests (#105).</t>
<t>Improved message deduplication rules (#106).</t>
<t>Section added on message size implementation considerations (#103).</t>
<t>Clarification made on human readable error payloads (#109).</t>
<t>Definition of CoAP methods improved (#108).</t>
<t>Max-Age removed from requests (#107).</t>
<t>Clarified uniqueness of tokens (#112).</t>
<t>Location-Query Option added (#113).</t>
<t>ETag length set to 1-8 bytes (#123).</t>
<t>Clarified relation between elective/critical and option numbers (#110).</t>
<t>Defined when to update Version header field (#111).</t>
<t>URI scheme registration improved (#102).</t>
<t>Added review guidelines for new CoAP codes and numbers.</t>
</list>
</t>
<t>Changes from ietf-03 to ietf-04:
<list style="symbols">
<t>Major document reorganization (#51, #63, #71, #81).</t>
<t>Max-age length set to 0-4 bytes (#30).</t>
<t>Added variable unsigned integer definition (#31).</t>
<t>Clarification made on human readable error payloads (#50).</t>
<t>Definition of POST improved (#52).</t>
<t>Token length changed to 0-8 bytes (#53).</t>
<t>Section added on multiplexing CoAP, DTLS and STUN (#56).</t>
<t>Added cross-protocol attack considerations (#61).</t>
<t>Used new Immediate/Deferred response definitions (#73).</t>
<t>Improved request/response matching rules (#74).</t>
<t>Removed unnecessary media types and added recommendations for their use in M2M (#76).</t>
<t>Response codes changed to base 32 coding, new Y.XX naming (#77).</t>
<t>References updated as per AD review (#79).</t>
<t>IANA section completed (#80).</t>
<t>Proxy-Uri Option added to disambiguate between proxy and non-proxy requests (#82).</t>
<t>Added text on critical options in cached states (#83).</t>
<t>HTTP mapping sections improved (#88).</t>
<t>Added text on reverse proxies (#72).</t>
<t>Some security text on multicast added (#54).</t>
<t>Trust model text added to introduction (#58, #60).</t>
<t>AES-CCM vs. AES-CCB text added (#55).</t>
<t>Text added about device capabilities (#59).</t>
<t>DTLS section improvements (#87).</t>
<t>Caching semantics aligned with RFC2616 (#78).</t>
<t>Uri-Path Option split into multiple path segments.</t>
<t>MAX_RETRANSMIT changed to 4 to adjust for RESPONSE_TIME = 2.</t>
</list>
</t>
<t>Changes from ietf-02 to ietf-03:
<list style="symbols">
<t>Token Option and related use in asynchronous requests added (#25).</t>
<t>CoAP specific error codes added (#26).</t>
<t>Erroring out on unknown critical options changed to a MUST (#27).</t>
<t>Uri-Query Option added.</t>
<t>Terminology and definitions of URIs improved. </t>
<t>Security section completed (#22).</t>
</list>
</t>
<t>Changes from ietf-01 to ietf-02:
<list style="symbols">
<t>Sending an error on a critical option clarified (#18).</t>
<t>Clarification on behavior of PUT and idempotent operations (#19).</t>
<t>Use of Uri-Authority clarified along with server processing rules; Uri-Scheme Option removed (#20, #23).</t>
<t>Resource discovery section removed to a separate CoRE Link Format draft (#21).</t>
<t>Initial security section outline added.</t>
</list>
</t>
<t>Changes from ietf-00 to ietf-01:
<list style="symbols">
<t>New cleaner transaction message model and header (#5).</t>
<t>Removed subscription while being designed (#1).</t>
<t>Section 2 re-written (#3).</t>
<t>Text added about use of short URIs (#4).</t>
<t>Improved header option scheme (#5, #14).</t>
<t>Date option removed whiled being designed (#6).</t>
<t>New text for CoAP default port (#7).</t>
<t>Completed proxying section (#8).</t>
<t>Completed resource discovery section (#9).</t>
<t>Completed HTTP mapping section (#10).</t>
<t>Several new examples added (#11).</t>
<t>URI split into 3 options (#12).</t>
<t>MIME type defined for link-format (#13, #16).</t>
<t>New text on maximum message size (#15).</t>
<t>Location Option added.</t>
</list>
</t>
<t>Changes from shelby-01 to ietf-00:
<list style="symbols">
<t>Removed the TCP binding section, left open for the future.</t>
<t>Fixed a bug in the example.</t>
<t>Marked current Sub/Notify as (Experimental) while under WG discussion.</t>
<t>Fixed maximum datagram size to 1280 for both IPv4 and IPv6 (for CoAP-CoAP proxying to work).</t>
<t>Temporarily removed the Magic Byte header as TCP is no longer included as a binding.</t>
<t>Removed the Uri-code Option as different URI encoding schemes are being discussed.</t>
<t>Changed the rel= field to desc= for resource discovery.</t>
<t>Changed the maximum message size to 1024 bytes to allow for IP/UDP headers.</t>
<t>Made the URI slash optimization and method idempotence MUSTs</t>
<t>Minor editing and bug fixing.</t>
</list>
</t>
<t>Changes from shelby-00 to shelby-01:
<list style="symbols">
<t>Unified the message header and added a notify message type.</t>
<t>Renamed methods with HTTP names and removed the NOTIFY method.</t>
<t>Added a number of options field to the header.</t>
<t>Combines the Option Type and Length into an 8-bit field.</t>
<t>Added the magic byte header.</t>
<t>Added new ETag Option.</t>
<t>Added new Date Option.</t>
<t>Added new Subscription Option.</t>
<t>Completed the HTTP Code - CoAP Code mapping table appendix.</t>
<t>Completed the Content-type Identifier appendix and tables.</t>
<t>Added more simplifications for URI support.</t>
<t>Initial subscription and discovery sections.</t>
<t>A Flag requirements simplified.</t>
</list>
</t>
</section>
</back>
</rfc>
<!-- LocalWords: CoAP IP URI URIs CoRE datagram Confirmable TLV DTLS
-->
<!-- LocalWords: MTU IPsec microcontrollers LoWPAN kbit RESTful IPv
-->
<!-- LocalWords: unicast ACK MID RST cacheable ETag IEEE AES CCM
-->
<!-- LocalWords: NATs TLS PSK requesters proxying proxied backoff
-->
<!-- LocalWords: subcomponent acknowledgement acknowledgements SCTP
-->
<!-- LocalWords: retransmission responder retransmits RETRANSMIT
-->
<!-- LocalWords: retransmitted retransmissions retransmit cleartext
-->
<!-- LocalWords: scalability wildcards parsers encodable Uri UTF
-->
<!-- LocalWords: parameterizing metadata parameterize fenceposts
-->
<!-- LocalWords: retransmitting optimizations cacheability NoSec
-->
<!-- LocalWords: revalidating encodings discoverable demultiplexing
-->
<!-- LocalWords: datagrams unescaped API APIs firewalling DNS IANA
-->
<!-- LocalWords: validatable fenceposting Interoperability Kidekuja
-->
<!-- LocalWords: Universitaet Sensinode Vuokatti Hartke TZI Bormann
-->
<!-- LocalWords: Postfach Carsten lossy multicast UDP coap Zach Acknowledgement
-->
<!-- LocalWords: TCP templated CoAP's checksum coaps ABNF namespace
-->
<!-- LocalWords: revalidate RawPublicKey nonces SNI speakable XMPP
-->
<!-- LocalWords: barcode SubjectAltName RECVPKTINFO Posix lookup
-->
<!-- LocalWords: PreSharedKey wakeup IETF Internetwork NSTART IESG
-->
<!-- LocalWords: liveness deduplication UnSafe NoCacheKey uint RSTs
-->
<!-- LocalWords: namespacing ETags implementers cryptographically
-->
<!-- LocalWords: Assignee anycast RTT MSL interoperability ICMP
-->
<!-- LocalWords: cryptographic
-->
| PAFTECH AB 2003-2026 | 2026-04-21 20:15:47 |