source: draft-ietf-lwig-coap.xml

Last change on this file was 63, checked in by cabo@…, 4 years ago

Posted lwig-coap-03.

File size: 84.0 KB
1<?xml version="1.0" encoding="UTF-8"?>
2  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
3  <!-- generated by version 1.0.27 -->
5<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
8<?rfc toc="yes"?>
9<?rfc tocdepth="3"?>
10<?rfc sortrefs="yes"?>
11<?rfc symrefs="yes"?>
13<rfc ipr="trust200902" docName="draft-ietf-lwig-coap-03" category="info">
15  <front>
16    <title>CoAP Implementation Guidance</title>
18    <author initials="M." surname="Kovatsch" fullname="Matthias Kovatsch">
19      <organization>ETH Zurich</organization>
20      <address>
21        <postal>
22          <street>Universitätstrasse 6</street>
23          <city>CH-8092 Zurich</city>
24          <country>Switzerland</country>
25        </postal>
26        <email></email>
27      </address>
28    </author>
29    <author initials="O." surname="Bergmann" fullname="Olaf Bergmann">
30      <organization>Universitaet Bremen TZI</organization>
31      <address>
32        <postal>
33          <street>Postfach 330440</street>
34          <city>D-28359 Bremen</city>
35          <country>Germany</country>
36        </postal>
37        <email></email>
38      </address>
39    </author>
40    <author initials="C." surname="Bormann" fullname="Carsten Bormann" role="editor">
41      <organization>Universitaet Bremen TZI</organization>
42      <address>
43        <postal>
44          <street>Postfach 330440</street>
45          <city>D-28359 Bremen</city>
46          <country>Germany</country>
47        </postal>
48        <phone>+49-421-218-63921</phone>
49        <email></email>
50      </address>
51    </author>
53    <date year="2015" month="July" day="06"/>
55    <area>Internet</area>
56    <workgroup>LWIG Working Group</workgroup>
57    <keyword>Internet-Draft</keyword>
59    <abstract>
62<t>The Constrained Application Protocol (CoAP) is designed for
63resource-constrained nodes and networks such as sensor nodes in a low-power
64lossy network (LLN). Yet to implement this Internet protocol on
65Class 1 devices (as per RFC 7228, ~ 10 KiB of RAM and ~ 100 KiB of ROM) also lightweight
66implementation techniques are necessary. This document provides
67lessons learned from implementing CoAP for tiny, battery-operated networked
68embedded systems. In particular, it provides guidance on correct implementation
69of the CoAP specification RFC 7252, memory optimizations, and
70customized protocol parameters.</t>
74    </abstract>
77  </front>
79  <middle>
82<!-- Note: xml2rfc ——html ignores align attributes on artwork -->
84<section anchor="introduction" title="Introduction">
86<t>The Constrained Application Protocol <xref target="RFC7252"/> has been designed
87specifically for machine-to-machine communication in networks with very
88constrained nodes.  Typical application scenarios therefore include building
89automation, process optimization, and the Internet of Things. The major design
90objectives have been set on small protocol overhead, robustness against packet
91loss, and against high latency induced by small bandwidth shares or slow
92request processing in end nodes.  To leverage integration of constrained nodes
93with the world-wide Internet, the protocol design was led by the REST
94architectural style that accounts for the scalability and robustness of the
95Hypertext Transfer Protocol <xref target="RFC7230"/>.</t>
97<t>Lightweight implementations benefit from this design in many
98respects: First, the use of Uniform Resource Identifiers (URIs) for
99naming resources and the transparent forwarding of their
100representations in a server-stateless request/response protocol make
101protocol translation to HTTP a straightforward task.  Second, the
102set of protocol elements that are unavoidable for the core protocol,
103and thus must be implemented on every node, has been kept very small,
104minimizing the unnecessary accumulation of “optional” features.  Options
105that – when present – are critical for message processing are
106explicitly marked as such to force immediate rejection of messages
107with unknown critical options.  Third, the syntax of protocol data
108units is easy to parse and is carefully defined to avoid creation of
109state in servers where possible.</t>
111<t>Although these features enable lightweight implementations of the
112Constrained Application Protocol, there is still a tradeoff between
113robustness and latency of constrained nodes on one hand and resource
114demands on the other.
115For constrained nodes of Class 1 or even Class 2 <xref target="RFC7228"/>, the most limiting
116factors usually are dynamic memory needs, static code size, and energy.
117Most implementations therefore need to optimize internal buffer usage,
118omit idle protocol feature, and maximize sleeping cycles.</t>
120<t>The present document gives possible strategies to solve this tradeoff
121for very constrained nodes (i.e., Class 1).
122For this, it provides guidance on correct implementation of the
123CoAP specification <xref target="RFC7252"/>, memory optimizations, and
124customized protocol parameters.</t>
127<section anchor="protocol-implementation" title="Protocol Implementation">
129<t>In the programming styles supported by very simple operating systems as
130found on constrained nodes, preemptive multi-threading is not an option.
131Instead, all operations are triggered by an event loop system, e.g.,
132in a send-receive-dispatch cycle.
133It is also common practice to allocate memory statically to ensure stable
134behavior, as no memory management unit (MMU) or other abstractions are
135available.  For a CoAP node, the two key parameters for memory usage are
136the number of (re)transmission buffers and the maximum message size that
137must be supported by each buffer.  Often the maximum message size is set
138far below the 1280-byte MTU of 6LoWPAN to allow more than one open Confirmable
139transmission at a time (in particular for parallel observe
140notifications <xref target="I-D.ietf-core-observe"/>).
141Note that implementations on constrained platforms often not even
142support the full MTU.  Larger messages must then use blockwise
143transfers <xref target="I-D.ietf-core-block"/>, while a good tradeoff between
1446LoWPAN fragmentation and CoAP header overhead must be found.
145Usually the amount of available free RAM dominates this decision.
146For Class 1 devices, the maximum message size is typically 128 or 256
147bytes (blockwise) payload plus an estimate of the maximum header size
148for the worst case option setting.</t>
150<section anchor="client-server" title="Client/Server Model">
152<t>In general, CoAP servers can be implemented more efficiently than clients.
153REST allows them to keep the communication stateless and piggy-backed
154responses are not stored for retransmission, saving buffer space.
155The use of idempotent requests also allows to relax deduplication, which
156further decreases memory usage.
157It is also easy to estimate the required maximum size of message buffers,
158since URI paths, supported options, and maximum payload sizes of the
159application are known at compile time. Hence, when the application is
160distributed over constrained and unconstrained nodes, the constrained ones
161should preferably have the server role.</t>
163<t>HTTP-based applications have established an inverse model because of the
164need for simple push notifications: A constrained client uses POST requests
165to update resources on an unconstrained server whenever an event (e.g., a
166new sensor reading) is triggered. This requirement is solved by the Observe
167option <xref target="I-D.ietf-core-observe"/> of CoAP. It allows servers to initiate
168communication and send push notifications to interested client nodes. This
169allows a more efficient and also more natural model for CoAP-based
170applications, where the information source is an origin server, which can also
171benefit from caching.</t>
174<section anchor="message-processing" title="Message Processing">
176<t>Apart from the required buffers, message processing is symmetric for clients
177and servers. First the 4-byte base header has to be parsed and thereby checked
178if it is a CoAP message. Since the encoding is very dense, only a wrong
179version or a datagram size smaller than four bytes identify non-CoAP
180datagrams. These need to be silently ignored. Other message format errors,
181such as an incomplete datagram or the usage of reserved values, may need to be
182rejected with a Reset (RST) message (see Section 4.2 and 4.3 of
183<xref target="RFC7252"/> for details).
184Next the Token is read based on the TKL
185field. For the options following, there are two alternatives: either
186process them on the fly when an option is accessed or initially parse
187all values into an internal data structure.</t>
189<section anchor="on-the-fly-processing" title="On-the-fly Processing">
191<t>The advantage of on-the-fly processing is that no additional memory needs to
192be allocated to store the option values, which are stored efficiently inline
193in the buffer for incoming messages. Once the message is
194accepted for further processing, the set of options contained in the received
195message must be decoded to check for unknown critical options. To avoid
196multiple passes through the option list, the option parser might maintain a
197bit-vector where each bit represents an option number that is present in the
198received request. With the wide and sparse range of option numbers, the number
199itself cannot be used to indicate the number of left-shift operations to mask
200the corresponding bit. Hence, an implementation-specific enum of supported
201options should be used to mask the present options of a message in the bitmap.
202In addition, the byte index of every option (a direct pointer) can be added
203to a sparse list (e.g., a one-dimensional array) for fast retrieval.</t>
205<t>This particularly enables efficient handling of options that might occur more
206than once such as Uri-Path. In this implementation strategy, the delta is zero
207for any subsequent path segment, hence the stored byte index for this option
208(e.g., 11 for Uri-Path) would be overwritten to hold a pointer to only the last
209occurrence of that option. The Uri-Path can be resolved on the fly, though,
210and a pointer to the targeted resource stored directly in the sparse list.</t>
212<!--What does this mean?-->
213<!--In simpler cases, conditionals can preselect one of the repeated option values.-->
215<t>Once the option list has been processed, all known critical option and all
216elective options can be masked out in the bit-vector to determine if any
217unknown critical option was present. If this is the case, this information can
218be used to create a 4.02 response accordingly. Note that full processing must
219only be done up to the highest supported option number. Beyond that, only the
220least significant bit (Critical or Elective) needs to be checked. Otherwise,
221if all critical options are supported, the sparse list of option pointers is
222used for further handling of the message.</t>
225<section anchor="internal-data-structure" title="Internal Data Structure">
227<t>Using an internal data structure for all parsed options has an advantage when
228working on the option values, as they are already in a variable of
229corresponding type (e.g., an integer in host byte order). The incoming payload
230and byte strings of the header can be accessed directly in the buffer for
231incoming messages using pointers (similar to on-the-fly processing). This
232approach also benefits from a bitmap. Otherwise special values must be
233reserved to encode an unset option, which might require a larger type than
234required for the actual value range (e.g., a 32-bit integer instead of 16-bit).</t>
236<t>Many of the byte strings (e.g., the URI) are usually not required when generating the
237response. When all important values are copied (e.g., the Token, which needs
238to be mirrored), the internal data structure
239facilitates using the buffer for incoming messages also for the assembly of
240outgoing messages – which can be the shared IP buffer provided by the OS.</t>
242<t>Setting options for outgoing messages is also easier with an internal data
243structure. Application developers can set options independent from the option
244number and do not need to care about the order for the delta encoding. The CoAP
245encoding is applied in a serialization step before sending. In contrast, assembling
246outgoing messages with on-the-fly processing requires either extensive memmove
247operations to insert new options, or restrictions for developers to set
248options in their correct order.</t>
252<section anchor="message-id-usage" title="Message ID Usage">
254<t>Many applications of CoAP use unreliable transports, in particular
255UDP, which can lose, reorder, and duplicate messages. Although DTLS’s
256replay protection deals with duplication by the network, losses are
257addressed with DTLS retransmissions only for the handshake protocol
258and not for the application data protocol. Furthermore, CoAP
259implementations usually send CON retransmissions in new DTLS records,
260which are not considered duplicates at the DTLS layer.</t>
262<section anchor="duplicate-rejection" title="Duplicate Rejection">
264<t>CoAP’s messaging sub-layer has been designed with protocol functionality such
265that rejection of duplicate messages is always possible. It is realized through
266the Message IDs (MIDs) and their lifetimes with regard to the message type.</t>
268<t>Duplicate detection is under the discretion of the recipient (see
269Section 4.5 of <xref target="RFC7252"/>, <xref target="relaxation-on-the-server"/>, <xref target="relaxation-on-the-client"/>).
270Where it is desired, the receiver needs to keep track of MIDs to
271filter the duplicates for at least NON_LIFETIME (145 s).
272This time also holds for CON messages, since it equals the possible reception
275<t>On the sender side, MIDs of CON messages must not be re-used within
276the EXCHANGE_LIFETIME; MIDs of NONs respectively within the
277NON_LIFETIME.  In typical scenarios, however, senders will re-use MIDs
278with intervals far larger than these lifetimes: with sequential
279assignment of MIDs, coming close to them would require 250 messages
280per second, much more than the bandwidth of constrained networks would
281usually allow for.</t>
283<t>In cases where senders might come closer to the maximum message rate, it is
284recommended to use more conservative timings for the re-use of MIDs.
285Otherwise, opposite inaccuracies in the clocks of sender and recipient
286may lead to obscure message loss.
287If needed, higher rates can be achieved by using multiple endpoints
288for sending requests and managing the local MID per remote endpoint
289instead of a single counter per system (essentially extending the
29016-bit message ID by a 16-bit port number and/or an 128-bit IP
291address).  In controlled scenarios, such as real-time applications
292over industrial Ethernet, the protocol parameters can also be tweaked
293to achieve higher message rates (<xref target="parameters"/>).</t>
296<section anchor="mid-namespaces" title="MID Namespaces">
298<t>MIDs are assigned under the control of the originator of CON and NON
299messages, and they do not mix with the MIDs assigned by the peer for
300CON and NON in the opposite direction. Hence, CoAP implementors
301need to make sure to manage different namespaces for the MIDs used for
302deduplication. MIDs of outgoing CONs and NONs belong to the local endpoint; so
303do the MIDs of incoming ACKs and RSTs. Accordingly, MIDs of incoming CONs and
304NONs and outgoing ACKs and RSTs belong to the corresponding remote endpoint.
305<xref target="mid_namespace"/> depicts a scenario where mixing the namespaces would
306cause erroneous filtering.</t>
308<figure title="Deduplication must manage the MIDs in different namespace corresponding to their origin endpoints." anchor="mid_namespace"><artwork align="center"><![CDATA[
309                  Client              Server
310                     |                  |
311                     |   CON [0x1234]   |
312                     +----------------->|
313                     |                  |
314                     |   ACK [0x1234]   |
315                     |<-----------------+
316                     |                  |
317                     |   CON [0x4711]   |
318                     |<-----------------+ Separate response
319                     |                  |
320                     |   ACK [0x4711]   |
321                     +----------------->|
322                     |                  |
323A request follows that uses the same MID as the last separate response
324                     |                  |
325                     |   CON [0x4711]   |
326                     +----------------->|
327Response is filtered |                  |
328  because MID 0x4711 |   ACK [0x4711]   |
329     is still in the X<-----------------+ Piggy-backed response
330  deduplication list |                  |
334<section anchor="relaxation-on-the-server" title="Relaxation on the Server">
336<t>Using the de-duplication functionality is at the discretion of the receiver: Processing of duplicate
337messages comes at a cost, but so does the management of the state associated
338with duplicate rejection. The number of remote endpoints that need to be
339managed might be vast. This can be costly in particular for less constrained
340nodes that have throughput in the order of hundreds of thousands requests per
341second (which needs about 16 GiB of RAM just for duplicate rejection). Deduplication
342is also heavy for servers on Class 1 devices, as also piggy-backed responses
343need to be stored for the case that the ACK message is lost.
344Hence, a receiver may have good reasons to decide not to perform deduplication.
345This behavior is possible when the application is designed with idempotent
346operations only and makes good use of the If-Match/If-None-Match options.</t>
348<t>If duplicate rejection is indeed necessary (e.g., for non-idempotent
349requests) it is important to control the amount of state that needs to
350be stored. It can be reduced, for instance, by deduplication at resource level:
351Knowledge of the application and supported representations can minimize the
352amount of state that needs to be kept.</t>
355<section anchor="relaxation-on-the-client" title="Relaxation on the Client">
357<t>Duplicate rejection on the client side can be simplified by choosing clever
358Tokens that are virtually not re-used
359(e.g., through an obfuscated sequence number in the Token value) and
360only filter based on the list of open Tokens.
361If a client wants to re-use Tokens (e.g., the empty Token for optimizations),
362it requires strict duplicate rejection based on MIDs to avoid the scenario
363outlined in <xref target="token_reuse"/>.</t>
365<figure title="Re-using Tokens requires strict duplicate rejection." anchor="token_reuse"><artwork align="center"><![CDATA[
366                  Client              Server
367                     |                  |
368                     |   CON [0x7a10]   |
369                     |    GET /temp     |
370                     |   (Token 0x23)   |
371                     +----------------->|
372                     |                  |
373                     |   ACK [0x7a10]   |
374                     |<-----------------+
375                     |                  |
376                     ... Time Passes  ...
377                     |                  |
378                     |   CON [0x23bb]   |
379                     |  4.04 Not Found  |
380                     |   (Token 0x23)   |
381                     |<-----------------+
382                     |                  |
383                     |   ACK [0x23bb]   |
384                     +--------X         |
385                     |                  |
386                     |   CON [0x7a11]   |
387                     |   GET /resource  |
388                     |   (Token 0x23)   |
389                     +----------------->|
390                     |                  |
391                     |   CON [0x23bb]   |
392 Causing an implicit |  4.04 Not Found  |
393  acknowledgement if |   (Token 0x23)   |
394not filtered through X<-----------------+ Retransmission
395 duplicate rejection |                  |
400<section anchor="token-usage" title="Token Usage">
402<t>Tokens are chosen by the client and help to identify request/response pairs
403that span several message exchanges (e.g., a separate response, which has a new MID).
404Servers do not generate Tokens and only mirror what they receive from the
405clients. Tokens must be unique within the namespace of a client throughout their
406lifetime. This begins when being assigned to a request and ends when the open
407request is closed by receiving and matching the final response. Neither empty
408ACKs nor notifications (i.e., responses carrying the Observe option) terminate
409the lifetime of a Token.</t>
411<t>As already mentioned, a clever assignment of Tokens can help to simplify
412duplicate rejection. Yet this is also important for coping with client crashes.
413When a client restarts during an open request and (unknowingly) re-uses the
414same Token, it might match the response from the previous request to the
415current one. Hence, when only the Token is used for matching, which is always
416the case for separate responses, randomized Tokens with enough entropy should
417be used. The 8-byte range for Tokens can even allow for one-time usage throughout
418the lifetime of a client node. When DTLS is used, client crashes/restarts
419will lead to a new security handshake, thereby solving the problem of
420mismatching responses and/or notifications.</t>
422<section anchor="tokens-for-observe" title="Tokens for Observe">
424<t>In the case of Observe <xref target="I-D.ietf-core-observe"/>, a request will be answered
425with multiple notifications and it is important to continue keeping
426track of the Token that was used for the request – its lifetime will
427end much later.
428Upon establishing an Observe relationship, the Token is
429registered at the server. Hence, the client’s use of that specific
430Token is now limited to controlling the Observation relationship.
431A client can use it to cancel the relationship, which frees the Token
432upon success (i.e., the message with an Observe Option with the value set to
433‘deregister’ (1) is confirmed with a response; see
434<xref target="I-D.ietf-core-observe"/> section 3.6). However, the client might never
435receive the response due to a temporary network outage or worse, a server crash.
436Although a network outage will also affect notifications so that the Observe
437garbage collection could apply, the server might simply happen not to send CON
438notifications during that time. Alternative Observe lifetime models such as
439Stubbornness(tm) might also keep relationships alive for longer periods.</t>
441<t>Thus, it is best to carefully choose the Token value used with Observe requests.
442(The empty value will rarely be applicable.)
443One option is to assign and re-use dedicated Tokens for each Observe
444relationship the client will establish.  The choice of Token values also is
445critical in NoSec mode, to limit the effectiveness of spoofing
446attacks.  Here, the recommendation is to use randomized Tokens with a
447length of at least four bytes (see Section 5.3.1 of <xref target="RFC7252"/>). Thus,
448dedicated ranges within the 8-byte Token
449space should be used when in NoSec mode. This also solves the problem of
450mismatching notifications after a client crash/restart.</t>
452<t>When the client wishes to reinforce its interest in a resource, maybe
453not really being sure whether the server has forgotten it or not, the Token
454value allocated to the Observe relationship is used to
455re-register that observation (see Section 3.3.1 of <xref target="I-D.ietf-core-observe"/> for
456details): If the server is still aware of the
457relationship (an entry with a matching endpoint and token is already
458present in its list of observers for the resource), it will not add a
459new relationship but will replace or update the existing one (Section
4604.1 of <xref target="I-D.ietf-core-observe"/>).  If not, it will simply establish a new
461registration which of course also uses the Token value.</t>
463<t>If the client sends an Observe request for the same resource with a
464new Token, this is not a
465protocol violation, because the specification allows the client to
466observe the same resource in a different Observe relationship if the
467cache-key is different (e.g., requesting a different Content-Format).
468If the cache-key is not different, though, an additional Observe
469relationship just wastes the server’s resources, and is therefore not
470allowed; the server might rely on this for its housekeeping.</t>
473<section anchor="tokens-for-blockwise-transfers" title="Tokens for Blockwise Transfers">
475<t>In general, blockwise transfers are independent from the Token and are
476correlated through client endpoint address and server address and resource path
477(destination URI). Thus, each block may be transferred using a different Token.
478Still it can be beneficial to use the same Token (it is freed upon reception
479of a response block) for all blocks, e.g., to easily route received blocks to
480the same response handler.</t>
482<t>When Block2 is combined with Observe,
483notifications only carry the first block and it is up to the client to retrieve
484the remaining ones. These GET requests do not carry the Observe option
485and need to
486use a different Token, since the Token from the notification is still in use.</t>
490<section anchor="fsms" title="Transmission States">
492<t>CoAP endpoints must keep transmission state to manage open requests, to handle
493the different response modes, and to implement reliable delivery at the message
494layer. The following finite state machines (FSMs) model the transmissions of a
495CoAP exchange at the request/response layer and the message layer. These layers
496are linked through actions. The M_CMD() action triggers a corresponding
497transition at the message layer and the RR_EVT() action triggers a transition
498at the request/response layer. The FSMs also use guard conditions to
499distinguish between information that is only available through the other layer
500(e.g., whether a request was sent using a CON or NON message).</t>
502<section anchor="requestresponse-layer" title="Request/Response Layer">
504<t><xref target="fsm_rr_c"/> depicts the two states at the request/response layer of a
505CoAP client. When a request is issued, a “reliable_send” or “unreliable_send”
506is triggered at the message layer. The WAITING state can be left through three
507transitions: Either the client cancels the request and triggers cancellation of
508a CON transmission at the message layer, the client receives a failure event
509from the message layer, or a receive event containing a response.</t>
511<figure title="CoAP Client Request/Response Layer FSM" anchor="fsm_rr_c"><artwork align="center"><![CDATA[
512    +------------CANCEL-------------------------------+
513    |        / M_CMD(cancel)                          |
514    |                                                 V
515    |                                              +------+
516+-------+ -------RR_EVT(fail)--------------------> |      |
517|WAITING|                                          | IDLE |
518+-------+ -------RR_EVT(rx)[is Response]---------> |      |
519    ^                / M_CMD(accept)               +------+
520    |                                                 |
521    +--------------------REQUEST----------------------+
522               / M_CMD((un)reliable_send)
525<t>A server resource can decide at the request/response layer whether to respond
526with a piggy-backed or a separate response. Thus, there are two busy states in
527<xref target="fsm_rr_s"/>, SERVING and SEPARATE. An incoming receive event with a NON
528request directly triggers the transition to the SEPARATE state.</t>
530<figure title="CoAP Server Request/Response Layer FSM" anchor="fsm_rr_s"><artwork align="center"><![CDATA[
531+--------+ <----------RR_EVT(rx)[is NON]---------- +------+
532|SEPARATE|                                         |      |
533+--------+ ----------------RESPONSE--------------> | IDLE |
534    ^            / M_CMD((un)reliable_send)        |      |
535    |                                        +---> +------+
536    |EMPTY_ACK                               |         |
537    |/M_CMD(accept)                          |         |
538    |                                        |         |
539    |                                        |         |
540+--------+                                   |         |
541|SERVING | --------------RESPONSE------------+         |
542+--------+          / M_CMD(accept)                    |
543    ^                                                  |
544    +------------------------RR_EVT(rx)[is CON]--------+
548<section anchor="message-layer" title="Message Layer">
550<t><xref target="fsm_m"/> shows the different states of a CoAP endpoint per message exchange.
551Besides the linking action RR_EVT(), the message layer has a TX action to send
552a message. For sending and receiving NONs, the endpoint remains in its CLOSED
553state. When sending a CON, the endpoint remains in RELIABLE_TX and keeps
554retransmitting until the transmission times out, it receives a matching RST,
555the request/response layer cancels the transmission, or the endpoint receives
556an implicit acknowledgement through a matching NON or CON. Whenever the
557endpoint receives a CON, it transitions into the ACK_PENDING state, which can
558be left by sending the corresponding ACK.</t>
560<figure title="CoAP Message Layer FSM" anchor="fsm_m"><artwork align="center"><![CDATA[
561+-----------+ <-------M_CMD(reliable_send)-----+
562|           |            / TX(con)              \
563|           |                                +--------------+
564|           | ---TIMEOUT(RETX_WINDOW)------> |              |
565|RELIABLE_TX|     / RR_EVT(fail)             |              |
566|           | ---------------------RX_RST--> |              | <----+
567|           |               / RR_EVT(fail)   |              |      |
568+-----------+ ----M_CMD(cancel)------------> |    CLOSED    |      |
569 ^  |  |  \  \                               |              | --+  |
570 |  |  |   \  +-------------------RX_ACK---> |              |   |  |
571 +*1+  |    \                / RR_EVT(rx)    |              |   |  |
572       |     +----RX_NON-------------------> +--------------+   |  |
573       |       / RR_EVT(rx)                  ^ ^ ^ ^  | | | |   |  |
574       |                                     | | | |  | | | |   |  |
575       |                                     | | | +*2+ | | |   |  |
576       |                                     | | +--*3--+ | |   |  |
577       |                                     | +----*4----+ |   |  |
578       |                                     +------*5------+   |  |
579       |                +---------------+                       |  |
580       |                |  ACK_PENDING  | <--RX_CON-------------+  |
581       +----RX_CON----> |               |  / RR_EVT(rx)            |
582         / RR_EVT(rx)   +---------------+ ---------M_CMD(accept)---+
583                                                     / TX(ack)
586*2: M_CMD(unreliable_send) / TX(non)
587*3: RX_NON / RR_EVT(rx)
589*5: RX_ACK
592<t>T.B.D.: (i) Rejecting messages (can be triggered at message and request/response
593layer). (ii) ACKs can also be triggered at both layers.</t>
596## Taxonomy of Cases
599This section was removed, as it is unclear whether it is needed.
600Maybe single interesting cases can be picked for further explanation.
601Restore the figures from the SVN (Rev. 12)
607<section anchor="out-of-band-information" title="Out-of-band Information">
609<t>The CoAP implementation can also leverage out-of-band information, that might
610also trigger some of the transitions shown in <xref target="fsms"/>. In particular ICMP
611messages can inform about unreachable remote endpoints or whole network
612outages. This information can be used to pause or cancel ongoing transmission
613to conserve energy. Providing ICMP information to the CoAP implementation is
614easier in constrained environments, where developers usually can adapt the
615underlying OS (or firmware). This is not the case on general purpose platforms
616that have full-fledged OSes and make use of high-level programming frameworks.</t>
618<t>The most important ICMP messages are host, network, port, or protocol
619unreachable errors. After appropriate vetting (cf. <xref target="RFC5927"/>),
620they should cause the cancellation of ongoing CON
621transmissions and clearing (or deferral) of Observe relationships. Requests to this
622destination should be paused for a sensible interval. In addition, the device
623could indicate of this error through a notification to a management endpoint
624or external status indicator, since the cause could be a misconfiguration or
625general unavailability of the required service. Problems reported through the
626Parameter Problem message are usually caused through a similar fundamental
629<t>The CoAP specification recommends to ignore Source Quench and Time Exceeded
630ICMP messages, though. Source Quench messages were originally intended
631to inform the sender to reduce the
632rate of packets. However, this mechanism is deprecated through <xref target="RFC6633"/>.
633CoAP also comes with its own congestion control mechanism, which is already
634designed conservatively. One advanced mechanism that can be employed for better
635network utilization is CoCoA, <xref target="I-D.bormann-core-cocoa"/>. Time
636Exceeded messages often occur during transient routing loops (unless
637they are caused by a too small initial
638Hop Limit value).</t>
641<section anchor="programming-model" title="Programming Model">
643<t>The event-driven approach, which is common in event-loop-based firmware, has
644also proven very efficient for embedded operating systems <xref target="TinyOS"/>,
645<xref target="Contiki"/>. Note that an OS is not necessarily required and a traditional
646firmware approach can suffice for Class 1 devices. Event-driven systems use
647split-phase operations (i.e., there are no blocking functions, but functions
648return and an event handler is called once a long-lasting operation completes)
649to enable cooperative multi-threading with a single stack.</t>
651<t>Bringing a Web transfer protocol to constrained environments does not
652only change the networking of the corresponding systems, but also the
653programming model. The complexity of event-driven systems can be hidden
654through APIs that resemble classic RESTful Web service implementations.</t>
656<section anchor="client" title="Client">
658<t>An API for asynchronous requests with response handler functions goes
659hand-in-hand with the event-driven approach. Synchronous requests with a
660blocking send function can facilitate applications that require strictly
661ordered, sequential request execution (e.g., to control a physical process) or
662other checkpointing (e.g., starting operation only after registration with the
663resource directory was successful). However, this can also be solved by
664triggering the next operation in the response handlers. Furthermore, as
665mentioned in <xref target="client-server"/>, it is more like that complex control flow is
666done by more powerful devices and Class 1 devices predominantly run a CoAP
667server (which might include a minimal client to communicate with a resource
671<section anchor="server" title="Server">
673<t>On CoAP servers, the event-driven nature can be hidden through resource handler
674abstractions as known from traditional REST frameworks. The following types of
675RESTful resources have proven useful to provide an intuitive API on constrained
676event-driven systems:</t>
678<t><list style="hanging">
679  <t hangText='NORMAL'>
680  A normal resource defined by a static Uri-Path and an associated resource
681handler function.  Allowed methods could already be filtered by the
682implementation based on flags. This is the basis for all other resource
684  <t hangText='PARENT'>
685  A parent resource manages several sub-resources under a given base path
686by programmatically evaluating the Uri-Path. Defining a URI template (see
687<xref target="RFC6570"/>) would be a convenient way to pre-parse arguments given
688in the Uri-Path.</t>
689  <t hangText='PERIODIC'>
690  A resource that has an additional handler function that is
691triggered periodically by the CoAP implementation with a resource-specific
692interval.  It can be used to sample a sensor or perform
693similar periodic updates of its state.  Usually, a periodic resource is
694observable and sends the notifications by triggering its normal resource
695handler from the periodic handler. These periodic tasks are quite common
696for sensor nodes, thus it makes sense to provide this functionality in the
697CoAP implementation and avoid redundant code in every resource.</t>
698  <t hangText='EVENT'>
699  An event resource is similar to an periodic resource, only
700that the second handler is called by an irregular event such as a
702  <t hangText='SEPARATE'>
703  Separate responses are usually used when handling a request takes more time,
704e.g., due to a slow sensor or UART-based subsystems. To not fully block the
705system during this time, the handler should also employ split-phase execution:
706The resource handler returns as soon as possible and an event handler resumes
707responding when the result is ready. The separate resource type can abstract
708from the split-phase operation and take care of temporarily storing the
709request information that is required later in the result handler to send the
710response (e.g., source address and Token).</t>
716<section anchor="optimizations" title="Optimizations">
718<section anchor="message-buffers" title="Message Buffers">
720<t>The cooperative multi-threading of an event loop system allows to optimize
721memory usage through in-place processing and reuse of buffers, in particular
722the IP buffer provided by the OS or firmware.</t>
724<t>CoAP servers can significantly benefit from in-place processing, as
725they can create responses directly in the incoming IP buffer. Note that an
726embedded OS usually only has a single buffer for incoming and outgoing IP
728The first few bytes of the basic header are usually parsed into
729an internal data structure and can be overwritten without harm.
730Thus, empty ACKs and RST messages can promptly be assembled and sent using
731the IP buffer. Also when a CoAP server only sends piggy-backed or
732Non-confirmable responses, no additional buffer is required at the application
733layer. This, however, requires careful timing so that no incoming data is
734overwritten before it was processed. Because of cooperative multi-threading,
735this requirement is relaxed, though. Once the message is sent, the IP buffer
736can accept new messages again. This does not work for Confirmable messages,
737however. They need to be stored for retransmission and would block any
738further IP communication.</t>
740<t>Depending on the number of requests that can be handled in
741parallel, an implementation might create a stub response filled with
742any option that has to be copied from the original request to the
743separate response, especially the Token option.  The drawback of
744this technique is that the server must be prepared to receive
745retransmissions of the previous (Confirmable) request to which a new
746acknowledgement must be generated.  If memory is an issue, a single
747buffer can be used for both tasks: Only the message type and code
748must be updated, changing the message id is optional.  Once the
749resource representation is known, it is added as new payload at the
750end of the stub response.  Acknowledgements still can be sent as
751described before as long as no additional options are required to
752describe the payload.</t>
755<section anchor="retransmissions" title="Retransmissions">
757<t>CoAP’s reliable transmissions require the before-mentioned
758retransmission buffers.  Messages, such as the requests of a client,
759should be stored in serialized form.  For servers, retransmissions
760apply for Confirmable separate responses and Confirmable
761notifications <xref target="I-D.ietf-core-observe"/>.  As separate responses stem
762from long-lasting resource handlers, the response should be stored
763for retransmission instead of re-dispatching a stored request (which
764would allow for updating the representation).  For Confirmable
765notifications, please see Section 2.6, as simply storing the response
766can break the concept of eventual consistency.</t>
768<t>String payloads such as JSON require a buffer to print to.  By
769splitting the retransmission buffer into header and payload part, it
770can be reused.  First to generate the payload and then storing the
771CoAP message by serializing into the same memory.  Thus, providing a
772retransmission for any message type can save the need for a separate
773application buffer.  This, however, requires an estimation about the
774maximum expected header size to split the buffer and a memmove to
775concatenate the two parts.</t>
777<t>For platforms that disable clock tick interrupts in sleep states, the
778application must take into consideration the clock deviation that occurs
779during sleep (or ensure to remain in idle state until the message has been
780acknowledged or the maximum number of retransmissions is reached).
781Since CoAP allows up to four retransmissions with a binary
782exponential back-off it could take up to 45 seconds until the send
783operation is complete.  Even in idle state, this means substantial
784energy consumption for low-power nodes.  Implementers therefore
785might choose a two-step strategy: First, do one or two
786retransmissions and then, in the later phases of back-off, go to sleep
787until the next retransmission is due. In the meantime, the node could
788check for new messages including the acknowledgement for any
789Confirmable message to send.</t>
792<section anchor="observable-resources" title="Observable Resources">
794<t>For each observer, the server needs to store at least address, port, token,
795and the last outgoing message ID.  The latter is needed to match incoming
796RST messages and cancel the observe relationship.</t>
798<t>It is favorable to have one retransmission buffer per observable resource
799that is shared among all observers.  Each notification is serialized once
800into this buffer and only address, port, and token are changed when
801iterating over the observer list (note that different token lengths
802might require realignment).  The advantage becomes clear for
803Confirmable notifications: Instead of one retransmission buffer per
804observer, only one buffer and only individual retransmission counters
805and timers in the list entry need to be stored.  When the
806notifications can be sent fast enough, even a single timer would
807suffice.  Furthermore, per-resource buffers simplify the update with
808a new resource state during open deliveries.</t>
811<section anchor="blockwise-transfers" title="Blockwise Transfers">
813<t>Blockwise transfers have the main purpose of providing fragmentation
814at the application layer, where partial information can be processed.
815This is not possible at lower layers such as 6LoWPAN, as only
816assembled packets can be passed up the stack.  While
817<xref target="I-D.ietf-core-block"/> also anticipates atomic handling of blocks,
818i.e., only fully received CoAP messages, this is not possible on
819Class 1 devices.</t>
821<t>When receiving a blockwise transfer, each block is usually passed to
822a handler function that for instance performs stream processing or
823writes the blocks to external memory such as flash.  Although there
824are no restrictions in <xref target="I-D.ietf-core-block"/>, it is beneficial for
825Class 1 devices to only allow ordered transmission of blocks.
826Otherwise on-the-fly processing would not be possible.</t>
828<t>When sending a blockwise transfer out of dynamically generated information, Class 1 devices usually do not
829have sufficient memory to print the full message into a buffer, and
830slice and send it in a second step.  For instance, if the CoRE Link
831Format at /.well-known/core is dynamically generated, a generator function is
832required that generates slices of a large string with a specific
833offset length (a ‘sonprintf()’).  This functionality is required
834recurrently and should be included in a library.</t>
837<section anchor="deduplication-with-sequential-mids" title="Deduplication with Sequential MIDs">
839<t>CoAP’s duplicate rejection functionality can be straightforwardly
840implemented in a CoAP
841endpoint by storing, for each remote CoAP endpoint (“peer”) that it
842communicates with, a list of recently received CoAP Message IDs (MIDs)
843along with some timing information.
844A CoAP message from a peer with a MID that is in the list for that peer
845can simply be discarded.</t>
847<t>The timing information in the list can then be used to time out
848entries that are older than the <spanx style="emph">expected extent of the re-ordering</spanx>,
849an upper bound for which can be estimated by adding the <spanx style="emph">potential
850retransmission window</spanx> (<xref target="RFC7252"/> section “Reliable
851Messages”) and the time packets can stay alive in the network.</t>
853<t>Such a straightforward implementation is suitable in case other CoAP
854endpoints generate random MIDs. However, this storage method may
855consume substantial RAM in specific cases, such as:</t>
857<t><list style="symbols">
858  <t>many clients are making periodic, non-idempotent requests to a
859single CoAP server;</t>
860  <t>one client makes periodic requests to a large number of CoAP
861servers and/or requests a large number of resources; where servers
862happen to mostly generate separate CoAP responses (not piggy-backed);</t>
865<t>For example, consider the first case where the expected extent of re-ordering
866is 50 seconds, and N clients are sending periodic POST
867requests to a single CoAP server during a period of high system
868activity, each on average sending one client request per second.
869The server would need 100 * N bytes of RAM to store the MIDs only.
870This amount of RAM may be significant on a RAM-constrained
871platform. On a number of platforms, it may be easier to allocate some
872extra program memory (e.g. Flash or ROM) to the CoAP protocol handler
873process than to allocate extra RAM. Therefore, one may try to reduce
874RAM usage of a CoAP implementation at the cost of some additional
875program memory usage and implementation complexity.</t>
877<t>Some CoAP clients generate MID values by a using a Message ID variable
878<xref target="RFC7252"/> that is incremented by one each time a new MID
879needs to be generated.  (After the maximum value 65535 it wraps back
880to 0.)  We call this behavior “sequential” MIDs.  One approach to
881reduce RAM use exploits the redundancy in sequential MIDs for a more
882efficient MID storage in CoAP servers.</t>
884<t>Naturally such an approach requires, in order to actually reduce RAM
885usage in an implementation, that a large part of the peers follow the
886sequential MID behavior. To realize this optimization, the authors
887therefore RECOMMEND that CoAP endpoint implementers employ the
888“sequential MID” scheme if there are no reasons to prefer another
889scheme, such as randomly generated MID values.</t>
891<t>Security considerations might call for a choice for (pseudo)randomized
892MIDs. Note however that with truly randomly generated MIDs the
893probability of MID collision is rather high in use cases as mentioned
894before, following from the Birthday Paradox. For example, in a
895sequence of 52 randomly drawn 16-bit values the probability of finding
896at least two identical values is about 2 percent.</t>
898<t>From here on we consider efficient storage implementations for MIDs in
899CoAP endpoints, that are optimized to store “sequential”
900MIDs. Because CoAP messages may be lost or arrive out-of-order, a
901solution has to take into
902account that received MIDs of CoAP messages are not actually arriving
903in a sequential fashion, due to lost or reordered messages. Also a
904peer might reset and lose its MID counter(s) state. In addition, a
905peer may have a single Message ID variable used in messages to many
906CoAP endpoints it communicates with, which partly breaks
907sequentiality from the receiving CoAP endpoint’s
908perspective. Finally, some peers might use a randomly generated MID
909values approach. Due to these specific conditions, existing sliding
910window bitfield implementations for storing received sequence numbers
911are typically not directly suitable for efficiently storing MIDs.</t>
913<t><xref target="mid-store"/> shows one example for a per-peer MID storage design: a
914table with a bitfield of a defined length <spanx style="emph">K</spanx> per entry to store
915received MIDs (one per bit) that have a value in the range
916[MID_i + 1 , MID_i + K].</t>
918<texttable title="A per-peer table for storing MIDs based on MID_i" anchor="mid-store">
919      <ttcol align='left'>MID base</ttcol>
920      <ttcol align='left'>K-bit bitfield</ttcol>
921      <ttcol align='left'>base time value</ttcol>
922      <c>MID_0</c>
923      <c>010010101001</c>
924      <c>t_0</c>
925      <c>MID_1</c>
926      <c>111101110111</c>
927      <c>t_1</c>
928      <c>… etc.</c>
929      <c>&#160;</c>
930      <c>&#160;</c>
933<t>The presence of a table row with base MID_i (regardless of the
934bitfield values) indicates that a value MID_i has been received at a
935time t_i.  Subsequently, each bitfield bit k (0…K-1) in a row i
936corresponds to a received MID value of MID_i + k + 1. If a bit k is
9370, it means a message with corresponding MID has not yet been
938received. A bit 1 indicates such a message has been received already
939at approximately time t_i. This storage structure allows e.g. with
940k=64 to store in best case up to 130 MID values using 20 bytes, as
941opposed to 260 bytes that would be needed for a non-sequential storage
944<t>The time values t_i are used for removing rows from the table
945after a preset timeout period, to keep the MID store small in size and
946enable these MIDs to be safely re-used in future communications.
947(Note that the table only stores one time value per row, which
948therefore needs to be updated on receipt of another MID that is stored
949as a single bit in this row.  As a consequence of only storing one
950time value per row, older MID entries typically time out later than
951with a simple per-MID time value storage scheme.  The endpoint
952therefore needs to ensure that this additional delay before MID
953entries are removed from the table is much smaller than the time
954period after which a peer starts to re-use MID values due to
955wrap-around of a peer’s MID variable. One solution is to check that a
956value t_i in a table row is still recent enough, before using the row
957and updating the
958value t_i to current time. If not recent enough, e.g. older than N
959seconds, a new row with an empty bitfield is
961[Clearly, these optimizations would benefit if the peer were much more conservative about re-using MIDs than currently required in the protocol specification.]</t>
963<t>The optimization described is less efficient for storing randomized
964MIDs that a CoAP endpoint may encounter from certain peers.  To solve
965this, a storage algorithm may start in a simple MID storage mode,
966first assuming that the peer produces non-sequential MIDs. While
967storing MIDs, a heuristic is then applied based on monitoring some
968“hit rate”, for example, the number of MIDs received that have a Most
969Significant Byte equal to that of the previous MID divided by the
970total number of MIDs received.  If the hit rate tends towards 1 over a
971period of time, the MID store may decide that this particular CoAP
972endpoint uses sequential MIDs and in response improve efficiency by
973switching its mode to the bitfield based storage.</t>
977<section anchor="alternative-configurations" title="Alternative Configurations">
979<section anchor="parameters" title="Transmission Parameters">
981<t>When a constrained network of CoAP nodes is not communicating over the
982Internet, for instance because it is shielded by a proxy or a
983closed deployment, alternative transmission parameters can be used.
984Consequently, the derived time values provided in <xref target="RFC7252"/>
985section 4.8.2 will also need to be adjusted, since most implementations
986will encode their absolute values.</t>
988<t>Static adjustments require a fixed deployment with a constant number or upper
989bound for the number of nodes, number of hops, and expected concurrent
990transmissions. Furthermore, the stability of the wireless links should be
991evaluated. ACK_TIMEOUT should be chosen above the xx% percentile of the
992round-trip time distribution. ACK_RANDOM_FACTOR depends on the number of nodes
993on the network. MAX_RETRANSMIT should be chosen suitable for the targeted
994application. A lower bound for LEISURE can be calculated as</t>
996<t>lb_Leisure = S * G / R</t>
998<t>where S is the estimated response size, G the group size, and R the target data
999transfer rate (see <xref target="RFC7252"/> section 8.2). NSTART and
1000PROBING_RATE depend on estimated network utilization. If the main cause for
1001loss are weak links, higher values can be chosen.</t>
1003<t>Dynamic adjustments will be performed by advanced congestion control mechanisms
1004such as <xref target="I-D.bormann-core-cocoa"/>. They are required if the main cause for
1005message loss is network or endpoint congestion. Semi-dynamic adjustments
1006could be implemented by disseminating new static transmission parameters to
1007all nodes when the network configuration changes (e.g., new nodes are added
1008or long-lasting interference is detected).</t>
1011<section anchor="coap-over-ipv4" title="CoAP over IPv4">
1013<t>CoAP was designed for the properties of IPv6, which is dominating in constrained
1014environments because of the 6LoWPAN adaption layer <xref target="RFC6282"/>. In particular,
1015the size limitations of CoAP are tailored to the minimal MTU of 1280 bytes.
1016Until the transition towards IPv6 converges, CoAP nodes might also communicate
1017over IPv4, though. Sections 4.2 and 4.6 of the base specification
1018<xref target="RFC7252"/> already provide guidance and implementation notes to
1019handle the smaller minimal MTUs of IPv4.</t>
1021<t>Another deployment issue in legacy IPv4 deployments is caused by Network Address Translators (NATs).
1022The session timeouts are unpredictable and NATs may close UDP sessions with timeout as short as 60 seconds. This makes CoAP endpoints behind NATs practically unreachable, even when they contact the remote endpoint with a public IP address first. Incorrect behavior may also arise when the NAT session heuristic changes the external port between two successive CoAP messages. For the remote endpoint, this will look like two different CoAP endpoints on the same IP address. Such behavior can be fatal for the resource directory registration interface.</t>
1026<section anchor="binding-to-specific-lower-layer-apis" title="Binding to specific lower-layer APIs">
1028<t>Implementing CoAP on specific lower-layer APIs appears to consistently
1029bring up certain less-known aspects of these APIs.  This section is
1030intended to alert implementers to such aspects.</t>
1032<section anchor="berkeley-socket-interface" title="Berkeley Socket Interface">
1034<section anchor="responding-from-the-right-address" title="Responding from the right address">
1036<t>In order for a client to recognize a reply (response or
1037acknowledgement) as coming from the endpoint to which the initiating
1038packet was addressed, the source IPv6 address of the reply needs to
1039match the destination address of the initiating packet.</t>
1041<t>Implementers that have previously written TCP-based applications are
1042used to binding their server sockets to INADDR_ANY.  Any TCP
1043connection received over such a socket is then more specifically bound
1044to the source address from which the TCP connection setup was
1045received; no programmer action is needed for this.</t>
1047<t>For stateless UDP sockets, more manual work is required.
1048Simply receiving a packet from a UDP socket bound to INADDR_ANY loses
1049the information about the destination address; replying to it through
1050the same socket will use the default address established by the kernel.
1051Two strategies are available:</t>
1053<t><list style="symbols">
1054  <t>Only use sockets bound to a specific address (not INADDR_ANY).  A
1055system with multiple interfaces (or addresses) will thus need to
1056bind multiple sockets and send replies back on the same socket the
1057initiating packet was received on.</t>
1058  <t>Use IPV6_RECVPKTINFO <xref target="RFC3542"/> to configure the socket, and mirror
1059back the IPV6_PKTINFO information for the reply (see also
1060<xref target="managing-interfaces"/>).</t>
1063<section anchor="managing-interfaces" title="Managing interfaces">
1065<t>For some applications, it may further be relevant what interface is
1066chosen to send to an endpoint, beyond the kernel choosing one that has
1067a routing table entry for the destination address.
1068E.g., it may be natural to send out a response or acknowledgment on
1069the same interface that the packet prompting it was received.
1070The end of the introduction to section 6 of <xref target="RFC3542"/> describes a
1071simple technique for this, where that RFC’s API (IPV6_PKTINFO) is
1073The same data structure can be used for indicating an interface to
1074send a packet that is initiating an exchange.  (Choosing that
1075interface is too application-specific to be in scope for the present
1081<section anchor="java" title="Java">
1083<t>Java provides a wildcard address ( to bind a socket to all network interface.
1084This is useful when a server is supposed to listen on any available interface including the lookback address.
1085For UDP, and hence CoAP this poses a problem, however, because the DatagramPacket class does not provide the information to which address it was sent.
1086When replying through the wildcard socket, the JVM will pick the default address, which can break the correlation of messages when the remote endpoint did not send the message to the default address.
1087This is in particular precarious for IPv6 where it is common to have multiple IP addresses per network interface.
1088Thus, it is recommended to bind to all adresses explicitly and manage the destination address of incoming messages within the CoAP implementation.</t>
1091<section anchor="multicast-detection" title="Multicast detection">
1093<t>Similar to the considerations above, Section 8 of <xref target="RFC7252"/> requires
1094a node to detect whether a packet that it is going to reply to was
1095sent to a unicast or to a multicast address.  On most platforms,
1096binding a UDP socket to a unicast address ensures that it only
1097receives packets addressed to that address.  Programmers relying on
1098this property should ensure that it indeed applies to the platform
1099they are using.
1100If it does not, IPV6_PKTINFO may, again, help for Berkeley Socket Interfaces.
1101For Java, explicit management of different sockets (in this case a MulticastSocket) is required.</t>
1104<section anchor="dtls" title="DTLS">
1106<t>CoAPS implementations require access to the authenticated user/device prinicipal to realize access control for resources.
1107How this information can be accessed heavily depends on the DTLS implementation used.
1108Generic and portable CoAP implementations might want to provide an abstraction layer that can be used by application developers that implement resource handlers.
1109It is recommended to keep the API of such an application layer close to popular HTTPS solutions that are available for the targeted platform, for instance, mod_ssl or the Java Servlet API.</t>
1113<section anchor="coap-on-various-transports" title="CoAP on various transports">
1115<t>As specified in <xref target="RFC7252"/>, CoAP is defined for two underlying
1116transports: UDP and DTLS.  These transports are relatively similar in
1117terms of the properties they expose to their users.  (The main
1118difference, apart from the increased security, is that DTLS provides
1119an abstraction of a connection, into which the endpoint abstraction is
1120placed; in contrast, the UDP endpoint abstraction is based on
1121four-tuples of IP addresses and ports.)</t>
1123<t>Recently, the need to carry CoAP over other transports <xref target="I-D.silverajan-core-coap-alternative-transports"/>
1124has led to specifications such as CoAP over TLS or TCP <xref target="I-D.tschofenig-core-coap-tcp-tls"/> or
1125websockets <xref target="I-D.savolainen-core-coap-websockets"/>, or even over non-IP transports such as SMS <xref target="I-D.becker-core-coap-sms-gprs"/>.
1126This section discusses considerations that arise when handling these
1127different transports in an implementation.</t>
1129<section anchor="coap-over-reliable-transports" title="CoAP over reliable transports">
1131<t>To cope with transports without reliable delivery (such as UDP and
1132DTLS), CoAP defines its own message layer, with acknowledgments,
1133timers, and retransmission.  When CoAP is run over a transport that
1134provides its own reliability (such as TCP or TLS), running this
1135machinery would be redundant.  Worse, keeping the machinery in place
1136is likely to lead to interoperability problems as it is unlikely to be
1137tested as well as on unreliable transports.  Therefore, <xref target="I-D.silverajan-core-coap-alternative-transports"/>
1138was defined by removing the message layer from CoAP and just running
1139the request/response layer directly on top of the reliable transport.
1140This also leads to a reduced (from the UDP/DTLS 4-byte header) header
1143<t>Conversely, where reliable transports provide a byte stream
1144abstraction, some form of message delimiting had to be added, which
1145now needs to be handled in the CoAP implementation.
1146The use of reliable transports may reduce the disincentive for using
1147messages larger than optimal link layer packet sizes.  Where different
1148message sizes are chosen by an application for reliable and for
1149unreliable transports, this can pose additional challenges for
1150translators (<xref target="trans"/>).</t>
1152<t>Where existing CoAP APIs expose details of the the message layer
1153(e.g., CON vs. NON, or assigning application layer semantics to ACKs),
1154using a reliable transport may require additional adjustments.</t>
1157<section anchor="trans" title="Translating between transports">
1159<t>One obvious way to convey CoAP exchanges between different
1160transports is to run a CoAP proxy that supports both transports.
1161The usual considerations for proxies apply.  <xref target="transprox"/> discusses
1162some additional considerations.</t>
1164<t>Where not much of the functionality of CoAP proxies (such as caching)
1165is required, a simpler 1:1 translation may be possible, as discussed
1166in <xref target="transonetoone"/>.</t>
1168<section anchor="transprox" title="Transport translation by proxies">
1170<t>(TBD.  In particular, point out the obvious: fan-in/fan-out means that
1171separate message ID and token spaces need to be maintained at the ends
1172of the proxy.)</t>
1174<t>One more CoAP specific function of a transport translator proxy may be
1175to convert between different block sizes, e.g. between a TCP
1176connection that can tolerate large blocks and UDP over a constrained
1177node network.</t>
1180<section anchor="transonetoone" title="One-to-one Transport translation">
1182<t>A translator with reduced requirements for state maintenance
1183can be constructed when no fan-in or fan-out is required, and when the
1184namespace lifetimes of the two sides can be made to coincide.
1185For this one-to-one translation, there is no need to manage message-ID
1186and Token value spaces for both sides separately.
1187So, a simple UDP-to-UDP one-to-one translator could simply copy the
1188messages (among other applications, this might be useful for
1189translation between IPv4 and IPv6 spaces).
1190Similarly, a DTLS-to-TCP translator could be built that executes the message
1191layer (deduplication, retransmission) on the DTLS side, and
1192repackages the CoAP header (add/remove the length information, and
1193remove/add the message ID and message type) between the DTLS and the TCP side.
1194<!-- ... more about connection management ... --></t>
1196<t>By definition, such a simple one-to-one translator needs to shut down
1197the connection on one side when the connection on the other side
1199However, a UDP-to-TCP one-to-one translator cannot simply shut down
1200the UDP endpoint when the TCP endpoint vanishes because the TCP
1201connection closes, so some additional management of state will be
1207<section anchor="iana-considerations" title="IANA considerations">
1209<t>This document has no actions for IANA.</t>
1212<section anchor="security-considerations" title="Security considerations">
1217<section anchor="acknowledgements" title="Acknowledgements">
1219<t>Esko Dijk contributed the sequential MID optimization. Xuan He provided help creating and improved the state machine charts.</t>
1221<!--  LocalWords:  CoAP lossy LLN KiB optimizations scalability URIs
1222 -->
1223<!--  LocalWords:  tradeoff Confirmable MTU blockwise LoWPAN datagram
1224 -->
1225<!--  LocalWords:  retransmission deduplication datagrams RST TKL URI
1226 -->
1227<!--  LocalWords:  preselect IP memmove UDP NoSec DTLS GiB ACK ACKs
1228 -->
1229<!--  LocalWords:  namespace FSM NONs retransmitting acknowledgement
1230 -->
1231<!--  LocalWords:  ICMP misconfiguration APIs RESTful API Uri UART
1232 -->
1233<!--  LocalWords:  checkpointing programmatically confirmable CoAP's
1234 -->
1235<!--  LocalWords:  retransmissions Acknowledgements JSON Implementers
1236 -->
1237<!--  LocalWords:  CoRE MIDs implementers sequentiality bitfield IPv
1238 -->
1239<!--  LocalWords:  MTUs RFC's PKTINFO Multicast unicast multicast TCP
1240 -->
1241<!--  LocalWords:  INADDR RECVPKTINFO IANA
1242 -->
1247  </middle>
1249  <back>
1251    <references title='Normative References'>
1257<reference anchor='RFC7230'>
1260<title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
1261<author initials='R.' surname='Fielding' fullname='R. Fielding'>
1262<organization /></author>
1263<author initials='J.' surname='Reschke' fullname='J. Reschke'>
1264<organization /></author>
1265<date year='2014' month='June' />
1267<t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems.  This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.</t></abstract></front>
1269<seriesInfo name='RFC' value='7230' />
1270<format type='TXT' octets='205947' target='' />
1275<reference anchor='RFC6570'>
1278<title>URI Template</title>
1279<author initials='J.' surname='Gregorio' fullname='J. Gregorio'>
1280<organization /></author>
1281<author initials='R.' surname='Fielding' fullname='R. Fielding'>
1282<organization /></author>
1283<author initials='M.' surname='Hadley' fullname='M. Hadley'>
1284<organization /></author>
1285<author initials='M.' surname='Nottingham' fullname='M. Nottingham'>
1286<organization /></author>
1287<author initials='D.' surname='Orchard' fullname='D. Orchard'>
1288<organization /></author>
1289<date year='2012' month='March' />
1291<t>A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion.  This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK]</t></abstract></front>
1293<seriesInfo name='RFC' value='6570' />
1294<format type='TXT' octets='79813' target='' />
1299<reference anchor='RFC6633'>
1302<title>Deprecation of ICMP Source Quench Messages</title>
1303<author initials='F.' surname='Gont' fullname='F. Gont'>
1304<organization /></author>
1305<date year='2012' month='May' />
1307<t>This document formally deprecates the use of ICMP Source Quench messages by transport protocols, formally updating RFC 792, RFC 1122, and RFC 1812. [STANDARDS-TRACK]</t></abstract></front>
1309<seriesInfo name='RFC' value='6633' />
1310<format type='TXT' octets='16367' target='' />
1315<reference anchor='RFC6282'>
1318<title>Compression Format for IPv6 Datagrams over IEEE 802.15.4-Based Networks</title>
1319<author initials='J.' surname='Hui' fullname='J. Hui'>
1320<organization /></author>
1321<author initials='P.' surname='Thubert' fullname='P. Thubert'>
1322<organization /></author>
1323<date year='2011' month='September' />
1325<t>This document updates RFC 4944, "Transmission of IPv6 Packets over IEEE 802.15.4 Networks".  This document specifies an IPv6 header compression format for IPv6 packet delivery in Low Power Wireless Personal Area Networks (6LoWPANs).  The compression format relies on shared context to allow compression of arbitrary prefixes.  How the information is maintained in that shared context is out of scope.  This document specifies compression of multicast addresses and a framework for compressing next headers.  UDP header compression is specified within this framework. [STANDARDS-TRACK]</t></abstract></front>
1327<seriesInfo name='RFC' value='6282' />
1328<format type='TXT' octets='52588' target='' />
1333<reference anchor='RFC7252'>
1336<title>The Constrained Application Protocol (CoAP)</title>
1337<author initials='Z.' surname='Shelby' fullname='Z. Shelby'>
1338<organization /></author>
1339<author initials='K.' surname='Hartke' fullname='K. Hartke'>
1340<organization /></author>
1341<author initials='C.' surname='Bormann' fullname='C. Bormann'>
1342<organization /></author>
1343<date year='2014' month='June' />
1345<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 IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation.&lt;/t>&lt;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>
1347<seriesInfo name='RFC' value='7252' />
1348<format type='TXT' octets='258789' target='' />
1353<reference anchor='I-D.ietf-core-observe'>
1355<title>Observing Resources in CoAP</title>
1357<author initials='K' surname='Hartke' fullname='Klaus Hartke'>
1358    <organization />
1361<date month='December' day='30' year='2014' />
1363<abstract><t>The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks.  The state of a resource on a CoAP server can change over time.  This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time.  The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server.</t></abstract>
1367<seriesInfo name='Internet-Draft' value='draft-ietf-core-observe-16' />
1368<format type='TXT'
1369        target='' />
1374<reference anchor='I-D.ietf-core-block'>
1376<title>Block-wise transfers in CoAP</title>
1378<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
1379    <organization />
1382<author initials='Z' surname='Shelby' fullname='Zach Shelby'>
1383    <organization />
1386<date month='March' day='9' year='2015' />
1388<abstract><t>CoAP is a RESTful transfer protocol for constrained nodes and networks.  Basic CoAP messages work well for the small payloads we expect from temperature sensors, light switches, and similar building-automation devices.  Occasionally, however, applications will need to transfer larger payloads -- for instance, for firmware updates.  With HTTP, TCP does the grunt work of slicing large payloads up into multiple packets and ensuring that they all arrive and are handled in the right order.  CoAP is based on datagram transports such as UDP or DTLS, which limits the maximum size of resource representations that can be transferred without too much fragmentation.  Although UDP supports larger payloads through IP fragmentation, it is limited to 64 KiB and, more importantly, doesn't really work well for constrained applications and networks.  Instead of relying on IP fragmentation, this specification extends basic CoAP with a pair of "Block" options, for transferring multiple blocks of information from a resource representation in multiple request-response pairs.  In many important cases, the Block options enable a server to be truly stateless: the server can handle each block transfer separately, with no need for a connection setup or other server-side memory of previous block transfers.  In summary, the Block options provide a minimal way to transfer larger representations in a block-wise fashion.</t></abstract>
1392<seriesInfo name='Internet-Draft' value='draft-ietf-core-block-17' />
1393<format type='TXT'
1394        target='' />
1399<reference anchor='I-D.bormann-core-cocoa'>
1401<title>CoAP Simple Congestion Control/Advanced</title>
1403<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
1404    <organization />
1407<author initials='A' surname='Betzler' fullname='August Betzler'>
1408    <organization />
1411<author initials='C' surname='Gomez' fullname='Carles Gomez'>
1412    <organization />
1415<author initials='I' surname='Demirkol' fullname='Ilker Demirkol'>
1416    <organization />
1419<date month='July' day='3' year='2014' />
1421<abstract><t>The CoAP protocol needs to be implemented in such a way that it does not cause persistent congestion on the network it uses.  The CoRE CoAP specification defines basic behavior that exhibits low risk of congestion with minimal implementation requirements.  It also leaves room for combining the base specification with advanced congestion control mechanisms with higher performance.  This specification defines some simple advanced CoRE Congestion Control mechanisms, Simple CoCoA.  In the present version -02, it is making use of input from simulations and experiments in real networks.  The specification might still benefit from simplifying it further.</t></abstract>
1425<seriesInfo name='Internet-Draft' value='draft-bormann-core-cocoa-02' />
1426<format type='TXT'
1427        target='' />
1433    </references>
1435    <references title='Informative References'>
1441<reference anchor='RFC7228'>
1444<title>Terminology for Constrained-Node Networks</title>
1445<author initials='C.' surname='Bormann' fullname='C. Bormann'>
1446<organization /></author>
1447<author initials='M.' surname='Ersue' fullname='M. Ersue'>
1448<organization /></author>
1449<author initials='A.' surname='Keranen' fullname='A. Keranen'>
1450<organization /></author>
1451<date year='2014' month='May' />
1453<t>The Internet Protocol Suite is increasingly used on small devices with severe constraints on power, memory, and processing resources, creating constrained-node networks.  This document provides a number of basic terms that have been useful in the standardization work for constrained-node networks.</t></abstract></front>
1455<seriesInfo name='RFC' value='7228' />
1456<format type='TXT' octets='37635' target='' />
1461<reference anchor='RFC3542'>
1464<title>Advanced Sockets Application Program Interface (API) for IPv6</title>
1465<author initials='W.' surname='Stevens' fullname='W. Stevens'>
1466<organization /></author>
1467<author initials='M.' surname='Thomas' fullname='M. Thomas'>
1468<organization /></author>
1469<author initials='E.' surname='Nordmark' fullname='E. Nordmark'>
1470<organization /></author>
1471<author initials='T.' surname='Jinmei' fullname='T. Jinmei'>
1472<organization /></author>
1473<date year='2003' month='May' />
1475<t>This document provides sockets Application Program Interface (API) to support "advanced" IPv6 applications, as a supplement to a separate specification, RFC 3493.  The expected applications include Ping, Traceroute, routing daemons and the like, which typically use raw sockets to access IPv6 or ICMPv6 header fields.  This document proposes some portable interfaces for applications that use raw sockets under IPv6.  There are other features of IPv6 that some applications will need to access: interface identification (specifying the outgoing interface and determining the incoming interface), IPv6 extension headers, and path Maximum Transmission Unit (MTU) information.  This document provides API access to these features too.  Additionally, some extended interfaces to libraries for the "r" commands are defined.  The extension will provide better backward compatibility to existing implementations that are not IPv6-capable.  This memo provides information for the Internet community.</t></abstract></front>
1477<seriesInfo name='RFC' value='3542' />
1478<format type='TXT' octets='173028' target='' />
1483<reference anchor='I-D.silverajan-core-coap-alternative-transports'>
1485<title>CoAP Communication with Alternative Transports</title>
1487<author initials='B' surname='Silverajan' fullname='Bill Silverajan'>
1488    <organization />
1491<author initials='T' surname='Savolainen' fullname='Teemu Savolainen'>
1492    <organization />
1495<date month='June' day='20' year='2015' />
1497<abstract><t>CoAP has been standardised as an application level REST-based protocol.  A single CoAP message is typically encapsulated and transmitted using UDP or DTLS as transports.  These transports are optimal solutions for CoAP use in IP-based constrained environments and nodes.  However compelling motivation exists for allowing CoAP to operate with other transports and protocols.  Examples are M2M communication in cellular networks using SMS, more suitable transport protocols for firewall/NAT traversal, end-to-end reliability and security such as TCP and TLS, or employing proxying and tunneling gateway techniques such as the WebSocket protocol.  This draft examines the requirements for conveying CoAP messages to end points over such alternative transports.  It also provides a new URI format for representing CoAP resources over alternative transports.</t></abstract>
1501<seriesInfo name='Internet-Draft' value='draft-silverajan-core-coap-alternative-transports-08' />
1502<format type='TXT'
1503        target='' />
1508<reference anchor='I-D.savolainen-core-coap-websockets'>
1510<title>CoAP over WebSockets</title>
1512<author initials='T' surname='Savolainen' fullname='Teemu Savolainen'>
1513    <organization />
1516<author initials='K' surname='Hartke' fullname='Klaus Hartke'>
1517    <organization />
1520<author initials='B' surname='Silverajan' fullname='Bill Silverajan'>
1521    <organization />
1524<date month='March' day='31' year='2015' />
1526<abstract><t>This document specifies how to retrieve and update CoAP resources using CoAP requests and responses over the WebSocket Protocol.</t></abstract>
1530<seriesInfo name='Internet-Draft' value='draft-savolainen-core-coap-websockets-04' />
1531<format type='TXT'
1532        target='' />
1537<reference anchor='I-D.tschofenig-core-coap-tcp-tls'>
1539<title>A TCP and TLS Transport for the Constrained Application Protocol (CoAP)</title>
1541<author initials='C' surname='Bormann' fullname='Carsten Bormann'>
1542    <organization />
1545<author initials='S' surname='Lemay' fullname='Simon Lemay'>
1546    <organization />
1549<author initials='Z' surname='Technologies' fullname='Zebra Technologies'>
1550    <organization />
1553<author initials='H' surname='Tschofenig' fullname='Hannes Tschofenig'>
1554    <organization />
1557<date month='June' day='10' year='2015' />
1559<abstract><t>The Hypertext Transfer Protocol (HTTP) has been designed with TCP as an underlying transport protocol.  The Constrained Application Protocol (CoAP), which has been inspired by HTTP, has on the other hand been defined to make use of UDP.  Therefore, reliable delivery and a simple congestion control and flow control mechanism are provided by the message layer of the CoAP protocol.  A number of environments benefit from the use of CoAP directly over a reliable byte stream that already provides these services.  This document defines the use of CoAP over TCP as well as CoAP over TLS.</t></abstract>
1563<seriesInfo name='Internet-Draft' value='draft-tschofenig-core-coap-tcp-tls-04' />
1564<format type='TXT'
1565        target='' />
1570<reference anchor='I-D.becker-core-coap-sms-gprs'>
1572<title>Transport of CoAP over SMS</title>
1574<author initials='M' surname='Becker' fullname='Markus Becker'>
1575    <organization />
1578<author initials='K' surname='Li' fullname='Kepeng Li'>
1579    <organization />
1582<author initials='K' surname='Kuladinithi' fullname='Koojana Kuladinithi'>
1583    <organization />
1586<author initials='T' surname='Poetsch' fullname='Thomas Poetsch'>
1587    <organization />
1590<date month='August' day='8' year='2014' />
1592<abstract><t>Short Message Service (SMS) of mobile cellular networks is frequently used in Machine-To-Machine (M2M) communications, such as for telematic devices.  The service offers small packet sizes and high delays just as other typical low-power and lossy networks (LLNs), i.e. 6LoWPANs.  The design of the Constrained Application Protocol (CoAP) [RFC7252], that took the limitations of LLNs into account, is thus also applicable to other transports.  The adaptation of CoAP to SMS transport mechanisms is described in this document.</t></abstract>
1596<seriesInfo name='Internet-Draft' value='draft-becker-core-coap-sms-gprs-05' />
1597<format type='TXT'
1598        target='' />
1602<reference anchor="TinyOS" >
1603  <front>
1604    <title>TinyOS: An Operating System for Sensor Networks</title>
1605    <author initials="P." surname="Levis">
1606      <organization></organization>
1607    </author>
1608    <author initials="S." surname="Madden">
1609      <organization></organization>
1610    </author>
1611    <author initials="J." surname="Polastre">
1612      <organization></organization>
1613    </author>
1614    <author initials="R." surname="Szewczyk">
1615      <organization></organization>
1616    </author>
1617    <author initials="K." surname="Whitehouse">
1618      <organization></organization>
1619    </author>
1620    <author initials="A." surname="Woo">
1621      <organization></organization>
1622    </author>
1623    <author initials="D." surname="Gay">
1624      <organization></organization>
1625    </author>
1626    <author initials="A." surname="Woo">
1627      <organization></organization>
1628    </author>
1629    <author initials="J." surname="Hill">
1630      <organization></organization>
1631    </author>
1632    <author initials="M." surname="Welsh">
1633      <organization></organization>
1634    </author>
1635    <author initials="E." surname="Brewer">
1636      <organization></organization>
1637    </author>
1638    <author initials="D." surname="Culler">
1639      <organization></organization>
1640    </author>
1641    <date year="2005"/>
1642  </front>
1643  <seriesInfo name="Ambient intelligence, Springer" value="(Berlin Heidelberg)"/>
1644  <seriesInfo name="ISBN" value="978-3-540-27139-0"/>
1646<reference anchor="Contiki" >
1647  <front>
1648    <title>Contiki - a Lightweight and Flexible Operating System for Tiny Networked Sensors</title>
1649    <author initials="A." surname="Dunkels" fullname="Adam Dunkels">
1650      <organization></organization>
1651    </author>
1652    <author initials="B." surname="Grönvall" fullname="Björn Grönvall">
1653      <organization></organization>
1654    </author>
1655    <author initials="T." surname="Voigt" fullname="Thiemo Voigt">
1656      <organization></organization>
1657    </author>
1658    <date year="2004" month="November"/>
1659  </front>
1660  <seriesInfo name="Proceedings of the First IEEE Workshop" value="on Embedded Networked Sensors"/>
1666<reference anchor='RFC5927'>
1669<title>ICMP Attacks against TCP</title>
1670<author initials='F.' surname='Gont' fullname='F. Gont'>
1671<organization /></author>
1672<date year='2010' month='July' />
1674<t>This document discusses the use of the Internet Control Message Protocol (ICMP) to perform a variety of attacks against the Transmission Control Protocol (TCP).  Additionally, this document describes a number of widely implemented modifications to TCP's handling of ICMP error messages that help to mitigate these issues.  This document is not an Internet Standards Track specification; it is published for informational purposes.</t></abstract></front>
1676<seriesInfo name='RFC' value='5927' />
1677<format type='TXT' octets='87744' target='' />
1683    </references>
1687  </back>
Note: See TracBrowser for help on using the repository browser.