CoAP Implementation Guidance
draft-kovatsch-lwig-coap-03

Abstract

The Constrained Application Protocol (CoAP) is designed for resource-constrained nodes and networks, e.g., sensor nodes in a low-power lossy network (LLN). Yet to implement this Internet protocol on Class 1 devices (i.e., ~ 10 KiB of RAM and ~ 100 KiB of ROM) also lightweight implementation techniques are necessary. This document provides lessons learned from implementing CoAP for tiny, battery-operated networked embedded systems. In particular, it provides guidance on correct implementation of the CoAP specification [I-D.ietf-core-coap], memory optimizations, and customized protocol parameters.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on September 01, 2014.

Copyright Notice

Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 2. Protocol Implementation
• 2.1. Client/Server Model
• 2.2. Message Processing
• 2.2.1. On-the-fly Processing
• 2.2.2. Internal Data Structure
• 2.3. Duplicate Rejection
• 2.4. Token Usage
• 2.4.1. Tokens for Observe
• 2.4.2. Tokens for Blockwise Transfers
• 2.5. Transmission States
• 2.5.1. Request/Response Layer
• 2.5.2. Message Layer
• 2.6. Out-of-band Information
• 2.7. Programming Model
• 2.7.1. Client
• 2.7.2. Server
• 3. Optimizations
• 3.1. Message Buffers
• 3.2. Retransmissions
• 3.3. Observable Resources
• 3.4. Blockwise Transfers
• 3.5. Deduplication with Sequential MIDs
• 4. Alternative Configurations
• 4.1. Transmission Parameters
• 4.2. CoAP over IPv4
• 5. References
• 5.1. Normative References
• 5.2. Informative References
• Authors' Addresses

1. Introduction

The Constrained Application Protocol [I-D.ietf-core-coap] has been designed specifically for machine-to-machine communication in networks with very constrained nodes. Typical application scenarios therefore include building automation, process optimization, and the Internet of Things. The major design objectives have been set on small protocol overhead, robustness against packet loss, and against high latency induced by small bandwidth shares or slow request processing in end nodes. To leverage integration of constrained nodes with the world-wide Internet, the protocol design was led by the REST architectural style that accounts for the scalability and robustness of the Hypertext Transfer Protocol [RFC2616].

Lightweight implementations benefit from this design in many respects: First, the use of Uniform Resource Identifiers (URIs) for naming resources and the transparent forwarding of their representations in a server-stateless request/response protocol make protocol translation to HTTP a straightforward task. Second, the set of protocol elements that are unavoidable for the core protocol and thus must be implemented on every node has been kept very small, minimizing the unnecessary accumulation of “optional” features. Options that – when present – are critical for message processing are explicitly marked as such to force immediate rejection of messages with unknown critical options. Third, the syntax of protocol data units is easy to parse and is carefully defined to avoid creation of state in servers where possible.

Although these features enable lightweight implementations of the Constrained Application Protocol, there is still a tradeoff between robustness and latency of constrained nodes on one hand and resource demands on the other. For constrained nodes of Class 1 or even Class 2, the most limiting factors usually are dynamic memory needs, static code size, and energy. Most implementations therefore need to optimize internal buffer usage, omit idle protocol feature, and maximize sleeping cycles.

The present document gives possible strategies to solve this tradeoff for very constrained nodes (i.e., Class 1 in [I-D.ietf-lwig-terminology]). For this, it provides guidance on correct implementation of the CoAP specification [I-D.ietf-core-coap], memory optimizations, and customized protocol parameters.

2. Protocol Implementation

In the programming styles supported by very simple operating systems as found on constrained nodes, preemptive multi-threading is not an option. Instead, all operations are triggered by an event loop system, e.g., in a send-receive-dispatch cycle. It is also common practice to allocate memory statically to ensure stable behavior, as no memory management unit (MMU) or other abstractions are available. For a CoAP node, the two key parameters for memory usage are the number of (re)transmission buffers and the maximum message size that must be supported by each buffer. Often the maximum message size is set far below the 1280-byte MTU of 6LoWPAN to allow more than one open Confirmable transmission at a time (in particular for parallel observe notifications). Note that implementations on constrained platforms often not even support the full MTU. Larger messages must then use blockwise transfers [I-D.ietf-core-block], while a good tradeoff between 6LoWPAN fragmentation and CoAP header overhead must be found. Usually the amount of available free RAM dominates this decision. For Class 1 devices, the maximum message size is typically 128 or 256 bytes (blockwise) payload plus an estimate of the maximum header size with a worst case option setting.

2.1. Client/Server Model

In general, CoAP servers can be implemented more efficiently than clients. REST allows them to keep the communication stateless and piggy-backed responses are not stored for retransmission, saving buffer space. The use of idempotent requests also allows to relax deduplication, which further decreases memory usage. It is also easy to estimate the required maximum size of message buffers, since URI paths, supported options, and maximum payload sizes of the application are known at compile time. Hence, when the application is distributed over constrained and unconstrained nodes, the constrained ones should preferably have the server role.

HTTP-based applications have established an inversed model because of the need for simple push notifications: A constrained client uses POST requests to update resources on an unconstrained server whenever an event, e.g., a new sensor reading, is triggered. This requirement is solved by the Observe option [I-D.ietf-core-observe] of CoAP. It allows servers to initiate communication and send push notifications to interested client nodes. This allows a more efficient and also more natural model for CoAP-based applications, where the information source is in server role and can benefit from caching.

2.2. Message Processing

Apart from the required buffers, message processing is symmetric for clients and servers. First the 4-byte base header has to be parsed and thereby checked if it is a CoAP message. Since the encoding is very dense, only a wrong Version or a datagram size smaller than four bytes identify non-CoAP datagrams. These MUST be silently ignored. All other message format errors, such as an incomplete datagram length or the usage of reserved values, MUST be rejected with a Reset (RST) message. Next the Token is read based on the TKL field. For the following header options, there are two alternatives: Either process the header on the fly when an option is accessed or initially parse all values into an internal data structure.

2.2.1. On-the-fly Processing

The advantage of on-the-fly processing is that no additional memory needs to be allocated to store the option values, which are stored efficiently inline in the buffer for incoming messages. Once the message is accepted for further processing, the set of options contained in the received message must be decoded to check for unknown critical options. To avoid multiple passes through the option list, the option parser might maintain a bit-vector where each bit represents an option number that is present in the received request. With the wide and sparse range of option numbers, the number itself cannot be used to indicate the number of left-shift operations to mask the corresponding bit. Hence, an implementation-specific enum of supported options should be used to mask the present options of a message in the bitmap. In addition, the byte index of every option (a direct pointer) can be added to a sparse list (e.g., a one-dimensional array) for fast retrieval.

This particularly enables efficient handling of options that might occur more than once such as Uri-Path. In this implementation strategy, the delta is zero for any subsequent path segment, hence the stored byte index for this option (e.g., 11 for Uri-Path) would be overwritten to hold a pointer to only the last occurrence of that option. The Uri-Path can be resolved on the fly, though, and a pointer to the targeted resource stored directly in the sparse list. In simpler cases, conditionals can preselect one of the repeated option values.

Once the option list has been processed, all known critical option and all elective options can be masked out in the bit-vector to determine if any unknown critical option was present. If this is the case, this information can be used to create a 4.02 response accordingly. Note that full processing must only be done up to the highest supported option number. Beyond that, only the least significant bit (Critical or Elective) needs to be checked. Otherwise, if all critical options are supported, the sparse list of option pointers is used for further handling of the message.

2.2.2. Internal Data Structure

Using an internal data structure for all parsed options has advantage when working on the option values, as they are already in a variable of corresponding type, e.g., an integer in host byte order. The incoming payload and byte strings of the header can be accessed directly in the buffer for incoming messages using pointers (similar to on-the-fly processing). This approach also benefits from a bitmap. Otherwise special values must be reserved to encode an unset option, which might require a larger type than required for the actual value range (e.g., a 32-bit integer instead of 16-bit).

The byte strings (e.g., the URI) are usually not required when generating the response. And since all important values were copied, this alternative facilitates using the buffer for incoming messages also for the assembly of outgoing messages – which can be the shared IP buffer provided by the OS.

Setting options for outgoing messages is also easier with an internal data structure. Application developers can set options independent from the option number, whose order is required for the delta encoding. The CoAP encoding is then applied in a serialization step before sending. In contrast, assembling outgoing messages with on-the-fly processing requires either extensive memmove operations to insert new header options or restrictions for developers to set options in their correct order.

2.3. Duplicate Rejection

If CoAP is used directly on top of UDP (i.e., in NoSec mode), it needs to cope with the fact that the UDP datagram transport can reorder and duplicate messages. (In contrast to UDP, DTLS has its own duplicate detection.) CoAP has been designed with protocol functionality such that rejection of duplicate messages is always possible. It is at the discretion of the receiver if it actually wants to make use of this functionality. Processing of duplicate messages comes at a cost, but so does the management of the state associated with duplicate rejection. The number of remote endpoints that need to be managed might be vast. This can be costly in particular for unconstrained nodes that have throughput in the order of one hundred thousand requests per second (i.e., about 16 GiB of RAM only for duplicate rejection). Deduplication is also heavy for servers on Class 1 devices, as also piggy-backed responses need to be stored for the case that the ACK message is lost. Hence, a receiver may have good reasons to decide not to do the deduplication.

If duplicate rejection is indeed necessary, e.g., for non-idempotent requests, it is important to control the amount of state that needs to be stored. It can be reduced for instance by deduplication at resource level: Knowledge of the application and supported representations can minimize the amount of state that needs to be kept. Duplicate rejection on the client side can be simplified by choosing clever Tokens and only filter based on this information (e.g., a list of Tokens currently in use or an obscured counter in the Token value).

2.4. Token Usage

Tokens are chosen by the client and help to identify request/response pairs that span several messages (e.g., a separate response, which has a new MID). Servers do not generate Tokens and only mirror what they receive from the clients. Tokens must be unique within the namespace of a client throughout their lifetime. This begins when being assigned to a request and ends when the open request is closed by receiving and matching the final response. Neither empty ACKs nor notifications (i.e., responses carrying the Observe option) terminate the lifetime of a Token.

As already mentioned, a clever assignment of Tokens can help to simplify duplicate rejection. Yet this is also important for coping with client crashes. When a client restarts during an open request and (unknowingly) re-uses the same Token, it might match the response from the previous request to the current one. Hence, when only the Token is used for matching, which is always the case for separate responses, randomized Tokens with enough entropy should be used. The 8-byte range for Tokens even allows for one-time usage throughout the lifetime of a client node. When DTLS is used, client crashes/restarts will lead to a new security handshake, thereby solving the problem of mismatching responses and/or notifications.

2.4.1. Tokens for Observe

In the case of Observe [I-D.ietf-core-observe], a request will be answered with multiple notifications and it can become hard to determine the end of a Token lifetime. When establishing an Observe relationship, the Token is registered at the server. Hence, the client partially loses control of the used Token. A client can attempt to cancel the relationship, which frees the Token upon success (i.e., the message with code 7.31 is acknowledged; see [I-D.ietf-core-observe] section 3.6). However, the client might never receive the ACK due to a temporary network outages or worse, a server crash. Although a network outage will also affect notifications so that the Observe garbage collection could apply, the server might simply not send CON notifucations during that time. Alternative Observe lifetime models such as Stubbornness(tm) might also keep relationships alive for longer periods.

Thus, Observe requests should never use the empty Token, but carefully chose the value. One option is to assign and re-use dedicated Tokens for each Observe relationship the client will establish. This is, however, critical for spoofing attacks in NoSec mode. The recommendation is to use randomized Tokens with a length of at least four bytes. Thus, dedicated ranges within the 8-byte Token space should be used when in NoSec mode. This also solves the the problem of mismatching notifications after a client crash/restart.

2.4.2. Tokens for Blockwise Transfers

In general, blockwise transfers are independent from the Token and are correlated through client endpoint address and server address and resource path (destination URI). Thus, each block may be transferred using a different Token. Still it can be beneficial to use the same Token (it is freed upon reception of a response block) for all blocks, e.g., to easily route received blocks to the same response handler.

Special care has to be taken when Block2 is combined with Observe. Notifications only carry the first block and it is up to the client to retrieve the remaining ones. These GET requests do not carry the Observe option and MUST use a different Token, since the Token from the notification is still in use.

2.5. Transmission States

CoAP endpoints must keep transmission state to manage open requests, to handle the different response modes, and to implement reliable delivery at the message layer. The following finite state machines (FSMs) model the transmissions of a CoAP exchange at the request/response layer and the message layer. These layers are linked through actions. The M_CMD() action triggers a corresponding transition at the message layer and the RR_EVT() action triggers a transition at the request/response layer. The FSMs also use guard conditions to distinguish between information that is only available through the other layer (e.g., whether a request was sent using a CON or NON message).

2.5.1. Request/Response Layer

Figure 1 depicts the two states at the request/response layer of a CoAP client. When a request is issued, a “reliable_send” or “unreliable_send” is triggered at the message layer. The WAITING state can be left through three transitions: Either the client cancels the request and triggers cancelation of a CON transmission at the message layer, the client receives a failure event from the message layer, or a receive event containing a response.

    +------------CANCEL-------------------------------+
    |        / M_CMD(cancel)                          |
    |                                                 V
    |                                              +------+
+-------+ -------RR_EVT(fail)--------------------> |      |
|WAITING|                                          | IDLE |
+-------+ -------RR_EVT(rx)[is Response]---------> |      |
    ^                / M_CMD(accept)               +------+
    |                                                 |
    +--------------------REQUEST----------------------+
               / M_CMD((un)reliable_send)

+--------+ <----------RR_EVT(rx)[is NON]---------- +------+
|SEPARATE|                                         |      |
+--------+ ----------------RESPONSE--------------> | IDLE |
    ^            / M_CMD((un)reliable_send)        |      |
    |                                        +---> +------+
    |EMPTY_ACK                               |         |         
    |/M_CMD(accept)                          |         |
    |                                        |         |
    |                                        |         |
+--------+                                   |         |
|SERVING | --------------RESPONSE------------+         |
+--------+          / M_CMD(accept)                    |
    ^                                                  |
    +------------------------RR_EVT(rx)[is CON]--------+

+-----------+ <-------M_CMD(reliable_send)-----+
|           |            / TX(con)              \
|           |                                +--------------+
|           | ---TIMEOUT(RETX_WINDOW)------> |              |
|RELIABLE_TX|     / RR_EVT(fail)             |              |
|           | ---------------------RX_RST--> |              | <----+
|           |               / RR_EVT(fail)   |              |      |
+-----------+ ----M_CMD(cancel)------------> |    CLOSED    |      |
 ^  |  |  \  \                               |              | --+  |
 |  |  |   \  +-------------------RX_ACK---> |              |   |  |
 +*1+  |    \                / RR_EVT(rx)    |              |   |  |
       |     +----RX_NON-------------------> +--------------+   |  |
       |       / RR_EVT(rx)                  ^ ^ ^ ^  | | | |   |  |
       |                                     | | | |  | | | |   |  | 
       |                                     | | | +*2+ | | |   |  |
       |                                     | | +--*3--+ | |   |  |
       |                                     | +----*4----+ |   |  |
       |                                     +------*5------+   |  |
       |                +---------------+                       |  |
       |                |  ACK_PENDING  | <--RX_CON-------------+  |
       +----RX_CON----> |               |  / RR_EVT(rx)            |
         / RR_EVT(rx)   +---------------+ ---------M_CMD(accept)---+
                                                     / TX(ack)

*1: TIMEOUT(RETX_TIMEOUT) / TX(con)
*2: M_CMD(unreliable_send) / TX(non)
*3: RX_NON / RR_EVT(rx)
*4: RX_RST / REMOVE_OBSERVER
*5: RX_ACK