| CoRE Working Group | K. Hartke |
| Internet-Draft | Ericsson |
| Updates: 7252, 8323 (if approved) | March 11, 2019 |
| Intended status: Standards Track | |
| Expires: September 12, 2019 |
Extended Tokens and Stateless Clients in the Constrained Application Protocol (CoAP)
draft-ietf-core-stateless-01
This document provides considerations for alleviating CoAP clients and intermediaries of keeping per-request state. To facilitate this, this document additionally introduces a new, optional CoAP protocol extension for extended token lengths.
This document updates RFCs 7252 and 8323.
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 https://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 12, 2019.
Copyright (c) 2019 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 (https://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.
The Constrained Application Protocol (CoAP) [RFC7252] is a RESTful application-layer protocol for constrained environments. In CoAP, clients (or intermediaries in the client role) make requests to servers (or intermediaries in the server role), which serve the requests by returning responses.
While a request is ongoing, a client typically needs to keep some state that it requires for processing the response when it arrives. Identification of this state is done by means of a token in CoAP, an opaque sequence of bytes chosen by the client and included in the CoAP request. The server returns the token verbatim in any resulting CoAP response (Figure 1).
+-----------------+ request with +------------+
| | | state identifier | |
| | | as token | |
| .-<-+->------|--------------------->|------. |
| _|_ | | | |
| / \ stored | | | |
| \___/ state | | | |
| | | | | |
| '->-+-<------|<---------------------|------' |
| | | response with | |
| v | token echoed back | |
+-----------------+ +------------+
Client Server
Figure 1: Token as an Identifier for Request State
In some scenarios, it can be beneficial to reduce the amount of state that is stored at the client at the cost of increased message sizes. Clients can implement this by serializing (parts of) their state into the token itself and recovering the state from the token in the response (Figure 2).
+-----------------+ request with +------------+
| | | serialized state | |
| | | as token | |
| +--------|=====================>|------. |
| | | | |
| look ma, | | | |
| no state! | | | |
| | | | |
| +--------|<=====================|------' |
| | | response with | |
| v | token echoed back | |
+-----------------+ +------------+
Client Server
Figure 2: Token as Serialization of Request State
Section 3 of this document provides considerations for making clients "stateless" in this way, i.e., for avoiding per-request state in client implementations. (They'll still need to maintain per-server state and other kinds of state, so they're not entirely stateless.)
Serializing state into tokens is complicated by the fact that both CoAP over UDP and CoAP over reliable transports limit the maximum token length to 8 bytes. To overcome this limitation, Section 2 of this document first introduces a CoAP protocol extension for extended token lengths.
While the use case (avoiding per-request state) and the mechanism (extended token lengths) presented in this document are closely related, both can be used independently of each other: Some implementations may be able to fit their state in just 8 bytes; some implementations may have other use cases for extended token lengths.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC8174] when, and only when, they appear in all capitals, as shown here.
This document updates the message formats defined for CoAP over UDP and CoAP over TCP, TLS, and WebSockets with the following new definition of the TKL field, increasing the maximum token length to 65804 bytes.
All other fields retain their definition.
The updated message formats are illustrated in Appendix A.
Extended token lengths require support from the server or, if there are one or more intermediaries between the client and the server, the intermediary in the server role that the client is interacting with.
Support can be discovered by a client (or intermediary in the client role) in one of two ways: In case Capabilities and Settings Messages (CSMs) are available, such as in CoAP over TCP, support can be discovered using the Extended-Token-Lengths Capability Option defined in Section 2.2.1. Otherwise, such as in CoAP over UDP, support can only be discovered by trial and error, as described in Section 2.2.2.
A sender can use the elective Extended-Token-Lengths Capability Option to indicate its support for the new TKL field definition specified in Section 2.1.
| # | C | R | Applies to | Name | Format | Length | Base Value |
|---|---|---|---|---|---|---|---|
| TBD | CSM | Extended-Token-Lengths | empty | 0 | (none) |
C=Critical, R=Repeatable
A request with a TKL field value outside the range from 0 to 8 will be considered a message format error (Section 3 of RFC 7252) and be rejected by a recipient that does not support the updated TKL field definition. A client thus can determine support by sending a request with an extended token length and checking whether it's rejected by the recipient or not.
In CoAP over UDP, a recipient rejects a malformed confirmable message by sending a Reset message (Section 4.2 of RFC 7252). In case of a non-confirmable message, sending a Reset message is permitted but not required (Section 4.3 of RFC 7252). It is therefore RECOMMENDED that clients use a confirmable message for determining support.
As per RFC 7252, Reset messages are empty and don't contain a token; they only return the Message ID (Figure 3). They also don't contain any indication of what caused a message format error. It is therefore RECOMMENDED that clients use a request that contains no potential message format error other than the extended token length.
In CoAP over TCP, TLS, and WebSockets, a recipient rejects a malformed message by sending an Abort message and shutting down the connection (Section 5.6 of RFC 8323).
+-----------------+ request message +------------+
| | | with extended | |
| | | token length | |
| .-<-+->------|--------------------->|------. |
| _|_ | | | |
| / \ stored | | | |
| \___/ state | | | |
| | | | | |
| '->-+-<------|<---------------------|------' |
| | | reset message | |
| v | with only message | |
+-----------------+ ID echoed back +------------+
Client Server
Figure 3: A Confirmable Request With an Extended Token is Rejected With a Reset Message if the Next Hop Does Not Support It
If a server supports extended token lengths but receives a request with a token of a length it is unwilling or unable to process, it MUST NOT reject the message. Instead, it SHOULD return a 4.00 (Bad Request) response. This implies that the server returns the entire token verbatim.
Tokens are a hop-by-hop feature: When an intermediary receives a request, the only requirement is that it echoes the token back in any resulting response. There is no requirement or expectation that an intermediary passes a client's token on to a server or that an intermediary uses extended token lengths itself when receiving a request with an extended token length.
A client can be alleviated of keeping per-request state by serializing the state into a sequence of bytes and sending the bytes as the token of the request. The server will return the token in the response to the client, so that the client can recover the state and process the response as if it had kept the state locally.
The format of the serialized state is an implementation detail of the client and opaque to any server implementation. However, using tokens to serialize state has significant and non-obvious security and privacy implications that need to be mitigated; see Section 4.
Tokens are a hop-by-hop feature: If a client makes a request to an intermediary, that intermediary needs to store the client's token (along with the client's transport address) while it makes its own request to the next hop towards the origin server and waits for the response. When the intermediary receives the response, it looks up the client's token and transport address for the ongoing request and sends an appropriate response to the client.
Such an intermediary might want to be "stateless" as well, i.e., be alleviated of storing the client's token and transport address for ongoing requests. This can be implemented by serializing this information along the request state into the token to the next hop. When the next hop returns the response, the intermediary can recover the information from the token and use it to satisfy the client's request.
The downside of this approach is that an intermediary, without keeping request state, is unable to aggregate multiple requests for the same target resource, which reduces efficiency.
When multiple clients observe the same resource, aggregating requests is REQUIRED (Section 3.1 of RFC 7641). As this cannot be satisfied without keeping request state, an intermediary MUST NOT include an Observe Option in requests it sends without keeping request state.
When using blockwise transfers, a server might not be able to distinguish blocks originating from different clients once they have been forwarded by an intermediary. To ensure that this does not lead to inconsistent resource state, a stateless intermediary MUST include the Request-Tag Option in blockwise transfers with a value that uniquely identifies the next hop towards the client in the intermediary's namespace.
A client (or intermediary in the role of a client) that depends on support for extended token lengths (Section 2) from the next hop to avoid keeping request state MUST perform a discovery of support (Section 2.2) before it can be stateless. This discovery MUST be performed in a stateful way, i.e., keeping state for the request (Figure 4): If the client was stateless from the start and the next hop doesn't support extended tokens, then any error message couldn't be processed since the state would neither be present at the client nor returned in the Reset message (Figure 5).
+-----------------+ dummy request +------------+
| | | with extended | |
| | | token | |
| .-<-+->------|=====================>|------. |
| _|_ | | | |
| / \ stored | | | |
| \___/ state | | | |
| | | | | |
| '->-+-<------|<=====================|------' |
| | | response with | |
| | | extended token | |
| | | echoed back | |
| | | | |
| | | | |
| | | request with | |
| | | serialized state | |
| | | as token | |
| +--------|=====================>|------. |
| | | | |
| look ma, | | | |
| no state! | | | |
| | | | |
| +--------|<=====================|------' |
| | | response with | |
| v | token echoed back | |
+-----------------+ +------------+
Client Server
Figure 4: Depending on Extended Tokens for Being Stateless First Requires a Successful Stateful Discovery of Support
+-----------------+ dummy request +------------+
| | | with extended | |
| | | token | |
| +--------|=====================>|------. |
| | | | |
| | | | |
| | | | |
| | | | |
| ???|<---------------------|------' |
| | reset message | |
| | with only message | |
+-----------------+ ID echoed back +------------+
Client Server
Figure 5: Stateless Discovery of Support Does Not Work
As a further step, in the case of CoAP over UDP, a client (or intermediary in the client role) might want to also avoid keeping message transmission state.
Generally, a client can use confirmable or non-confirmable messages for requests. When using confirmable messages, it needs to keep message exchange state for performing retransmissions and handling Acknowledgement and Reset messages. When using non-confirmable messages, it can keep no message exchange state. However, in either case the client needs to keep congestion control state. That is, it needs to maintain state for each node it communicates with and, e.g., enforce NSTART.
As per RFC 7252, a client must be prepared to receive a response as a piggybacked response, a separate response or non-confirmable response (Section 5.2 of RFC 7252), regardless of the message type used for the request. A stateless client needs to handle these response types as follows:
Tokens significantly larger than the 8 bytes specified in RFC 7252 have implications for nodes in particular with constrained memory size that need to be mitigated.
A node in the server role supporting extended token lengths may be vulnerable to a denial-of-service when an attacker (either on-path or a malicious client) sends large tokens to fill up the memory of the node. Implementations MUST be prepared for this and mitigate it.
Transporting the state needed by a client to process a response as serialized state information in the token has several significant and non-obvious security and privacy implications that need to be mitigated.
Serialized state information is an attractive target for both unwanted nodes (attackers between the node in client role and the next hop) and wanted nodes (the next hop itself) on the path. Therefore, a node in the client role MUST integrity protect the state information, unless processing a response does not modify state or cause other significant side effects.
Even when the serialized state is integrity protected, an attacker may still replay a response, making the client believe it sent the same request twice. Therefore, the node in client role MUST implement replay protection (e.g., by using sequence numbers and a replay window), unless processing a response does not modify state or cause other significant side effects. Integrity protection is REQUIRED for replay protection.
If processing a response without keeping request state is sensitive to the time elapsed to sending the request, then the serialized state MUST include freshness information (e.g., a timestamp).
Information in the serialized state may be privacy sensitive. A node in client role MUST encrypt the serialized state if it contains privacy sensitive information that an attacker would not get otherwise. For example, an intermediary that serializes the client's token and transport address into its token leaks that information to the next hop, which may be undesirable. In wireless mesh networks, where all traffic is visible to a passive attacker, encryption may not be needed as the attacker can get the same information from analyzing the traffic flows.
The use of encryption, integrity protection, and replay protection of serialized state is recommended in general, unless a careful analysis of any potential attacks to security and privacy is performed. AES-CCM with a 64 bit tag is recommended, combined with a sequence number and a replay window. Where encryption is not needed, HMAC-SHA-256, combined with a sequence number and a replay window, may be used.
The following entries are added to the "CoAP Signaling Option Numbers" registry within the "CoRE Parameters" registry.
| Applies to | Number | Name | Reference |
|---|---|---|---|
| 7.01 | TBD | Extended-Token-Lengths | [[this document]] |
| [I-D.ietf-6tisch-minimal-security] | Vucinic, M., Simon, J., Pister, K. and M. Richardson, "Minimal Security Framework for 6TiSCH", Internet-Draft draft-ietf-6tisch-minimal-security-09, November 2018. |
| [RFC7228] | Bormann, C., Ersue, M. and A. Keranen, "Terminology for Constrained-Node Networks", RFC 7228, DOI 10.17487/RFC7228, May 2014. |
This appendix illustrates the CoAP message formats updated with the new definition of the TKL field (Section 2).
0 1 2 3 4 5 6 7
+-------+-------+---------------+
| | | |
| Ver | T | TKL | 1 byte
| | | |
+-------+-------+---------------+
| |
| Code | 1 byte
| |
+-------------------------------+
| |
| |
| |
+- Message ID -+ 2 bytes
| |
| |
| |
+-------------------------------+
\ \
/ TKL / 0-2 bytes
\ (extended) \
+-------------------------------+
\ \
/ Token / 0 or more bytes
\ \
+-------------------------------+
\ \
/ /
\ \
/ Options / 0 or more bytes
\ \
/ /
\ \
+---------------+---------------+
| | |
| 15 | 15 | 1 byte (if payload)
| | |
+---------------+---------------+
\ \
/ /
\ \
/ Payload / 0 or more bytes
\ \
/ /
\ \
+-------------------------------+
0 1 2 3 4 5 6 7
+---------------+---------------+
| | |
| Len | TKL | 1 byte
| | |
+---------------+---------------+
\ \
/ Len / 0-2 bytes
\ (extended) \
+-------------------------------+
| |
| Code | 1 byte
| |
+-------------------------------+
\ \
/ TKL / 0-2 bytes
\ (extended) \
+-------------------------------+
\ \
/ Token / 0 or more bytes
\ \
+-------------------------------+
\ \
/ /
\ \
/ Options / 0 or more bytes
\ \
/ /
\ \
+---------------+---------------+
| | |
| 15 | 15 | 1 byte (if payload)
| | |
+---------------+---------------+
\ \
/ /
\ \
/ Payload / 0 or more bytes
\ \
/ /
\ \
+-------------------------------+
0 1 2 3 4 5 6 7
+---------------+---------------+
| | |
| 0 | TKL | 1 byte
| | |
+---------------+---------------+
| |
| Code | 1 byte
| |
+-------------------------------+
\ \
/ TKL / 0-2 bytes
\ (extended) \
+-------------------------------+
\ \
/ Token / 0 or more bytes
\ \
+-------------------------------+
\ \
/ /
\ \
/ Options / 0 or more bytes
\ \
/ /
\ \
+---------------+---------------+
| | |
| 15 | 15 | 1 byte (if payload)
| | |
+---------------+---------------+
\ \
/ /
\ \
/ Payload / 0 or more bytes
\ \
/ /
\ \
+-------------------------------+
This document is based on the requirements of and work on the Minimal Security Framework for 6TiSCH by Malisa Vucinic, Jonathan Simon, Kris Pister, and Michael Richardson.
Thanks to Carsten Bormann, Ari Keranen, John Mattsson, Jim Schaad, Goeran Selander, and Malisa Vucinic for helpful comments and discussions that have shaped the document.