diff options
Diffstat (limited to 'doc/rfc/rfc8974.txt')
| -rw-r--r-- | doc/rfc/rfc8974.txt | 974 |
1 files changed, 974 insertions, 0 deletions
diff --git a/doc/rfc/rfc8974.txt b/doc/rfc/rfc8974.txt new file mode 100644 index 0000000..50a77be --- /dev/null +++ b/doc/rfc/rfc8974.txt @@ -0,0 +1,974 @@ + + + + +Internet Engineering Task Force (IETF) K. Hartke +Request for Comments: 8974 Ericsson +Updates: 7252, 8323 M. Richardson +Category: Standards Track Sandelman +ISSN: 2070-1721 January 2021 + + + Extended Tokens and Stateless Clients + in the Constrained Application Protocol (CoAP) + +Abstract + + This document provides considerations for alleviating Constrained + Application Protocol (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 with an extended definition + of the "TKL" field in the CoAP message header. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8974. + +Copyright Notice + + Copyright (c) 2021 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. + +Table of Contents + + 1. Introduction + 1.1. Terminology + 2. Extended Tokens + 2.1. Extended Token Length (TKL) Field + 2.2. Discovering Support + 2.2.1. Extended-Token-Length Capability Option + 2.2.2. Trial and Error + 2.3. Intermediaries + 3. Stateless Clients + 3.1. Serializing Client State + 3.2. Using Extended Tokens + 3.3. Transmitting Messages + 4. Stateless Intermediaries + 4.1. Observing Resources + 4.2. Block-Wise Transfers + 4.3. Gateway Timeouts + 4.4. Extended Tokens + 5. Security Considerations + 5.1. Extended Tokens + 5.2. Stateless Clients and Intermediaries + 6. IANA Considerations + 6.1. CoAP Signaling Option Number + 7. References + 7.1. Normative References + 7.2. Informative References + Appendix A. Updated Message Formats + A.1. CoAP over UDP + A.2. CoAP over TCP/TLS + A.3. CoAP over WebSockets + Acknowledgements + Authors' Addresses + +1. Introduction + + The Constrained Application Protocol (CoAP) [RFC7252] is a RESTful + application-layer protocol for constrained environments [RFC7228]. + In CoAP, clients (or intermediaries in the client role) make requests + to servers (or intermediaries in the server role), which satisfy 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 that arrives. + Identification of this state is done in CoAP by means of a token: an + opaque sequence of bytes that is chosen by the client and included in + the CoAP request and that is returned by the server 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. + A client can opt into this by serializing (parts of) its state into + the token itself and then recovering this 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 clients + becoming "stateless" in this way. (The term "stateless" is in quotes + here, because it's a bit oversimplified. Such clients still need to + maintain per-server state and other kinds of state. So it would be + more accurate to just say that the clients are avoiding per-request + state.) + + Section 4 of this document extends the considerations for clients to + intermediaries, which may want to avoid keeping state for not only + the requests they send to servers but also the requests they receive + from clients. + + The serialization of state into tokens is limited by the fact that + both CoAP over UDP [RFC7252] and CoAP over reliable transports + [RFC8323] restrict the maximum token length to 8 bytes. To overcome + this limitation, Section 2 of this document 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, each can be used independently of the 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. + +1.1. Terminology + + In this document, the term "stateless" refers to an implementation + strategy for a client (or intermediary in the client role) that does + not require it to keep state for the individual requests it sends to + a server (or intermediary in the server role). The client still + needs to keep state for each server it communicates with (e.g., for + token generation, message retransmission, and congestion control). + + 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 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +2. Extended Tokens + + This document updates the message formats defined for CoAP over UDP + [RFC7252] and CoAP over TCP, TLS, and WebSockets [RFC8323] with a new + definition of the "TKL" field. + +2.1. Extended Token Length (TKL) Field + + The definition of the "TKL" field is updated as follows: + + Token Length (TKL): 4-bit unsigned integer. A value between 0 and + 12, inclusive, indicates the length of the variable-length "Token" + field in bytes. The other three values are reserved for special + constructs: + + 13: An 8-bit unsigned integer directly precedes the "Token" + field and indicates the length of the "Token" field minus + 13. + + 14: A 16-bit unsigned integer in network byte order directly + precedes the "Token" field and indicates the length of the + "Token" field minus 269. + + 15: Reserved. This value MUST NOT be sent and MUST be processed + as a message-format error. + + All other fields retain their definitions. + + The updated message formats are illustrated in Appendix A. + + The new definition of the "TKL" field increases the maximum token + length that can be represented in a message to 65804 bytes. However, + the maximum token length that sender and recipient implementations + support may be shorter. For example, a constrained node of Class 1 + [RFC7228] might support extended token lengths only up to 32 bytes. + + In CoAP over UDP, it is often beneficial to keep CoAP messages small + enough to avoid IP fragmentation. The maximum practical token length + may therefore also be influenced by the Path MTU (PMTU). See + Section 4.6 of [RFC7252] for details. + +2.2. Discovering Support + + Extended token lengths require support from server implementations. + Support can be discovered by a client implementation in one of two + ways: + + * Where Capabilities and Settings Messages (CSMs) are available, + such as in CoAP over TCP, support can be discovered using the + Extended-Token-Length 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. + +2.2.1. Extended-Token-Length Capability Option + + A server can use the elective Extended-Token-Length Capability Option + to indicate the maximum token length it can accept in requests. + + +=+=+===+=========+=======================+========+========+=======+ + |#|C| R | Applies | Name | Format | Length | Base | + | | | | to | | | | Value | + +=+=+===+=========+=======================+========+========+=======+ + |6| | | CSM | Extended-Token-Length | uint | 0-3 | 8 | + +-+-+---+---------+-----------------------+--------+--------+-------+ + + Table 1: The Extended-Token-Length Capability Option + + C=Critical, R=Repeatable + + As per Section 3 of [RFC7252], the base value (and the value used + when this option is not implemented) is 8. + + The active value of the Extended-Token-Length Option is replaced each + time the option is sent with a modified value. Its starting value is + its base value. + + The option value MUST NOT be less than 8 or greater than 65804. If + an option value less than 8 is received, the option MUST be ignored. + If an option value greater than 65804 is received, the option value + MUST be set to 65804. + + Any option value greater than 8 implies support for the new + definition of the "TKL" field specified in Section 2.1. Indication + of support by a server does not oblige a client to actually make use + of token lengths greater than 8. + + If a server receives a request with a token of a length greater than + what it indicated in its Extended-Token-Length Option, it MUST handle + the request as a message-format error. + + If a server receives a request with a token of a length less than, or + equal to, what it indicated in its Extended-Token-Length Option but + is unwilling or unable to handle the token at that time, it MUST NOT + handle the request as a message-format error. Instead, it SHOULD + return a 5.03 (Service Unavailable) response. + + The Extended-Token-Length Capability Option does not apply to + responses. The sender of a request is simply expected not to use a + token of a length greater than it is willing to accept in a response. + +2.2.2. Trial and Error + + A server implementation that does not support the updated definition + of the "TKL" field specified in Section 2.1 will consider a request + with a "TKL" field value outside the range 0 to 8 to be a message- + format error and reject it (Section 3 of [RFC7252]). A client can + therefore determine support by sending a request with an extended + token length and checking whether or not it is rejected by the + server. + + In CoAP over UDP, the way a request message is rejected depends on + the message type. A Confirmable message with a message-format error + is rejected with a Reset message (Section 4.2 of [RFC7252]). A Non- + confirmable message with a message-format error is either rejected + with a Reset message or just silently ignored (Section 4.3 of + [RFC7252]). To reliably get a Reset message, it is therefore + REQUIRED that clients use a Confirmable message for determining + support. + + As per RFC 7252, Reset messages are empty and do not contain a token; + they only return the Message ID (Figure 3). They also do not contain + any indication of what caused a message-format error. To avoid any + ambiguity, it is therefore RECOMMENDED that clients use a request + that has no potential message-format error other than the extended + token length. + + +-----------------+ 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 Server Does Not Have Support + + An example of a suitable request is a GET request in a Confirmable + message that includes only an If-None-Match option and a token of the + greatest length that the client intends to use. Any response with + the same token echoed back indicates that tokens up to that length + are supported by the server. + + Since network addresses may change, a client SHOULD NOT assume that + extended token lengths are supported by a server for an unlimited + duration. Unless additional information is available, the client + should assume that addresses (and therefore extended token lengths) + are valid for a minimum of 1800 s and a maximum of 86400 s (1 day). + A client may use additional forms of input into this determination. + For instance, a client may assume a server that is in the same subnet + as the client has a similar address lifetime as the client. The + client may use DHCP lease times or Router Advertisements to set the + limits. For servers that are not local, if the server was looked up + using DNS, then the DNS resource record will have a Time To Live + (TTL), and the extended token length should be kept for only that + amount of time. + + If a server supports extended token lengths but receives a request + with a token of a length it is unwilling or unable to handle, it MUST + NOT reject the message, as that would imply that extended token + lengths are not supported at all. Instead, if the server cannot + handle the request at the time, it SHOULD return a 5.03 (Service + Unavailable) response; if the server will never be able to handle the + request (e.g., because the token is too large), it SHOULD return a + 4.00 (Bad Request) response. + + | Design Note: The requirement to return an error response when a + | token cannot be handled might seem somewhat contradictory, as + | returning the error response requires the server also to return + | the token it cannot handle. However, processing a request + | usually involves a number of steps from receiving the message + | to passing it to application logic. The idea is that a server + | implementing this extension supports large tokens at least in + | its first few processing steps, enough to return an error + | response rather than a Reset message. + + | Design Note: To prevent the trial-and-error-based discovery + | from becoming too complicated, no effort is made to indicate + | the maximum supported token length. A client implementation + | would probably already choose the shortest token possible for + | the task (such as being stateless, as described in Section 3), + | so it would probably not be able to reduce the length any + | further anyway should a server indicate a lower limit. + +2.3. Intermediaries + + Tokens are a hop-by-hop feature: if there are one or more + intermediaries between a client and a server, every token is scoped + to the exchange between a node in the client role and the node in the + server role that it is immediately interacting with. + + 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 in its request to satisfy a request with an extended + token length. Discovery needs to be performed for each hop where + extended token lengths are to be used. + +3. Stateless Clients + + A client can be alleviated of keeping per-request state as follows: + + 1. The client serializes (parts of) its per-request state into a + sequence of bytes and sends those bytes as the token of its + request to the server. + + 2. The server returns the token verbatim in the response to the + client, which allows the client to recover the state and process + the response as if it had kept the state locally. + + As servers are just expected to return any token verbatim to the + client, this implementation strategy for clients does not impact the + interoperability of client and server implementations. However, + there are a number of significant, nonobvious implications (e.g., + related to security and other CoAP protocol features) that client + implementations need take into consideration. + + The following subsections discuss some of these considerations. + +3.1. Serializing Client State + + The format of the serialized state is generally an implementation + detail of the client and opaque to the server. However, serialized + state information is an attractive target for both unwanted nodes + (e.g., on-path attackers) and wanted nodes (e.g., any configured + forward proxy) on the path. The serialization format therefore needs + to include security measures such as the following: + + * A client SHOULD protect the integrity of the state information + serialized in a token. + + * Even when the integrity of the serialized state is protected, an + attacker may still replay a response, making the client believe it + sent the same request twice. For this reason, the client SHOULD + implement replay protection (e.g., by using sequence numbers and a + replay window). For replay protection, integrity protection is + REQUIRED. + + * If processing a response without keeping request state is + sensitive to the time elapsed since sending the request, then the + client SHOULD include freshness information (e.g., a timestamp) in + the serialized state and reject any response where the freshness + information is insufficiently fresh. + + * Information in the serialized state may be privacy sensitive. A + client SHOULD encrypt the serialized state if it contains privacy- + sensitive information that an attacker would not get otherwise. + + * When a client changes the format of the serialized state, it + SHOULD prevent false interoperability with the previous format + (e.g., by changing the key used for integrity protection or + changing a field in the serialized state). + +3.2. Using Extended Tokens + + A client that depends on support for extended token lengths + (Section 2) from the server to avoid keeping request state needs to + 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 server does not support extended tokens, then no + error message could 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 + + In environments where support can be reliably discovered through some + other means, the discovery of support is OPTIONAL. An example for + this is the Constrained Join Protocol (CoJP) in a 6TiSCH network + [6TISCH-MIN-SEC], where support for extended tokens is required from + all relevant parties. + +3.3. Transmitting Messages + + In CoAP over UDP [RFC7252], a client has the choice between + Confirmable and Non-confirmable messages for requests. When using + Non-confirmable messages, a client does not have to keep any message- + exchange state, which can help in the goal of avoiding state. When + using Confirmable messages, a client needs to keep message-exchange + state for performing retransmissions and handling Acknowledgement and + Reset messages, however. Non-confirmable messages are therefore + better suited for avoiding state. In any case, a client still needs + to keep congestion-control state, i.e., maintain state for each node + it communicates with and enforce limits like NSTART. + + As per Section 5.2 of [RFC7252], a client must be prepared to receive + a response as a piggybacked response, a separate response, or a Non- + confirmable response, regardless of the message type used for the + request. A stateless client MUST handle these response types as + follows: + + * If a piggybacked response passes the checks for token integrity + and freshness (Section 3.1), the client processes the message as + specified in RFC 7252; otherwise, it processes the acknowledgement + portion of the message as specified in RFC 7252 and silently + discards the response portion. + + * If a separate response passes the checks for token integrity and + freshness, the client processes the message as specified in RFC + 7252; otherwise, it rejects the message as specified in + Section 4.2 of [RFC7252]. + + * If a Non-confirmable response passes the checks for token + integrity and freshness, the client processes the message as + specified in RFC 7252; otherwise, it rejects the message as + specified in Section 4.3 of [RFC7252]. + +4. Stateless Intermediaries + + 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 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 received request and sends an + appropriate response to the client. + + An intermediary might want to be "stateless" not only in its role as + a client but also in its role as a server, i.e., be alleviated of + storing the client information for the requests it receives. + + Such an intermediary can be implemented by serializing the client + information along with the request state into the token towards the + origin server. When the intermediary receives the response, it can + recover the client information from the token and use it to satisfy + the client's request; therefore, the intermediary doesn't need to + store the information itself. + + The following subsections discuss some considerations for this + approach. + +4.1. Observing Resources + + One drawback of the approach is that an intermediary, without keeping + request state, is unable to aggregate multiple requests for the same + target resource, which can significantly reduce efficiency. In + particular, when clients observe [RFC7641] the same resource, + aggregating requests is REQUIRED (Section 3.1 of [RFC7641]). This + requirement cannot be satisfied without keeping request state. + + Furthermore, an intermediary that does not keep track of the clients + observing a resource is not able to determine whether these clients + are still interested in receiving further notifications (Section 3.5 + of [RFC7641]) or want to cancel an observation (Section 3.6 of + [RFC7641]). + + Therefore, an intermediary MUST NOT include an Observe Option in + requests it sends without keeping both the request state for the + requests it sends and the client information for the requests it + receives. + +4.2. Block-Wise Transfers + + When using block-wise transfers [RFC7959], a server might not be able + to distinguish blocks originating from different clients once they + have been forwarded by an intermediary. Intermediaries need to + ensure that this does not lead to inconsistent resource state by + keeping distinct block-wise request operations on the same resource + apart, e.g., utilizing the Request-Tag Option [ECHO-REQUEST-TAG]. + +4.3. Gateway Timeouts + + As per Section 5.7.1 of [RFC7252], an intermediary is REQUIRED to + return a 5.04 (Gateway Timeout) response if it cannot obtain a + response within a timeout. However, if an intermediary does not keep + the client information for the requests it receives, it cannot return + such a response. Therefore, in this case, the gateway cannot return + such a response and as such cannot implement such a timeout. + +4.4. Extended Tokens + + A client may make use of extended token lengths in a request to an + intermediary that wants to be "stateless". This means that such an + intermediary may have to serialize potentially very large client + information into its token towards the origin server. The tokens can + grow even further when it progresses along a chain of intermediaries + that all want to be "stateless". + + Intermediaries SHOULD limit the size of client information they are + serializing into their own tokens. An intermediary can do this, for + example, by limiting the extended token lengths it accepts from its + clients (see Section 2.2) or by keeping the client information + locally when the client information exceeds the limit (i.e., not + being "stateless"). + +5. Security Considerations + +5.1. Extended Tokens + + Tokens significantly larger than the 8 bytes specified in RFC 7252 + have implications -- in particular, for nodes 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 need + to be prepared to handle such messages. + +5.2. Stateless Clients and Intermediaries + + Transporting the state needed by a client to process a response as + serialized state information in the token has several significant and + nonobvious security and privacy implications that need to be + mitigated; see Section 3.1 for recommendations. + + In addition to the format requirements outlined there, + implementations need to ensure that they are not vulnerable to + maliciously crafted, delayed, or replayed tokens. + + It is generally expected that the use of encryption, integrity + protection, and replay protection for serialized state is + appropriate. + + In the absence of integrity and replay protection, an on-path + attacker or rogue server/intermediary could return a state (either + one modified in a reply, or an unsolicited one) that could alter the + internal state of the client. + + It is for this reason that at least the use of integrity protection + on the token is always recommended. + + It may be that in some very specific cases, as a result of a careful + and detailed analysis of any potential attacks, it is decided that + such cryptographic protections do not add value. The authors of this + document have not found such a use case as yet, but this is a local + decision. + + It should further be emphasized that the encrypted state is created + by the sending node and decrypted by the same node when receiving a + response. The key is not shared with any other system. Therefore, + the choice of encryption scheme and the generation of the key for + this system is purely a local matter. + + When encryption is used, the use of AES-CCM [RFC3610] with a 64-bit + tag is recommended, combined with a sequence number and a replay + window. This choice is informed by available hardware acceleration + of on many constrained systems. If a different algorithm is + available accelerated on the sender, with similar or stronger + strength, then it SHOULD be preferred. Where privacy of the state is + not required, and encryption is not needed, HMAC-SHA-256 [RFC6234], + combined with a sequence number and a replay window, may be used. + + This size of the replay window depends upon the number of requests + that need to be outstanding. This can be determined from the rate at + which new ones are made and the expected time period during which + responses are expected. + + For instance, given a CoAP MAX_TRANSMIT_WAIT of 93 s (Section 4.8.2 + of [RFC7252]), any request that is not answered within 93 s will be + considered to have failed. At a request rate of one request per 10 + s, at most 10 (ceil(9.3)) requests can be outstanding at a time, and + any convenient replay window larger than 20 will work. As replay + windows are often implemented with a sliding window and a bit, the + use of a 32-bit window would be sufficient. + + For use cases where requests are being relayed from another node, the + request rate may be estimated by the total link capacity allocated + for that kind of traffic. An alternate view would consider how many + IPv6 Neighbor Cache Entries (NCEs) the system can afford to allocate + for this use. + + When using an encryption mode that depends on a nonce, such as AES- + CCM, repeated use of the same nonce under the same key causes the + cipher to fail catastrophically. + + If a nonce is ever used for more than one encryption operation with + the same key, then the same key stream gets used to encrypt both + plaintexts, and the confidentiality guarantees are voided. Devices + with low-quality entropy sources -- as is typical with constrained + devices, which incidentally happen to be a natural candidate for the + stateless mechanism described in this document -- need to carefully + pick a nonce-generation mechanism that provides the above uniqueness + guarantee. + + [RFC8613], Appendix B.1.1 ("Sender Sequence Number") provides a model + for how to maintain nonrepeating nonces without causing excessive + wear of flash memory. + +6. IANA Considerations + +6.1. CoAP Signaling Option Number + + The following entry has been added to the "CoAP Signaling Option + Numbers" registry within the "CoRE Parameters" registry. + + +============+========+=======================+===========+ + | Applies to | Number | Name | Reference | + +============+========+=======================+===========+ + | 7.01 | 6 | Extended-Token-Length | RFC 8974 | + +------------+--------+-----------------------+-----------+ + + Table 2: CoAP Signaling Option Number + + +7. References + +7.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained + Application Protocol (CoAP)", RFC 7252, + DOI 10.17487/RFC7252, June 2014, + <https://www.rfc-editor.org/info/rfc7252>. + + [RFC7641] Hartke, K., "Observing Resources in the Constrained + Application Protocol (CoAP)", RFC 7641, + DOI 10.17487/RFC7641, September 2015, + <https://www.rfc-editor.org/info/rfc7641>. + + [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in + the Constrained Application Protocol (CoAP)", RFC 7959, + DOI 10.17487/RFC7959, August 2016, + <https://www.rfc-editor.org/info/rfc7959>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + + [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., + Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained + Application Protocol) over TCP, TLS, and WebSockets", + RFC 8323, DOI 10.17487/RFC8323, February 2018, + <https://www.rfc-editor.org/info/rfc8323>. + +7.2. Informative References + + [6TISCH-MIN-SEC] + Vucinic, M., Simon, J., Pister, K., and M. Richardson, + "Constrained Join Protocol (CoJP) for 6TiSCH", Work in + Progress, Internet-Draft, draft-ietf-6tisch-minimal- + security-15, 10 December 2019, + <https://tools.ietf.org/html/draft-ietf-6tisch-minimal- + security-15>. + + [ECHO-REQUEST-TAG] + Amsüss, C., Mattsson, J. P., and G. Selander, "CoAP: Echo, + Request-Tag, and Token Processing", Work in Progress, + Internet-Draft, draft-ietf-core-echo-request-tag-11, 2 + November 2020, <https://tools.ietf.org/html/draft-ietf- + core-echo-request-tag-11>. + + [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with + CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September + 2003, <https://www.rfc-editor.org/info/rfc3610>. + + [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms + (SHA and SHA-based HMAC and HKDF)", RFC 6234, + DOI 10.17487/RFC6234, May 2011, + <https://www.rfc-editor.org/info/rfc6234>. + + [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for + Constrained-Node Networks", RFC 7228, + DOI 10.17487/RFC7228, May 2014, + <https://www.rfc-editor.org/info/rfc7228>. + + [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, + "Object Security for Constrained RESTful Environments + (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, + <https://www.rfc-editor.org/info/rfc8613>. + +Appendix A. Updated Message Formats + + In Section 2, this document updates the CoAP message formats by + specifying a new definition of the "TKL" field in the message header. + As an alternative presentation of this update, this appendix shows + the CoAP message formats for CoAP over UDP [RFC7252] and CoAP over + TCP, TLS, and WebSockets [RFC8323] with the new definition applied. + +A.1. CoAP over UDP + + 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-65804 bytes + \ \ + +-------------------------------+ + \ \ + / / + \ \ + / Options / 0 or more bytes + \ \ + / / + \ \ + +---------------+---------------+ + | | | + | 15 | 15 | 1 byte (if payload) + | | | + +---------------+---------------+ + \ \ + / / + \ \ + / Payload / 0 or more bytes + \ \ + / / + \ \ + +-------------------------------+ + +A.2. CoAP over TCP/TLS + + 0 1 2 3 4 5 6 7 + +---------------+---------------+ + | | | + | Len | TKL | 1 byte + | | | + +---------------+---------------+ + \ \ + / Len / 0-4 bytes + \ (extended) \ + +-------------------------------+ + | | + | Code | 1 byte + | | + +-------------------------------+ + \ \ + / TKL / 0-2 bytes + \ (extended) \ + +-------------------------------+ + \ \ + / Token / 0-65804 bytes + \ \ + +-------------------------------+ + \ \ + / / + \ \ + / Options / 0 or more bytes + \ \ + / / + \ \ + +---------------+---------------+ + | | | + | 15 | 15 | 1 byte (if payload) + | | | + +---------------+---------------+ + \ \ + / / + \ \ + / Payload / 0 or more bytes + \ \ + / / + \ \ + +-------------------------------+ + +A.3. CoAP over WebSockets + + 0 1 2 3 4 5 6 7 + +---------------+---------------+ + | | | + | 0 | TKL | 1 byte + | | | + +---------------+---------------+ + | | + | Code | 1 byte + | | + +-------------------------------+ + \ \ + / TKL / 0-2 bytes + \ (extended) \ + +-------------------------------+ + \ \ + / Token / 0-65804 bytes + \ \ + +-------------------------------+ + \ \ + / / + \ \ + / Options / 0 or more bytes + \ \ + / / + \ \ + +---------------+---------------+ + | | | + | 15 | 15 | 1 byte (if payload) + | | | + +---------------+---------------+ + \ \ + / / + \ \ + / Payload / 0 or more bytes + \ \ + / / + \ \ + +-------------------------------+ + +Acknowledgements + + This document is based on the requirements of, and work on, + "Constrained Join Protocol (CoJP) for 6TiSCH" (January 2020) by + Mališa Vučinić, Jonathan Simon, Kris Pister, and Michael Richardson. + + Thanks to Christian Amsüss, Carsten Bormann, Roman Danyliw, Christer + Holmberg, Benjamin Kaduk, Ari Keränen, Erik Kline, Murray Kucherawy, + Warren Kumari, Barry Leiba, David Mandelberg, Dan Romascanu, Jim + Schaad, Göran Selander, Mališa Vučinić, Éric Vyncke, and Robert + Wilton for helpful comments and discussions that have shaped the + document. + + Special thanks to John Mattsson for his contributions to the security + considerations of the document, and to Thomas Fossati for his in- + depth review, copious comments, and suggested text. + +Authors' Addresses + + Klaus Hartke + Ericsson + Torshamnsgatan 23 + SE-16483 Stockholm + Sweden + + Email: klaus.hartke@ericsson.com + + + Michael C. Richardson + Sandelman Software Works + + Email: mcr+ietf@sandelman.ca + URI: http://www.sandelman.ca/ |