rfc8974xml2.original.xml   rfc8974.xml 
<?xml version="1.0" encoding="us-ascii"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.2
119.xml">
<!ENTITY RFC3610 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.3
610.xml">
<!ENTITY RFC4107 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.4
107.xml">
<!ENTITY RFC6234 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.6
234.xml">
<!ENTITY RFC7228 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.7
228.xml">
<!ENTITY RFC7252 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.7
252.xml">
<!ENTITY RFC7641 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.7
641.xml">
<!ENTITY RFC7959 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.7
959.xml">
<!ENTITY RFC8174 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.8
174.xml">
<!ENTITY RFC8323 SYSTEM "http://www.rfc-editor.org/refs/bibxml/reference.RFC.8
323.xml">
<!ENTITY I-D.ietf-6tisch-minimal-security SYSTEM "http://www.rfc-editor.org/re
fs/bibxml3/reference.I-D.ietf-6tisch-minimal-security.xml">
<!ENTITY I-D.ietf-core-echo-request-tag SYSTEM "http://www.rfc-editor.org/refs
/bibxml3/reference.I-D.ietf-core-echo-request-tag.xml">
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<?rfc compact="yes"?> <!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
<?rfc sortrefs="yes"?>
<?rfc subcompact="no"?>
<?rfc symrefs="yes"?>
<?rfc toc="yes"?>
<?rfc tocdepth="3"?>
<rfc category="std" docName="draft-ietf-core-stateless-08" ipr="trust200902" upd <rfc xmlns:xi="http://www.w3.org/2001/XInclude" docName="draft-ietf-core-statele
ates="7252, 8323"> ss-08" number="8974" ipr="trust200902" updates="7252, 8323" obsoletes="" submis
sionType="IETF"
category="std" consensus="true" xml:lang="en" sortRefs="true" symRefs="true" toc
Include="true" tocDepth="3" version="3">
<!-- xml2rfc v2v3 conversion 3.5.0 -->
<front> <front>
<title abbrev="Extended Tokens in CoAP"> <title abbrev="Extended Tokens in CoAP">
Extended&#160;Tokens&#160;and&#160;Stateless&#160;Clients Extended&nbsp;Tokens&nbsp;and&nbsp;Stateless&nbsp;Clients
in&#160;the&#160;Constrained&#160;Application&#160;Protocol&#160;(CoAP) in&nbsp;the&nbsp;Constrained&nbsp;Application&nbsp;Protocol&nbsp;(CoAP)
</title> </title>
<seriesInfo name="RFC" value="8974"/>
<author initials="K." surname="Hartke" fullname="Klaus Hartke"> <author initials="K." surname="Hartke" fullname="Klaus Hartke">
<organization>Ericsson</organization> <organization>Ericsson</organization>
<address> <address>
<postal> <postal>
<street>Torshamnsgatan 23</street> <street>Torshamnsgatan 23</street>
<city>Stockholm</city> <city>Stockholm</city>
<code>SE-16483</code> <code>16483</code>
<country>Sweden</country> <country>Sweden</country>
</postal> </postal>
<email>klaus.hartke@ericsson.com</email> <email>klaus.hartke@ericsson.com</email>
</address> </address>
</author> </author>
<author fullname="Michael C. Richardson" initials="M." surname="Richardson">
<author fullname="Michael C. Richardson" initials="M."
surname="Richardson">
<organization abbrev="Sandelman">Sandelman Software Works</organization> <organization abbrev="Sandelman">Sandelman Software Works</organization>
<address> <address>
<email>mcr+ietf@sandelman.ca</email> <email>mcr+ietf@sandelman.ca</email>
<uri>http://www.sandelman.ca/</uri> <uri>http://www.sandelman.ca/</uri>
</address> </address>
</author> </author>
<date year="2021" month="January" />
<date/>
<workgroup>CoRE Working Group</workgroup> <workgroup>CoRE Working Group</workgroup>
<abstract> <abstract>
<t> <t>
This document provides considerations for alleviating CoAP clients and This document provides considerations for alleviating Constrained Applic ation Protocol (CoAP) clients and
intermediaries of keeping per-request state. To facilitate this, this intermediaries of keeping per-request state. To facilitate this, this
document additionally introduces a new, optional CoAP protocol extension document additionally introduces a new, optional CoAP protocol extension
for extended token lengths. for extended token lengths.
</t> </t>
<t> <t>
This document updates RFCs 7252 and 8323 with an extended definition of the This document updates RFCs 7252 and 8323 with an extended definition of the
TKL field in the CoAP message header. "TKL" field in the CoAP message header.
</t> </t>
</abstract> </abstract>
</front> </front>
<middle> <middle>
<!-- **************************************************************** --> <section anchor="introduction" numbered="true" toc="default">
<!-- **************************************************************** --> <name>Introduction</name>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Introduction" anchor="introduction">
<t> <t>
The Constrained Application Protocol (CoAP) <xref target="RFC7252"/> is The Constrained Application Protocol (CoAP) <xref target="RFC7252" forma
a RESTful application-layer protocol for <xref t="default"/> is
target="RFC7228">constrained environments</xref>. In CoAP, clients (or a RESTful application-layer protocol for <xref target="RFC7228" format="
default">constrained environments</xref>. In CoAP, clients (or
intermediaries in the client role) make requests to servers (or intermediaries in the client role) make requests to servers (or
intermediaries in the server role), which satisfy the requests by intermediaries in the server role), which satisfy the requests by
returning responses. returning responses.
</t> </t>
<t> <t>
While a request is ongoing, a client typically needs to keep some state that While a request is ongoing, a client typically needs to keep some state that
it requires for processing the response when that arrives. Identificatio n it requires for processing the response when that arrives. Identificatio n
of this state is done in CoAP by means of a token, an of this state is done in CoAP by means of a token: an
opaque sequence of bytes chosen by the client and included in the CoAP opaque sequence of bytes that is chosen by the client and included in th
request, and that is returned by the server verbatim in any resulting Co e CoAP
AP request and that is returned by the server verbatim in any resulting CoA
response (<xref target="stateful-exchange"/>). P
response (<xref target="stateful-exchange" format="default"/>).
</t> </t>
<figure anchor="stateful-exchange">
<figure anchor="stateful-exchange" title="Token as an Identifier for Request Sta <name>Token as an Identifier for Request State</name>
te"><artwork align="center"><![CDATA[ <artwork align="center" name="" type="" alt=""><![CDATA[
+-----------------+ request with +------------+ +-----------------+ request with +------------+
| | | state identifier | | | | | state identifier | |
| | | as token | | | | | as token | |
| .-<-+->------|--------------------->|------. | | .-<-+->------|--------------------->|------. |
| _|_ | | | | | _|_ | | | |
| / \ stored | | | | | / \ stored | | | |
| \___/ state | | | | | \___/ state | | | |
| | | | | | | | | | | |
| '->-+-<------|<---------------------|------' | | '->-+-<------|<---------------------|------' |
| | | response with | | | | | response with | |
| v | token echoed back | | | v | token echoed back | |
+-----------------+ +------------+ +-----------------+ +------------+
Client Server Client Server
]]></artwork></figure> ]]></artwork>
</figure>
<t> <t>
In some scenarios, it can be beneficial to reduce the amount of 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 c lient can that is stored at the client at the cost of increased message sizes. A c lient can
opt into this by serializing (parts of) its state into the token itself and then opt into this by serializing (parts of) its state into the token itself and then
recovering this state from the token in the response (<xref recovering this state from the token in the response (<xref target="stat
target="stateless-exchange"/>). eless-exchange" format="default"/>).
</t> </t>
<figure anchor="stateless-exchange">
<figure anchor="stateless-exchange" title="Token as Serialization of Request Sta <name>Token as Serialization of Request State</name>
te"><artwork align="center"><![CDATA[ <artwork align="center" name="" type="" alt=""><![CDATA[
+-----------------+ request with +------------+ +-----------------+ request with +------------+
| | | serialized state | | | | | serialized state | |
| | | as token | | | | | as token | |
| +--------|=====================>|------. | | +--------|=====================>|------. |
| | | | | | | | | |
| look ma, | | | | | look ma, | | | |
| no state! | | | | | no state! | | | |
| | | | | | | | | |
| +--------|<=====================|------' | | +--------|<=====================|------' |
| | | response with | | | | | response with | |
| v | token echoed back | | | v | token echoed back | |
+-----------------+ +------------+ +-----------------+ +------------+
Client Server Client Server
]]></artwork></figure> ]]></artwork>
</figure>
<t> <t>
<xref target="stateless-clients"/> of this document provides <xref target="stateless-clients" format="default"/> of this document pro vides
considerations for clients becoming "stateless" in this way. considerations for clients becoming "stateless" in this way.
(The term "stateless" is in quotes here, because it's a bit (The term "stateless" is in quotes here, because it's a bit
oversimplified. Such clients still need to maintain per-server state and other oversimplified. Such clients still need to maintain per-server state and other
kinds of state. So it would be more accurate to kinds of state. So it would be more accurate to
just say that the clients are avoiding per-request state.) just say that the clients are avoiding per-request state.)
</t> </t>
<t> <t>
<xref target="stateless-intermediaries"/> of this document <xref target="stateless-intermediaries" format="default"/> of this docum ent
extends the considerations for clients to intermediaries, which extends the considerations for clients to intermediaries, which
may not only want to avoid keeping state for the requests they may want to avoid keeping state for not only the requests they
send to servers but also for the requests they receive from send to servers but also the requests they receive from
clients. clients.
</t> </t>
<t> <t>
The serialization of state into tokens is limited by the fact The serialization of state into tokens is limited by the fact
that both <xref target="RFC7252">CoAP over UDP</xref> and <xref that both <xref target="RFC7252" format="default">CoAP over UDP</xref> a
target="RFC8323">CoAP over reliable transports</xref> restrict nd <xref target="RFC8323" format="default">CoAP over reliable transports</xref>
restrict
the maximum token length to 8 bytes. To overcome this the maximum token length to 8 bytes. To overcome this
limitation, <xref target="extended-tokens"/> of this document limitation, <xref target="extended-tokens" format="default"/> of this do
first introduces a CoAP protocol extension for extended token cument
introduces a CoAP protocol extension for extended token
lengths. lengths.
</t> </t>
<t> <t>
While the use case (avoiding per-request state) and the mechanism While the use case (avoiding per-request state) and the mechanism
(extended token lengths) presented in this document are closely (extended token lengths) presented in this document are closely
related, both can be used independently of each other: Some 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 be able to fit their state in just 8 bytes; some
implementations may have other use cases for extended token lengths. implementations may have other use cases for extended token lengths.
</t> </t>
<section numbered="true" toc="default">
<section title="Terminology"> <name>Terminology</name>
<t> <t>
In this document, the term "stateless" refers to an implementation In this document, the term "stateless" refers to an implementation
strategy for a client (or intermediary in the client role) that does 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 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 server (or intermediary in the server role). The client still needs to
keep state for each server it communicates with (e.g., for token keep state for each server it communicates with (e.g., for token
generation, message retransmission, and congestion control). generation, message retransmission, and congestion control).
</t> </t>
<t> <t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and >REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
"OPTIONAL" in this document are to be interpreted as described in NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<b
<xref target="RFC2119">BCP 14</xref> <xref target="RFC8174"/> when, cp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
and only when, they appear in all capitals, as shown here. "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document ar
e to be interpreted as
described in BCP&nbsp;14 <xref target="RFC2119"/> <xref target="RFC8174
"/>
when, and only when, they appear in all capitals, as shown here.
</t> </t>
</section> </section>
</section> </section>
<!-- **************************************************************** --> <section anchor="extended-tokens" numbered="true" toc="default">
<!-- **************************************************************** --> <name>Extended Tokens</name>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Extended Tokens" anchor="extended-tokens">
<t> <t>
This document updates the message formats defined for <xref This document updates the message formats defined for <xref target="RFC7
target="RFC7252">CoAP over UDP</xref> and <xref target="RFC8323">CoAP 252" format="default">CoAP over UDP</xref> and <xref target="RFC8323" format="de
over TCP, TLS, and WebSockets</xref> with a new definition of the TKL fault">CoAP
over TCP, TLS, and WebSockets</xref> with a new definition of the "TKL"
field. field.
</t> </t>
<section anchor="tkl-field" numbered="true" toc="default">
<section title="Extended Token Length (TKL) Field" anchor="tkl-field"> <name>Extended Token Length (TKL) Field</name>
<t> <t>
The definition of the TKL field is updated as follows: The definition of the "TKL" field is updated as follows:
<list style="hanging"> </t>
<t hangText="Token Length (TKL):"> <dl newline="false" spacing="normal">
4-bit unsigned integer. A value between 0 and 12 inclusive <dt>Token Length (TKL):</dt>
indicates the length of the variable-length Token field in bytes. <dd>
<t>
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: The other three values are reserved for special constructs:
<list style="hanging"> </t>
<t hangText="13:"> <dl newline="false" spacing="normal" indent="6">
An 8-bit unsigned integer directly precedes the Token field an <dt>13:</dt>
d <dd>
indicates the length of the Token field minus 13. An 8-bit unsigned integer directly precedes the "Token" field
</t> and
<t hangText="14:"> indicates the length of the "Token" field minus 13.
</dd>
<dt>14:</dt>
<dd>
A 16-bit unsigned integer in network byte order directly prece des the A 16-bit unsigned integer in network byte order directly prece des the
Token field and indicates the length of the Token field minus "Token" field and indicates the length of the "Token" field mi nus
269. 269.
</t> </dd>
<t hangText="15:"> <dt>15:</dt>
Reserved. This value MUST NOT be sent and MUST be processed as <dd>
a message format error. Reserved. This value <bcp14>MUST NOT</bcp14> be sent and <bcp1
</t> 4>MUST</bcp14> be processed as
</list> a message-format error.
</t> </dd>
</list> </dl>
</t> </dd>
</dl>
<t> <t>
All other fields retain their definitions. All other fields retain their definitions.
</t> </t>
<t> <t>
The updated message formats are illustrated in <xref The updated message formats are illustrated in <xref target="message-f
target="message-formats"/>. ormats" format="default"/>.
</t> </t>
<t> <t>
The new definition of the TKL field increases the maximum token length that can be represented in a The new definition of the "TKL" field increases the maximum token leng th that can be represented in a
message to 65804 bytes. However, the maximum token length that sender and message to 65804 bytes. However, the maximum token length that sender and
recipient implementations support may be shorter. For example, a recipient implementations support may be shorter. For example, a
constrained node of <xref target="RFC7228">Class 1</xref> might constrained node of <xref target="RFC7228" format="default">Class 1</x ref> might
support extended token lengths only up to 32 bytes. support extended token lengths only up to 32 bytes.
</t> </t>
<t> <t>
In CoAP over UDP, it is often beneficial to keep CoAP messages small In CoAP over UDP, it is often beneficial to keep CoAP messages small
enough to avoid IP fragmentation. The maximum practical token length enough to avoid IP fragmentation. The maximum practical token length
may therefore also be influenced by the Path MTU. See Section 4.6 of may therefore also be influenced by the Path MTU (PMTU). See <xref tar
RFC 7252 for details. get="RFC7252"
sectionFormat="of" section="4.6" /> for details.
</t> </t>
</section> </section>
<section anchor="discovery" numbered="true" toc="default">
<section title="Discovering Support" anchor="discovery"> <name>Discovering Support</name>
<t> <t>
Extended token lengths require support from server implementations. Extended token lengths require support from server implementations.
Support can be discovered by a client implementation in one of two Support can be discovered by a client implementation in one of two
ways: ways:
<list style="symbols"> </t>
<t> <ul spacing="normal">
<li>
Where Capabilities and Settings Messages (CSMs) are available, Where Capabilities and Settings Messages (CSMs) are available,
such as in CoAP over TCP, support can be discovered using the such as in CoAP over TCP, support can be discovered using the
Extended-Token-Length Capability Option defined in <xref Extended-Token-Length Capability Option defined in <xref target="c
target="capability-option"/>. apability-option" format="default"/>.
</t> </li>
<t> <li>
Otherwise, such as in CoAP over UDP, support can only be Otherwise, such as in CoAP over UDP, support can only be
discovered by trial-and-error, as described in <xref discovered by trial and error, as described in <xref target="trial
target="trial-and-error"/>. -and-error" format="default"/>.
</t> </li>
</list> </ul>
</t> <section anchor="capability-option" numbered="true" toc="default">
<name>Extended-Token-Length Capability Option</name>
<section title="Extended-Token-Length Capability Option" anchor="capabil
ity-option">
<t> <t>
A server can use the elective Extended-Token-Length Capability A server can use the elective Extended-Token-Length Capability
Option to indicate the maximum token length it can accept in Option to indicate the maximum token length it can accept in
requests. requests.
</t> </t>
<table anchor="capability-option-definition" align="center">
<texttable title="The Extended-Token-Length Capability Option" anchor= <name>The Extended-Token-Length Capability Option</name>
"capability-option-definition"> <thead>
<ttcol align="right">#</ttcol> <tr>
<ttcol align="left">C</ttcol> <th align="right">#</th>
<ttcol align="left">R</ttcol> <th align="left">C</th>
<ttcol align="left">Applies to</ttcol> <th align="left">R</th>
<ttcol align="left">Name</ttcol> <th align="left">Applies to</th>
<ttcol align="left">Format</ttcol> <th align="left">Name</th>
<ttcol align="left">Length</ttcol> <th align="left">Format</th>
<ttcol align="left">Base Value</ttcol> <th align="left">Length</th>
<th align="left">Base Value</th>
<c>TBD</c> </tr>
<c></c> </thead>
<c></c> <tbody>
<c>CSM</c> <tr>
<c>Extended-Token-Length</c> <td align="right">6</td>
<c>uint</c> <td align="left"/>
<c>0-3</c> <td align="left"/>
<c>8</c> <td align="left">CSM</td>
<td align="left">Extended-Token-Length</td>
<postamble>C=Critical, R=Repeatable</postamble> <td align="left">uint</td>
</texttable> <td align="left">0-3</td>
<td align="left">8</td>
</tr>
</tbody>
</table>
<t keepWithPrevious="true">C=Critical, R=Repeatable</t>
<t> <t>
As per Section 3 of RFC 7252, the base value (and the value used As per <xref target="RFC7252" sectionFormat="of" section="3" />, the base value (and the value used
when this option is not implemented) is 8. when this option is not implemented) is 8.
</t> </t>
<t> <t>
The active value of the Extended-Token-Length Option is replaced The active value of the Extended-Token-Length Option is replaced
each time the option is sent with a modified value. Its starting each time the option is sent with a modified value. Its starting
value is its base value. value is its base value.
</t> </t>
<t> <t>
The option value MUST NOT be less than 8 or greater than 65804. If The option value <bcp14>MUST NOT</bcp14> be less than 8 or greater t
an option value less than 8 is received, the option MUST be ignored. han 65804. If
an option value less than 8 is received, the option <bcp14>MUST</bcp
14> be ignored.
If an option value greater than 65804 is received, the option value If an option value greater than 65804 is received, the option value
MUST be set to 65804. <bcp14>MUST</bcp14> be set to 65804.
</t> </t>
<t> <t>
Any option value greater than 8 implies support for the new Any option value greater than 8 implies support for the new
definition of the TKL field specified in <xref target="tkl-field"/>. definition of the "TKL" field specified in <xref target="tkl-field" format="default"/>.
Indication of support by a server does not oblige a client to Indication of support by a server does not oblige a client to
actually make use of token lengths greater than 8. actually make use of token lengths greater than 8.
</t> </t>
<t> <t>
If a server receives a request with a token of a length greater than what 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 it indicated in its Extended-Token-Length Option, it <bcp14>MUST</bc
request as a message format error. p14> handle the
request as a message-format error.
</t> </t>
<t> <t>
If a server receives a request with a token of a length less than or If a server receives a request with a token of a length less than, o
equal to what it indicated in its Extended-Token-Length Option but r
is unwilling or unable to handle the token at that time, it MUST NOT equal to, what it indicated in its Extended-Token-Length Option but
handle the request as a message format error. Instead, it SHOULD is unwilling or unable to handle the token at that time, it <bcp14>M
UST NOT</bcp14>
handle the request as a message-format error. Instead, it <bcp14>SHO
ULD</bcp14>
return a 5.03 (Service Unavailable) response. return a 5.03 (Service Unavailable) response.
</t> </t>
<t> <t>
The Extended-Token-Length Capability Option does not apply to The Extended-Token-Length Capability Option does not apply to
responses. The sender of a request is simply expected not to use a 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 token of a length greater than it is willing to accept in a
response. response.
</t> </t>
</section> </section>
<section anchor="trial-and-error" numbered="true" toc="default">
<section title="Trial-and-Error" anchor="trial-and-error"> <name>Trial and Error</name>
<t> <t>
A server implementation that does not support the updated definition A server implementation that does not support the updated definition
of the TKL of the "TKL"
field specified in <xref target="tkl-field"/> will consider a field specified in <xref target="tkl-field" format="default"/> will
request with a TKL field value outside the range 0 to 8 a message consider a
format error and reject it (Section 3 of RFC 7252). A client can request with a "TKL" field value outside the range 0 to 8 to be a me
ssage-format error and reject it (<xref target="RFC7252" sectionFormat="of" sect
ion="3" />). A client can
therefore determine support by sending a request with an extended therefore determine support by sending a request with an extended
token length and checking whether it is rejected by the server or token length and checking whether or not it is rejected by the serve
not. r.
</t> </t>
<t> <t>
In CoAP over UDP, the way a request message is rejected depends on t he message type. In CoAP over UDP, the way a request message is rejected depends on t he message type.
A Confirmable message with a message format error A Confirmable message with a message-format error
is rejected with a Reset message (Section 4.2 of RFC 7252). A is rejected with a Reset message (<xref target="RFC7252" sectionForm
Non-confirmable message with a message format error is either reject at="of" section="4.2" />). A
ed Non-confirmable message with a message-format error is either reject
with a Reset message or just silently ignored (Section 4.3 of RFC ed
7252). To reliably get a Reset message, it is therefore REQUIRED tha with a Reset message or just silently ignored (<xref target="RFC7252
t clients use a Confirmable " sectionFormat="of" section="4.3" />). To reliably get a Reset message, it is t
herefore <bcp14>REQUIRED</bcp14> that clients use a Confirmable
message for determining support. message for determining support.
</t> </t>
<t> <t>
As per RFC 7252, Reset messages are empty and do not contain a As per RFC 7252, Reset messages are empty and do not contain a
token; they only return the Message ID (<xref token; they only return the Message ID (<xref target="trial-and-erro
target="trial-and-error-illustration"/>). They also do not contain r-illustration" format="default"/>). They also do not contain
any indication of what caused a message format error. To avoid any any indication of what caused a message-format error. To avoid any
ambiguity, it is therefore RECOMMENDED that clients use a request ambiguity, it is therefore <bcp14>RECOMMENDED</bcp14> that clients u
that has no potential message format error other than the extended se a request
that has no potential message-format error other than the extended
token length. token length.
</t> </t>
<figure anchor="trial-and-error-illustration">
<figure anchor="trial-and-error-illustration" title="A Confirmable Request With <name>A Confirmable Request with an Extended Token Is Rejected with
an Extended Token is Rejected With a Reset Message if the Server Does Not Have S a Reset Message If the Server Does Not Have Support</name>
upport"><artwork align="center"><![CDATA[ <artwork align="center" name="" type="" alt=""><![CDATA[
+-----------------+ request message +------------+ +-----------------+ request message +------------+
| | | with extended | | | | | with extended | |
| | | token length | | | | | token length | |
| .-<-+->------|--------------------->|------. | | .-<-+->------|--------------------->|------. |
| _|_ | | | | | _|_ | | | |
| / \ stored | | | | | / \ stored | | | |
| \___/ state | | | | | \___/ state | | | |
| | | | | | | | | | | |
| '->-+-<------|<---------------------|------' | | '->-+-<------|<---------------------|------' |
| | | reset message | | | | | Reset message | |
| v | with only message | | | v | with only message | |
+-----------------+ ID echoed back +------------+ +-----------------+ ID echoed back +------------+
Client Server Client Server
]]></artwork></figure> ]]></artwork>
</figure>
<t> <t>
An example of a suitable request is a GET request in a Confirmable message that 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 le ngth includes only an If-None-Match option and a token of the greatest le ngth
that the client intends to use. Any response with the same token that the client intends to use. Any response with the same token
echoed back indicates that tokens up to that length are supported by echoed back indicates that tokens up to that length are supported by
the server. the server.
</t> </t>
<t> <t>
Since network addresses may change, a client SHOULD NOT assume that extended token Since network addresses may change, a client <bcp14>SHOULD NOT</bcp1 4> assume that extended token
lengths are supported by a server for an unlimited duration. 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 o f 1800 s, and for a maximum of 86400 s (1 day). Unless additional information is available, the client should assume that addresses (and therefore extended token lengths) are valid for a minimum o f 1800 s and a maximum of 86400 s (1 day).
A client may use additional forms of input into this determination. A client may use additional forms of input into this determination.
For instance a client may assume a server which is in the same subne t as the client has a similar address lifetime as the client. For instance, a client may assume a server that is in the same subne t 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. 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 DN S, then the DNS resource record will have a Time To Live, and the extended token length should be kept for only that amount of time. For servers that are not local, if the server was looked up using DN S, 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.
</t> </t>
<t> <t>
If a server supports extended token lengths but receives a request 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 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 <bcp14>MUST NOT</bcp14> reject the message, as that would imply that extended token
lengths are not supported at all. Instead, if the server cannot lengths are not supported at all. Instead, if the server cannot
handle the request at the time, it SHOULD return a 5.03 (Service handle the request at the time, it <bcp14>SHOULD</bcp14> return a 5. 03 (Service
Unavailable) response; if the server will never be able to handle th e request Unavailable) response; if the server will never be able to handle th e request
(e.g., because the token is too large), it SHOULD return a 4.00 (Bad (e.g., because the token is too large), it <bcp14>SHOULD</bcp14> ret urn a 4.00 (Bad
Request) response. Request) response.
</t> </t>
<aside>
<t> <t>Design Note: The requirement to return an error response when a
<list style="hanging">
<t hangText="Design Note:">
The requirement to return an error response when a
token cannot be handled might seem somewhat contradictory, as token cannot be handled might seem somewhat contradictory, as
returning the error response requires the server also to return the returning the error response requires the server also to return the
token it cannot handle. However, token it cannot handle. However,
processing a request usually involves a number of steps from processing a request usually involves a number of steps from
receiving the message to passing it to application logic. receiving the message to passing it to application logic.
The idea is that a server implementing this extension The idea is that a server implementing this extension
supports large tokens at least in its first few processing steps , enough to supports large tokens at least in its first few processing steps , enough to
return an error response rather than a Reset message. return an error response rather than a Reset message.
</t> </t>
</list> </aside>
</t> <aside>
<t>Design Note: To prevent the trial-and-error-based discovery from b
<t> ecoming too complicated, no effort is made to indicate the maximum supported
<list style="hanging">
<t hangText="Design Note:">
To make the trial-and-error-based discovery not too complicated,
no effort is made to indicate the maximum supported
token length. A client implementation would probably token length. A client implementation would probably
already choose the shortest token possible for the task (like already choose the shortest token possible for the task (such as
being stateless as described in <xref being stateless, as described in <xref target="stateless-clients
target="stateless-clients"/>), so it would probably not be able " format="default"/>), so it would probably not be able
to reduce the length any further anyway should a server to reduce the length any further anyway should a server
indicate a lower limit. indicate a lower limit.
</t> </t>
</list> </aside>
</t>
</section> </section>
</section> </section>
<section anchor="hop-by-hop" numbered="true" toc="default">
<section title="Intermediaries" anchor="hop-by-hop"> <name>Intermediaries</name>
<t> <t>
Tokens are a hop-by-hop feature: If there are one or more 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 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 the exchange between a node in the client role and the node in the
server role that it is immediately interacting with. server role that it is immediately interacting with.
</t> </t>
<t> <t>
When an intermediary receives a request, the only requirement is that When an intermediary receives a request, the only requirement is that
it echoes the token back in any resulting response. There is no it echoes the token back in any resulting response. There is no
requirement or expectation that an intermediary passes a client's requirement or expectation that an intermediary passes a client's
token on to a server or that an intermediary uses extended token token on to a server or that an intermediary uses extended token
lengths itself in its request to satisfy a request with an extended lengths itself in its request to satisfy a request with an extended
token length. Discovery needs to be performed for each hop where exten ded token lengths are to be used. token length. Discovery needs to be performed for each hop where exten ded token lengths are to be used.
</t> </t>
</section> </section>
</section> </section>
<!-- **************************************************************** --> <section anchor="stateless-clients" numbered="true" toc="default">
<!-- **************************************************************** --> <name>Stateless Clients</name>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Stateless Clients" anchor="stateless-clients">
<t> <t>
A client can be alleviated of keeping per-request state as follows: A client can be alleviated of keeping per-request state as follows:
<list style="numbers"> </t>
<t> <ol spacing="normal" type="1"><li>
The client serializes (parts of) its per-request state into The client serializes (parts of) its per-request state into
a sequence of bytes and sends those bytes as the token of a sequence of bytes and sends those bytes as the token of
its request to the server. its request to the server.
</t> </li>
<t> <li>
The server returns the token verbatim in the response to the The server returns the token verbatim in the response to the
client, which allows the client to recover the state and client, which allows the client to recover the state and
process the response as if it had kept the state locally. process the response as if it had kept the state locally.
</t> </li>
</list> </ol>
</t>
<t> <t>
As servers are just expected to return any token verbatim to the As servers are just expected to return any token verbatim to the
client, this implementation strategy for clients does not impact the client, this implementation strategy for clients does not impact the
interoperability of client and server implementations. However, interoperability of client and server implementations. However,
there are a number of significant, non-obvious implications there are a number of significant, nonobvious implications
(e.g., related to security and other CoAP protocol features) (e.g., related to security and other CoAP protocol features)
that client implementations need take into consideration. that client implementations need take into consideration.
</t> </t>
<t> <t>
The following subsections discuss some of these considerations. The following subsections discuss some of these considerations.
</t> </t>
<section anchor="serialized-state" numbered="true" toc="default">
<section title="Serializing Client State" anchor="serialized-state"> <name>Serializing Client State</name>
<t> <t>
The format of the serialized state is generally an The format of the serialized state is generally an
implementation detail of the client and opaque to the server. implementation detail of the client and opaque to the server.
However, serialized state information is an attractive target However, serialized state information is an attractive target
for both unwanted nodes (e.g., on-path attackers) and wanted for both unwanted nodes (e.g., on-path attackers) and wanted
nodes (e.g., any configured forward proxy) on the path. nodes (e.g., any configured forward proxy) on the path.
The serialization format therefore needs to include security The serialization format therefore needs to include security
measures such as the following: measures such as the following:
<list style="symbols"> </t>
<t> <ul spacing="normal">
A client SHOULD protect the integrity of the state information <li>
A client <bcp14>SHOULD</bcp14> protect the integrity of the state
information
serialized in a token. serialized in a token.
</t> </li>
<t> <li>
Even when the integrity of the serialized state is protected, an Even when the integrity of the serialized state is protected, an
attacker may still replay a response, making the client attacker may still replay a response, making the client
believe it sent the same request twice. believe it sent the same request twice.
For this reason, the client SHOULD implement replay For this reason, the client <bcp14>SHOULD</bcp14> implement replay
protection (e.g., by using sequence numbers and a replay protection (e.g., by using sequence numbers and a replay
window). window).
For replay protection, integrity protection is REQUIRED. For replay protection, integrity protection is <bcp14>REQUIRED</bc
</t> p14>.
<t> </li>
<li>
If processing a response without keeping request state is If processing a response without keeping request state is
sensitive to the time elapsed since sending the request, then the sensitive to the time elapsed since sending the request, then the
client SHOULD include freshness information (e.g., a timestamp) in client <bcp14>SHOULD</bcp14> include freshness information (e.g., a timestamp) in
the serialized state and reject any response where the freshness the serialized state and reject any response where the freshness
information is insufficiently fresh. information is insufficiently fresh.
</t> </li>
<t> <li>
Information in the serialized state may be privacy Information in the serialized state may be privacy
sensitive. sensitive.
A client SHOULD encrypt the serialized state if it A client <bcp14>SHOULD</bcp14> encrypt the serialized state if it
contains privacy sensitive information that an attacker contains privacy-sensitive information that an attacker
would not get otherwise. would not get otherwise.
</t> </li>
<t> <li>
When a client changes the format of the serialized state, When a client changes the format of the serialized state,
it SHOULD prevent false interoperability with the previous it <bcp14>SHOULD</bcp14> prevent false interoperability with the p revious
format (e.g., by changing the key used for integrity format (e.g., by changing the key used for integrity
protection or changing a field in the serialized state). protection or changing a field in the serialized state).
</t> </li>
</list> </ul>
</t>
</section> </section>
<section numbered="true" toc="default">
<section title="Using Extended Tokens"> <name>Using Extended Tokens</name>
<t> <t>
A client that depends on A client that depends on
support for extended token lengths (<xref target="extended-tokens"/>) support for extended token lengths (<xref target="extended-tokens" for mat="default"/>)
from the server to avoid keeping request state needs to perform a from the server to avoid keeping request state needs to perform a
discovery of support (<xref target="discovery"/>) before it can be discovery of support (<xref target="discovery" format="default"/>) bef ore it can be
stateless. stateless.
</t> </t>
<t> <t>
This discovery MUST be performed in a stateful way, i.e., This discovery <bcp14>MUST</bcp14> be performed in a stateful way, i.e
keeping state for the request (<xref target="stateful-discovery"/>): .,
If the client was stateless from the start and the server does not keeping state for the request (<xref target="stateful-discovery" forma
support extended tokens, then any error message could not be processed t="default"/>).
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 since the state would neither be present at the client nor returned in
the Reset message (<xref target="stateless-discovery"/>). the Reset message (<xref target="stateless-discovery" format="default" />).
</t> </t>
<figure anchor="stateful-discovery">
<figure anchor="stateful-discovery" title="Depending on Extended Tokens for Bein <name>Depending on Extended Tokens for Being Stateless First Requires
g Stateless First Requires a Successful Stateful Discovery of Support"><artwork a Successful Stateful Discovery of Support</name>
align="center"><![CDATA[ <artwork align="center" name="" type="" alt=""><![CDATA[
+-----------------+ dummy request +------------+ +-----------------+ dummy request +------------+
| | | with extended | | | | | with extended | |
| | | token | | | | | token | |
| .-<-+->------|=====================>|------. | | .-<-+->------|=====================>|------. |
| _|_ | | | | | _|_ | | | |
| / \ stored | | | | | / \ stored | | | |
| \___/ state | | | | | \___/ state | | | |
| | | | | | | | | | | |
| '->-+-<------|<=====================|------' | | '->-+-<------|<=====================|------' |
| | | response with | | | | | response with | |
skipping to change at line 644 skipping to change at line 553
| +--------|=====================>|------. | | +--------|=====================>|------. |
| | | | | | | | | |
| look ma, | | | | | look ma, | | | |
| no state! | | | | | no state! | | | |
| | | | | | | | | |
| +--------|<=====================|------' | | +--------|<=====================|------' |
| | | response with | | | | | response with | |
| v | token echoed back | | | v | token echoed back | |
+-----------------+ +------------+ +-----------------+ +------------+
Client Server Client Server
]]></artwork></figure> ]]></artwork>
</figure>
<figure anchor="stateless-discovery" title="Stateless Discovery of Support Does <figure anchor="stateless-discovery">
Not Work"><artwork align="center"><![CDATA[ <name>Stateless Discovery of Support Does Not Work</name>
<artwork align="center" name="" type="" alt=""><![CDATA[
+-----------------+ dummy request +------------+ +-----------------+ dummy request +------------+
| | | with extended | | | | | with extended | |
| | | token | | | | | token | |
| +--------|=====================>|------. | | +--------|=====================>|------. |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| ???|<---------------------|------' | | ???|<---------------------|------' |
| | reset message | | | | Reset message | |
| | with only message | | | | with only message | |
+-----------------+ ID echoed back +------------+ +-----------------+ ID echoed back +------------+
Client Server Client Server
]]></artwork></figure> ]]></artwork>
</figure>
<t> <t>
In environments where support can be reliably discovered through some In environments where support can be reliably discovered through some
other means, the discovery of support is OPTIONAL. An example for this other means, the discovery of support is <bcp14>OPTIONAL</bcp14>. An e
is the <xref target="I-D.ietf-6tisch-minimal-security">Constrained xample for this
is the <xref target="I-D.ietf-6tisch-minimal-security" format="default
">Constrained
Join Protocol (CoJP) in a 6TiSCH network</xref>, where support for Join Protocol (CoJP) in a 6TiSCH network</xref>, where support for
extended tokens is required from all relevant parties. extended tokens is required from all relevant parties.
</t> </t>
</section> </section>
<section numbered="true" toc="default">
<section title="Transmitting Messages"> <name>Transmitting Messages</name>
<t> <t>
In <xref target="RFC7252">CoAP over UDP</xref>, a client has the choic e between In <xref target="RFC7252" format="default">CoAP over UDP</xref>, a cli ent has the choice between
Confirmable and Non-confirmable messages for requests. When using Confirmable and Non-confirmable messages for requests. When using
Non-confirmable messages, a client does not have to keep any message Non-confirmable messages, a client does not have to keep any message-e
exchange state, which can help in the goal of avoiding state. When usi xchange state, which can help in the goal of avoiding state. When using
ng Confirmable messages, a client needs to keep message-exchange
Confirmable messages, a client needs to keep message exchange
state for performing retransmissions and handling Acknowledgement and state for performing retransmissions and handling Acknowledgement and
Reset messages, however. Non-confirmable messages are therefore better suited for avoiding state. 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., 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 maintain state for each node it communicates with and enforce limits
like NSTART. like NSTART.
</t> </t>
<t> <t>
As per Section 5.2 of RFC 7252, a client must be prepared to receive a As per <xref target="RFC7252" sectionFormat="of" section="5.2" />, a c
response as a lient must be prepared to receive a response as a
piggybacked response, a separate response, or Non-confirmable response piggybacked response, a separate response, or a Non-confirmable respon
, se,
regardless of the message type used for the regardless of the message type used for the
request. A stateless client MUST handle these response types as request. A stateless client <bcp14>MUST</bcp14> handle these response types as
follows: follows:
<list style="symbols"> </t>
<t> <ul spacing="normal">
<li>
If a piggybacked response passes the checks for token integrity If a piggybacked response passes the checks for token integrity
and freshness (<xref target="serialized-state"/>), the client proc esses the message as and freshness (<xref target="serialized-state" format="default"/>) , the client processes the message as
specified in RFC 7252; otherwise, it processes the acknowledgement specified in RFC 7252; otherwise, it processes the acknowledgement
portion of the message as specified in RFC 7252 and silently portion of the message as specified in RFC 7252 and silently
discards the response portion. discards the response portion.
</t> </li>
<t> <li>
If a separate response passes the checks for token integrity and If a separate response passes the checks for token integrity and
freshness, the client processes the message as specified in freshness, the client processes the message as specified in
RFC 7252; otherwise, it rejects the message as specified in RFC 7252; otherwise, it rejects the message as specified in <xref
Section 4.2 of RFC 7252. target="RFC7252" sectionFormat="of" section="4.2" />.
</t> </li>
<t> <li>
If a Non-confirmable response passes the checks for token If a Non-confirmable response passes the checks for token
integrity and freshness, the client processes the message integrity and freshness, the client processes the message
as specified in RFC 7252; otherwise, it rejects the message as as specified in RFC 7252; otherwise, it rejects the message as
specified in Section 4.3 of RFC 7252. specified in <xref target="RFC7252" sectionFormat="of" section="4.
</t> 3" />.
</list> </li>
</t> </ul>
</section> </section>
</section> </section>
<section anchor="stateless-intermediaries" numbered="true" toc="default">
<section title="Stateless Intermediaries" anchor="stateless-intermediaries"> <name>Stateless Intermediaries</name>
<t> <t>
Tokens are a hop-by-hop feature: If a client makes a request to an 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 intermediary, that intermediary needs to store the client's token
(along with the client's transport address) while it makes its own (along with the client's transport address) while it makes its own
request towards the origin server and waits for the request towards the origin server and waits for the
response. When the intermediary receives the response, it looks up response. When the intermediary receives the response, it looks up
the client's token and transport address for the received request and the client's token and transport address for the received request and
sends an appropriate response to the client. sends an appropriate response to the client.
</t> </t>
<t> <t>
An intermediary might want to be "stateless" not only in its role as 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 a client but also in its role as a server, i.e., be
alleviated of storing the client information for alleviated of storing the client information for
the requests it receives. the requests it receives.
</t> </t>
<t> <t>
Such an intermediary can be implemented by serializing the Such an intermediary can be implemented by serializing the
client information along with the request state into the token towards t he origin server. client information along with the request state into the token towards t he origin server.
When the intermediary receives the response, it can recover When the intermediary receives the response, it can recover
the client information from the token and use it to satisfy the client's the client information from the token and use it to satisfy the client's
request and therefore doesn't need to store it itself. request; therefore, the intermediary doesn't need to store the informati on itself.
</t> </t>
<t> <t>
The following subsections discuss some considerations for this approach. The following subsections discuss some considerations for this approach.
</t> </t>
<section numbered="true" toc="default">
<section title="Observing Resources"> <name>Observing Resources</name>
<t> <t>
One drawback of the approach is that an intermediary, without keeping One drawback of the approach is that an intermediary, without keeping
request state, is unable to aggregate multiple requests for the same request state, is unable to aggregate multiple requests for the same
target resource, which can significantly reduce efficiency. In target resource, which can significantly reduce efficiency. In
particular, when clients <xref target="RFC7641">observe</xref> the particular, when clients observe <xref target="RFC7641" format="defaul
same resource, aggregating requests is REQUIRED (Section 3.1 of RFC t"></xref> the
7641). This requirement cannot be satisfied without keeping request same resource, aggregating requests is <bcp14>REQUIRED</bcp14> (<xref
target="RFC7641" sectionFormat="of" section="3.1" />). This requirement cannot b
e satisfied without keeping request
state. state.
</t> </t>
<t> <t>
Furthermore, an intermediary that does not keep track of the clients Furthermore, an intermediary that does not keep track of the clients
observing a resource is not able to determine whether these observing a resource is not able to determine whether these
clients are still interested in receiving further notifications clients are still interested in receiving further notifications
(Section 3.5 of RFC 7641) or want to cancel an observation (Section 3. (<xref target="RFC7641" sectionFormat="of" section="3.5" />) or want t
6 of o cancel an observation (<xref target="RFC7641" sectionFormat="of" section="3.6"
RFC 7641). />).
</t> </t>
<t> <t>
Therefore, an intermediary MUST NOT include an Observe Option in Therefore, an intermediary <bcp14>MUST NOT</bcp14> include an Observe Option in
requests it sends without keeping both the request state for the reque sts it sends and the requests it sends without keeping both the request state for the reque sts it sends and the
client information for the requests it receives. client information for the requests it receives.
</t> </t>
</section> </section>
<section numbered="true" toc="default">
<section title="Block-Wise Transfers"> <name>Block-Wise Transfers</name>
<t> <t>
When using <xref target="RFC7959">block-wise transfers</xref>, a When using <xref target="RFC7959" format="default">block-wise transfer s</xref>, a
server might not be able to distinguish blocks originating from server might not be able to distinguish blocks originating from
different clients once they have been forwarded by an intermediary. different clients once they have been forwarded by an intermediary.
Intermediaries need to ensure that this does not lead to inconsistent Intermediaries need to ensure that this does not lead to inconsistent
resource state by keeping distinct block-wise request operations on resource state by keeping distinct block-wise request operations on
the same resource apart, e.g., utilizing the <xref the same resource apart, e.g., utilizing the <xref target="I-D.ietf-co
target="I-D.ietf-core-echo-request-tag">Request-Tag Option</xref>. re-echo-request-tag" format="default">Request-Tag Option</xref>.
</t> </t>
</section> </section>
<section numbered="true" toc="default">
<section title="Gateway Timeouts"> <name>Gateway Timeouts</name>
<t> <t>
As per Section 5.7.1 of RFC 7252, an intermediary is REQUIRED to As per <xref target="RFC7252" sectionFormat="of" section="5.7.1" />, a n intermediary is <bcp14>REQUIRED</bcp14> to
return a 5.04 (Gateway Timeout) response if it cannot obtain a return a 5.04 (Gateway Timeout) response if it cannot obtain a
response within a timeout. However, if an intermediary does not keep response within a timeout. However, if an intermediary does not keep
the client information for the requests it receives, it cannot return 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. Therefore, in this case, the gateway cannot return
such a response and as such cannot implement such a timeout. such a response and as such cannot implement such a timeout.
</t> </t>
</section> </section>
<section numbered="true" toc="default">
<section title="Extended Tokens"> <name>Extended Tokens</name>
<t> <t>
A client may make use of extended token lengths in a request to an 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 int ermediary intermediary that wants to be "stateless". This means that such an int ermediary
may have to serialize potentially very large client information into may have to serialize potentially very large client information into
its token towards the origin server. The tokens can grow even further 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 when it progresses along a chain of intermediaries that all want to be
"stateless". "stateless".
</t> </t>
<t> <t>
Intermediaries SHOULD limit the size of client information they are Intermediaries <bcp14>SHOULD</bcp14> limit the size of client informat ion they are
serializing into their own tokens. An intermediary can do this, for serializing into their own tokens. An intermediary can do this, for
example, by limiting the extended token lengths it accepts from its example, by limiting the extended token lengths it accepts from its
clients (see <xref target="discovery"/>) or by keeping the client clients (see <xref target="discovery" format="default"/>) or by keepin g the client
information locally when the client information exceeds the limit information locally when the client information exceeds the limit
(i.e., not being "stateless"). (i.e., not being "stateless").
</t> </t>
</section> </section>
</section> </section>
<!-- **************************************************************** --> <section anchor="security" numbered="true" toc="default">
<!-- **************************************************************** --> <name>Security Considerations</name>
<!-- **************************************************************** --> <section numbered="true" toc="default">
<!-- **************************************************************** --> <name>Extended Tokens</name>
<section title="Security Considerations" anchor="security">
<section title="Extended Tokens">
<t> <t>
Tokens significantly larger than the 8 bytes specified in RFC 7252 Tokens significantly larger than the 8 bytes specified in RFC 7252
have implications in particular for nodes with constrained memory size have implications -- in particular, for nodes with constrained memory size --
that need to be mitigated. A node in the server role supporting that need to be mitigated. A node in the server role supporting
extended token lengths may be vulnerable to a denial-of-service when extended token lengths may be vulnerable to a denial of service when
an attacker (either on-path or a malicious client) sends large tokens 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 fill up the memory of the node. Implementations need to be prepared
to handle such messages. to handle such messages.
</t> </t>
</section> </section>
<section numbered="true" toc="default">
<section title="Stateless Clients and Intermediaries"> <name>Stateless Clients and Intermediaries</name>
<t> <t>
Transporting the state needed by a client to process a response as Transporting the state needed by a client to process a response as
serialized state information in the token has several significant and serialized state information in the token has several significant and
non-obvious security and privacy implications that need to be nonobvious security and privacy implications that need to be
mitigated; see <xref target="serialized-state"/> for recommendations. mitigated; see <xref target="serialized-state" format="default"/> for
recommendations.
</t> </t>
<t> <t>
In addition to the format requirements outlined there, implementations In addition to the format requirements outlined there, implementations
need to ensure that they are not vulnerable to maliciously crafted, need to ensure that they are not vulnerable to maliciously crafted,
delayed, or replayed tokens. delayed, or replayed tokens.
</t> </t>
<t> <t>
It is generally expected that the use of encryption, integrity It is generally expected that the use of encryption, integrity
protection, and replay protection for serialized state is protection, and replay protection for serialized state is
appropriate. appropriate.
</t> </t>
<t> <t>
In the absence of integrity and replay protection, an on-path attacker In the absence of integrity and replay protection, an on-path attacker
or rogue server/intermediary could return a state (either one modified or rogue server/intermediary could return a state (either one modified
in a reply, or an unsolicited one) that could alter the internal state in a reply, or an unsolicited one) that could alter the internal state
of the client. of the client.
</t> </t>
<t> <t>
It is for this reason that at least the use of integrity protection on It is for this reason that at least the use of integrity protection on
the token is always recommended. the token is always recommended.
</t> </t>
<t> <t>
It maybe that in some very specific case, as a result of a careful It may be that in some very specific cases, as a result of a careful
and detailed analysis of any potential attacks, that there may be cas and detailed analysis of any potential attacks, it is decided that suc
es h cryptographic protections do not add value.
where such cryptographic protections do not add value.
The authors of this document have not found such a use case as yet, bu t this The authors of this document have not found such a use case as yet, bu t this
is a local decision. is a local decision.
</t> </t>
<t> <t>
It should further be emphasized that the encrypted state is created by the It should further be emphasized that the encrypted state is created by the
sending node, and decrypted by the same node when receiving a sending node and decrypted by the same node when receiving a
response. response.
The key is not shared with any other system. The key is not shared with any other system.
Therefore the choice of encryption scheme and the generation of the ke y for Therefore, the choice of encryption scheme and the generation of the k ey for
this system is purely a local matter. this system is purely a local matter.
</t> </t>
<t> <t>
When encryption is used, the use of <xref When encryption is used, the use of <xref target="RFC3610" format="def
target="RFC3610">AES-CCM</xref> with a 64-bit tag is recommended, ault">AES-CCM</xref> with a 64-bit tag is recommended,
combined with a sequence number and a replay window. combined with a sequence number and a replay window.
This choice is informed by available hardware acceleration of on This choice is informed by available hardware acceleration of on
many constrained systems. many constrained systems.
If a different algorithm is available accelerated on the sender, If a different algorithm is available accelerated on the sender,
with similar or stronger strength, then it SHOULD be preferred. with similar or stronger strength, then it <bcp14>SHOULD</bcp14> be pr eferred.
Where privacy of the state is not required, and encryption is not need Where privacy of the state is not required, and encryption is not need
ed, <xref ed, <xref target="RFC6234" format="default">HMAC-SHA-256</xref>, combined with a
target="RFC6234">HMAC-SHA-256</xref>, combined with a sequence number sequence number
and a replay window, may be used. and a replay window, may be used.
</t> </t>
<t> <t>
This size of the replay window depends upon the number of This size of the replay window depends upon the number of
requests that need to be outstanding. This can be requests that need to be outstanding. This can be
determined from the rate at which new ones are made, and the determined from the rate at which new ones are made and the
expected duration in which responses are expected. expected time period during which responses are expected.
</t> </t>
<t> <t>
For instance, given a CoAP MAX_TRANSMIT_WAIT of 93 s (Section 4.8.2 of <xref target="RFC7252"/>, any request that is not answered within 93 s will For instance, given a CoAP MAX_TRANSMIT_WAIT of 93 s (<xref target="RF C7252" sectionFormat="of" section="4.8.2"/>), any request that is not answered w ithin 93 s will
be considered to have failed. At a request rate of be considered to have failed. At a request rate of
one request per 10 s, at most 10 (ceil(9.3)) requests can be 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 outstanding at a time, and any convenient replay window larger than
20 will work. As replay windows are often implemented with a 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 sliding window and a bit, the use of a 32-bit window would be
sufficient. sufficient.
</t> </t>
<t> <t>
For use cases where requests are being relayed from another node, For use cases where requests are being relayed from another node,
the request rate may be estimated by the total link capacity the request rate may be estimated by the total link capacity
allocated for that kind of traffic. An alternate view would allocated for that kind of traffic. An alternate view would
consider how many IPv6 Neighbor Cache Entries (NCEs) the system can consider how many IPv6 Neighbor Cache Entries (NCEs) the system can
afford to allocate for this use. afford to allocate for this use.
</t> </t>
<t> <t>
When using an encryption mode that depends on a nonce, such as When using an encryption mode that depends on a nonce, such as
AES-CCM, repeated use of the same nonce under the same key AES-CCM, repeated use of the same nonce under the same key
causes the cipher to fail catastrophically. causes the cipher to fail catastrophically.
</t> </t>
<t> <t>
If a nonce is ever used for more than one encryption operation with 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 plain texts and the the same key, then the same key stream gets used to encrypt both plain texts, and the
confidentiality guarantees are voided. Devices with low-quality entrop y confidentiality guarantees are voided. Devices with low-quality entrop y
sources -- as is typical with constrained devices, which incidentally sources -- as is typical with constrained devices, which incidentally
happen to be a natural candidate for the stateless mechanism described happen to be a natural candidate for the stateless mechanism described
in this document -- need to carefully pick a nonce generation in this document -- need to carefully pick a nonce-generation
mechanism that provides the above uniqueness guarantee. mechanism that provides the above uniqueness guarantee.
</t> </t>
<t> <t>
<xref target="RFC8613" /> appendix B.1.1 ("Sender Sequence Number") <xref target="RFC8613"/>, Appendix B.1.1 ("Sender Sequence Number")
provides a model for how to maintain non-repeating nonces without provides a model for how to maintain nonrepeating nonces without
causing excessive wear of flash memory. causing excessive wear of flash memory.
</t> </t>
</section> </section>
</section> </section>
<!-- **************************************************************** --> <section numbered="true" toc="default">
<!-- **************************************************************** --> <name>IANA Considerations</name>
<!-- **************************************************************** --> <section numbered="true" toc="default">
<!-- **************************************************************** --> <name>CoAP Signaling Option Number</name>
<section title="IANA Considerations">
<section title="CoAP Signaling Option Number">
<t> <t>
The following entries are added to the "CoAP Signaling Option Numbers" The following entry has been added to the "CoAP Signaling Option Numbe rs"
registry within the "CoRE Parameters" registry. registry within the "CoRE Parameters" registry.
</t> </t>
<table align="center">
<texttable> <name>CoAP Signalling Option Number</name>
<ttcol align="left">Applies to</ttcol> <thead>
<ttcol align="right">Number</ttcol> <tr>
<ttcol align="left">Name</ttcol> <th align="left">Applies to</th>
<ttcol align="left">Reference</ttcol> <th align="right">Number</th>
<th align="left">Name</th>
<c>7.01</c> <th align="left">Reference</th>
<c>TBD</c> </tr>
<c>Extended-Token-Length</c> </thead>
<c>[[this document]]</c> <tbody>
</texttable> <tr>
<td align="left">7.01</td>
<td align="right">6</td>
<td align="left">Extended-Token-Length</td>
<td align="left">RFC 8974</td>
</tr>
</tbody>
</table>
<t> <t>
[[NOTE TO RFC EDITOR: Please replace "TBD" in this section and in
<xref target="capability-option-definition"/> with the code point
assigned by IANA.]]
</t> </t>
</section> </section>
</section> </section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
</middle> </middle>
<back> <back>
<!-- **************************************************************** --> <displayreference target="I-D.ietf-core-echo-request-tag" to="ECHO-REQUEST-TAG"/
<!-- **************************************************************** --> >
<!-- **************************************************************** --> <displayreference target="I-D.ietf-6tisch-minimal-security" to="6TISCH-MIN-SEC"/
<!-- **************************************************************** --> >
<references title="Normative References">
&RFC2119;
&RFC7252;
&RFC7641;
&RFC7959;
&RFC8174;
&RFC8323;
</references>
<references title="Informative References"> <references>
<name>References</name>
<references>
<name>Normative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.2119.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.7252.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.7641.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.7959.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.8174.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.8323.xml"/>
</references>
<references>
<name>Informative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.3610.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.6234.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.7228.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.8613.xml"/>
&RFC3610; <!-- [I-D.ietf-core-echo-request-tag] IESG state - Waiting for AD Go-Ahead::AD F
&RFC6234; ollowup -->
&RFC7228;
<?rfc include="reference.RFC.8613" ?>
&I-D.ietf-core-echo-request-tag; <xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D .ietf-core-echo-request-tag.xml"/>;
&I-D.ietf-6tisch-minimal-security; <!-- [I-D.ietf-6tisch-minimal-security] in MISSREF state as of 12/5/20 -->;
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/reference.I-D
.ietf-6tisch-minimal-security.xml"/>
</references>
</references> </references>
<!-- **************************************************************** --> <section anchor="message-formats" numbered="true" toc="default">
<!-- **************************************************************** --> <name>Updated Message Formats</name>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Updated Message Formats" anchor="message-formats">
<t> <t>
In <xref target="extended-tokens"/>, this document updates the In <xref target="extended-tokens" format="default"/>, this document upda
CoAP message formats by specifying a new definition of the TKL tes the
CoAP message formats by specifying a new definition of the "TKL"
field in the message header. As an alternative presentation of field in the message header. As an alternative presentation of
this update, this appendix shows the CoAP message formats for this update, this appendix shows the CoAP message formats for
<xref target="RFC7252">CoAP over UDP</xref> and <xref <xref target="RFC7252" format="default">CoAP over UDP</xref> and <xref t
target="RFC8323">CoAP over TCP, TLS, and WebSockets</xref> with arget="RFC8323" format="default">CoAP over TCP, TLS, and WebSockets</xref> with
the new definition applied. the new definition applied.
</t> </t>
<section numbered="true" toc="default">
<section title="CoAP over UDP"> <name>CoAP over UDP</name>
<artwork align="center" name="" type="" alt=""><![CDATA[
<figure><artwork align="center"><![CDATA[
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+-------+-------+---------------+ +-------+-------+---------------+
| | | | | | | |
| Ver | T | TKL | 1 byte | Ver | T | TKL | 1 byte
| | | | | | | |
+-------+-------+---------------+ +-------+-------+---------------+
| | | |
| Code | 1 byte | Code | 1 byte
| | | |
+-------------------------------+ +-------------------------------+
skipping to change at line 1102 skipping to change at line 953
| | | | | |
+---------------+---------------+ +---------------+---------------+
\ \ \ \
/ / / /
\ \ \ \
/ Payload / 0 or more bytes / Payload / 0 or more bytes
\ \ \ \
/ / / /
\ \ \ \
+-------------------------------+ +-------------------------------+
]]></artwork></figure> ]]></artwork>
</section> </section>
<section numbered="true" toc="default">
<section title="CoAP over TCP/TLS"> <name>CoAP over TCP/TLS</name>
<artwork align="center" name="" type="" alt=""><![CDATA[
<figure><artwork align="center"><![CDATA[
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+---------------+---------------+ +---------------+---------------+
| | | | | |
| Len | TKL | 1 byte | Len | TKL | 1 byte
| | | | | |
+---------------+---------------+ +---------------+---------------+
\ \ \ \
/ Len / 0-4 bytes / Len / 0-4 bytes
\ (extended) \ \ (extended) \
+-------------------------------+ +-------------------------------+
skipping to change at line 1151 skipping to change at line 1000
| | | | | |
+---------------+---------------+ +---------------+---------------+
\ \ \ \
/ / / /
\ \ \ \
/ Payload / 0 or more bytes / Payload / 0 or more bytes
\ \ \ \
/ / / /
\ \ \ \
+-------------------------------+ +-------------------------------+
]]></artwork></figure> ]]></artwork>
</section> </section>
<section numbered="true" toc="default">
<section title="CoAP over WebSockets"> <name>CoAP over WebSockets</name>
<artwork align="center" name="" type="" alt=""><![CDATA[
<figure><artwork align="center"><![CDATA[
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+---------------+---------------+ +---------------+---------------+
| | | | | |
| 0 | TKL | 1 byte | 0 | TKL | 1 byte
| | | | | |
+---------------+---------------+ +---------------+---------------+
| | | |
| Code | 1 byte | Code | 1 byte
| | | |
+-------------------------------+ +-------------------------------+
skipping to change at line 1196 skipping to change at line 1043
| | | | | |
+---------------+---------------+ +---------------+---------------+
\ \ \ \
/ / / /
\ \ \ \
/ Payload / 0 or more bytes / Payload / 0 or more bytes
\ \ \ \
/ / / /
\ \ \ \
+-------------------------------+ +-------------------------------+
]]></artwork></figure> ]]></artwork>
</section> </section>
</section> </section>
<!-- **************************************************************** --> <section numbered="false" toc="default">
<!-- **************************************************************** --> <name>Acknowledgements</name>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Acknowledgements" numbered="no">
<t> <t>
This document is based on the requirements of and work on the <xref This document is based on the requirements of, and work on, "Constrained
target="I-D.ietf-6tisch-minimal-security">Minimal Security Framework for Join Protocol (CoJP) for 6TiSCH" (January 2020) by <contact fullname="Mališa Vu
6TiSCH</xref> by Malisa Vucinic, Jonathan Simon, Kris Pister, and činić"/>, <contact fullname="Jonathan Simon"/>, <contact fullname="Kris Pister"/
Michael Richardson. >, and
<contact fullname="Michael Richardson"/>.
</t> </t>
<!-- sorted by last name -->
<t> <t>
Thanks to Thanks to
Christian Amsuss, <contact fullname="Christian Amsüss"/>,
Carsten Bormann, <contact fullname="Carsten Bormann"/>,
Roman Danyliw, <contact fullname="Roman Danyliw"/>,
Christer Holmberg, <contact fullname="Christer Holmberg"/>,
Benjamin Kaduk, <contact fullname="Benjamin Kaduk"/>,
Ari Keranen, <contact fullname="Ari Keränen"/>,
Erik Kline, <contact fullname="Erik Kline"/>,
Murray Kucherawy, <contact fullname="Murray Kucherawy"/>,
Warren Kumari, <contact fullname="Warren Kumari"/>,
Barry Leiba, <contact fullname="Barry Leiba"/>,
David Mandelberg, <contact fullname="David Mandelberg"/>,
Dan Romascanu, <contact fullname="Dan Romascanu"/>,
Jim Schaad, <contact fullname="Jim Schaad"/>,
Goran Selander, <contact fullname="Göran Selander"/>,
Malisa Vucinic, <contact fullname="Mališa Vučinić"/>,
Eric Vyncke, and <contact fullname="Éric Vyncke"/>, and
Robert Wilton <contact fullname="Robert Wilton"/>
for helpful comments and discussions that have shaped the document. for helpful comments and discussions that have shaped the document.
</t> </t>
<t> <t>
Special thanks to John Mattsson for his contributions to the security Special thanks to <contact fullname="John Mattsson"/> for his contributi
considerations of the document, and to Thomas Fossati for his in-depth ons to the security considerations of the document, and to <contact fullname="Th
review, copious comments, and suggested text. omas Fossati"/> for his in-depth review, copious comments, and suggested text.
</t> </t>
</section> </section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
</back> </back>
</rfc> </rfc>
 End of changes. 234 change blocks. 
593 lines changed or deleted 474 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/